Configure and Use Salt Cloud and Cloud Maps to Provision Systems

Updated Friday, April 17, 2020 by Linode Contributed by Sergey Bulavintsev

Contribute on GitHub

Salt Cloud

What is Salt Cloud?

Salt Cloud is a configuration management tool that allows users to provision systems on cloud hosts or hypervisors. During installation, Salt Cloud installs Salt on all provisioned systems by default. This enables the user to put systems into the desired state during provisioning.

Salt Cloud:

Helps gather information on your systems and manage their lifecycle through a Command Line Interface (CLI).
Supports Linode as a provider out of the box. You do not have to install any additional plugins.

This guide shows how to install Salt Cloud and configure it to work on a Linode.

Before You Begin

Create a management server which will be used to create and manage your Linode servers. You can host the management server remotely on a Linode, or on a local machine. The only condition is that it is capable of installing and executing Salt Cloud.
This guide assumes that Salt Cloud will be installed together with Salt master server.
Generate an API key to access Linode API. Salt Cloud currently requires a v3 key generated from the Linode Manager and not the new Cloud Manager. This key will be used by Salt Cloud to manage your instances. Make sure to keep your API key safe. Test your API key is working via the REST interface:
```
curl "https://api.linode.com/?api_key=SECRETKEYHERE&api_action=test.echo&foo=bar"
```
The management server must have access to the Linode API (non-proxy internet access).

Install Salt and Salt Cloud via Bootstrap Script

The recommended way to install Salt Cloud is with a Salt Bootstrap script. This script will install Salt, Salt Cloud packages, and all required dependencies. Run the script with the -h flag to view the additional options available, or refer to Salt Bootstrap Guide for detailed instructions.

Download the Salt Bootstrap script via curl:

curl -o bootstrap-salt.sh -L https://bootstrap.saltstack.com

Execute the script and use the -L option to install Salt and Salt Cloud:
```
sh bootstrap-salt.sh -L
```

Configure Salt Cloud

Set up Provider Configuration:

Configure and test access to the Linode API.

Edit /etc/salt/cloud.providers.d/linode.conf to configure the name of your provider configuration. Salt Cloud will use it during operations with instances in the CLI. Use a short name (or abbreviation like li) that will be easy to remember. You can also specify multiple Linode providers for managing multiple accounts. Linode requires the default root password for the new servers to be set. This password needs to be eight characters and contain lowercase, uppercase, and numbers.
/etc/salt/cloud.providers.d/linode.conf
1 2 3 4

linode-provider: apikey: <Your API key> password: <Default password for the new instances> driver: linode
Note
All configuration files store data in YAML format. Be careful with indentation - use only spaces and not tabs. Each level of indentation is usually separated with 2 spaces.

Test access to the Linode API:

Execute the following command from your master to test access to the Linode API:

salt-cloud --list-locations linode-provider

If you have set up the connection to Linode properly, you will see output similar to:

linode_provider:
    ----------
    linode:
        ----------
        Atlanta, GA, USA:
            ----------
            ABBR:
                atlanta
            DATACENTERID:
                4
            LOCATION:
                Atlanta, GA, USA

Create a New Salt Cloud Instance

List Available Locations, Images and Sizes

Before creating new instances, specify instance size: amount of system memory, CPU, and storage; location: physical location of data center; and image: operating system.

You can obtain this information with the following commands:

Available locations:

salt-cloud --list-locations linode-provider

Available sizes:

salt-cloud --list-sizes linode-provider

Available images:

salt-cloud --list-images linode-provider

Set up Profile Configuration

Create an instance profile. In this profile you describe a server which will be created on your Linode account. Minimal configuration should include provider, size, image and location.

For this example, create an instance with minimal size, using a CentOS 7 image, located in London.

Open /etc/salt/cloud.profiles.d/linode-london-1gb.conf and paste the following:
/etc/salt/cloud.profiles.d/linode-london-1gb.conf
1 2 3 4 5

linode_1gb: provider: linode-provider size: Nanode 1GB image: CentOS 7 location: London, England, UK
You can use one file for all profiles, or use one file per instance profile. All files from /etc/salt/cloud.profiles.d/ are read during execution.
By default, Salt Cloud will install Salt Minion on all provisioned servers. To allow provisioned systems to connect to the master, set the default master configuration for all provisioned systems.

Edit /etc/salt/cloud.conf.d/master.conf and paste the following content, replacing saltmaster.example.com with the IP address or domain name of your master server:
/etc/salt/cloud.conf.d/master.conf
1 2

minion: master: saltmaster.example.com
Another option is to set this parameter for specific instance profile:
/etc/salt/cloud.profiles.d/linode-london-1gb.conf
1 2 3 4 5 6 7

linode_1gb_with_master: provider: linode-provider size: Nanode 1GB image: CentOS 7 location: London, England, UK minion: master: mymaster.example.com

Set up SSH key authentication for your instance. To do this during provisioning, set up the profile as follows, replacing the ssh_pubkey and ssh_key_file with key information for an SSH key on your master server:

/etc/salt/cloud.profiles.d/linode-london-1gb.conf

1
2
3
4
5
6
7


linode_1gb_with_ssh_key:
  provider: linode-provider
  size: Nanode 1GB
  image: CentOS 7
  location: London, England, UK
  ssh_pubkey: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHEOLLbeXgaqRQT9NBAopVz366SdYc0KKX33vAnq+2R user@host
  ssh_key_file: ~/.ssh/id_ed25519

Note
If your master server is located behind a firewall, you will have to open ports 4505-4506 in firewall. Depending on your network configuration, you may have to set up port forwarding for these ports.

Salt Cloud Interface

Create Linode Instances

There are several ways to create new instances:

Create a single new instance:

salt-cloud -p linode_1gb linode1

Creating the instance and installing Salt Minion on it might take some time.

When deployment is complete, you will see following summary:

linode1:
    ----------
    deployed:
        True
    id:
        <ID>
    image:
        CentOS 7
    name:
        linode1
    private_ips:
    public_ips:
        - <ip_address>
    size:
        Nanode 1GB
    state:
        Running

You can connect to the instance using user root and the password specified in the config file.
To create multiple servers in one command type the following:
```
salt-cloud -p linode_1gb linode1 linode2
```
The instance names which you provide in this command are used to manage instances internally and they are not connected to the instance hostname.

Linode labels:
- May only contain ASCII letters or numbers, dashes, and underscores
- Must begin and end with letters or numbers, and
- Be at least three characters in length.
Normally when creating instances, they are executed serially. Use the salt-cloud command with -P option to create instances in parallel allowing for deployment:
```
salt-cloud -P -p linode_1gb linode1 linode2
```
If you do not want to install Salt Minion on the provisioned server, run salt-cloud with the --no-deploy option:
```
salt-cloud -p linode_1gb --no-deploy linode3
```
Salt cloud will generate an error message, but the instance will be created:
```
linode3:
    ----------
    Error:
        ----------
        No Deploy:
            'deploy' is not enabled. Not deploying.
```

Destroy Salt Cloud Instances

To destroy an instance, execute salt-cloud with -d option:
```
salt-cloud -d linode1
```
The server will be destroyed after you confirm the deletion.

Get Information About Running Instances

Partial Information

Gather partial information by executing salt-cloud with the -Q option:

salt-cloud -Q

Full Information

Get full information about instances using -F option:

salt-cloud -F

Configure a Selective Query

Edit /etc/salt/cloud.conf.d/query.conf and add the fields you would like to select:
/etc/salt/cloud.conf.d/query.conf
1 2 3

query.selection: - image - size

Execute selective query using -S option:

salt-cloud -S

Output:

linode3:
    ----------
    image:
        CentOS
    size:
        1024

How to Perform Actions on Salt Cloud Instances

Actions are features that apply to a specific instance. Currently, the following actions are supported:

show_instance
start
stop

For example, to stop a running linode1 instance, execute the salt-cloud command with the -a option and stop command:

salt-cloud -a stop linode1

Use Cloud Map Files to Manage Complex Environments

Scaling, creating, and destroying servers one at a time can be cumbersome. To alleviate this, use Cloud Map files.

Cloud maps assign profiles to a list of instances. During execution Salt Cloud will try to bring the state of these instances into agreement with the map file. New instances will be created, and existing instances will remain unmodified.

Configure Cloud Map

In this example, Cloud map will define two instances: linode_web and linode_db. Both instances will use the profile linode_1gb, defined earlier.

Edit /etc/salt/cloud.conf.d/linode.map and paste the following:
/etc/salt/cloud.conf.d/linode.map
1 2 3

linode_1gb: - linode_web - linode_db
Cloud map file allows you to define instances from several Linode accounts or even from a different provider. Check the Cloud Map documentation for an in-depth guide.
To create instances from the Cloud map file, execute salt-cloud with the -m option and point to the .map file:
```
salt-cloud -m /etc/salt/cloud.conf.d/linode.map
```
Salt Cloud will ask you to confirm the target configuration:
```
The following virtual machines are set to be created:
    linode_web
    linode_db

Proceed? [N/y] y
... proceeding
.  .  .
```
To create instances in parallel, use -P option with Cloud map files.

Delete Instances Created by Cloud Map Files

If an existing instance is removed from the Cloud map file, it will remain running. To delete instances created by map files:

Delete single or multiple instances, specify their names:
```
salt-cloud -d linode_web linode_db
```

Delete all instances, described in the map file:

salt-cloud -d -m /etc/salt/cloud.conf.d/linode.map

Allow Salt Cloud to destroy every instance not described in the map file. SaltStack considers deleting such instances dangerous. This is disabled by default. To enable it:
1. Modify /etc/salt/cloud and add:
  /etc/salt/cloud
  1
  
  enable_hard_maps: True
2. Execute salt-cloud with the --hard option:
```
salt-cloud -d -m /etc/salt/cloud.conf.d/linode.map
```
3. Confirm the deletion when prompted.

Join our Community

Find answers, ask questions, and help others.

This guide is published under a CC BY-ND 4.0 license.

Why Linode

GET TO KNOW US BETTER

Featured

Compute

Storage

Services

Networking

Developer Tools

Community

Engage With Us