Using Salt Cloud and Cloud Maps to Provision Systems

Traducciones al Español
Estamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.
Create a Linode account to try this guide with a $ credit.
This credit will be applied to any valid services used during your first  days.

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

  1. 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.

  2. This guide assumes that Salt Cloud will be installed together with Salt master server.

  3. Generate an API key to access Linode API. This key will be used by Salt Cloud to manage your instances. Make sure to keep your API key safe. Set the environment variable API_TOKEN and test your API key is working through the REST interface:

    curl -H "Authorization:Bearer $API_TOKEN" | json_pp
  4. 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.

  1. Download the Salt Bootstrap script via curl:

     curl -o -L
  2. Execute the script and use the -L option to install Salt and Salt Cloud:

     sh -L

Configure Salt Cloud

Set up Provider Configuration:

Configure and test access to the Linode API.

  1. 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.

    File: /etc/salt/cloud.providers.d/linode.conf
        api_version: v4
        apikey: <Your API key>
        password: <Default password for the new instances>
        driver: linode
    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.
  2. Test access to the Linode API:

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

     salt-cloud --list-locations my-linode-provider

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

             Atlanta, GA, USA:
                     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 my-linode-provider
  • Available sizes:

     salt-cloud --list-sizes my-linode-provider
  • Available images:

     salt-cloud --list-images my-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 a standard size, using a Debian 11 image, located in London.

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

    File: /etc/salt/cloud.profiles.d/linode-london-1gb.conf
      provider: my-linode-provider
      size: g6-standard-1
      image: linode/debian11
      location: eu-west

    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.

  2. 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 with the IP address or domain name of your master server:

    File: /etc/salt/cloud.conf.d/master.conf

    Another option is to set this parameter for specific instance profile:

    File: /etc/salt/cloud.profiles.d/linode-london-1gb.conf
    provider: my-linode-provider
      size: g6-standard-1
      image: linode/debian11
      location: eu-west
  3. 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:

    File: /etc/salt/cloud.profiles.d/linode-london-1gb.conf
      provider: my-linode-provider
      size: g6-standard-1
      image: linode/debian11
      location: eu-west
      ssh_pubkey: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHEOLLbeXgaqRQT9NBAopVz366SdYc0KKX33vAnq+2R user@host
      ssh_key_file: ~/.ssh/id_ed25519
    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:

             - <ip_address>
  • 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:

             No Deploy:
                 'deploy' is not enabled. Not deploying.

Destroy Salt Cloud Instances

  1. To destroy an instance, execute salt-cloud with -d option:

    salt-cloud -d linode1
  2. 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

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

    File: /etc/salt/cloud.conf.d/query.conf
      - image
      - size
  2. Execute selective query using -S option:

    salt-cloud -S



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.

  1. Edit /etc/salt/cloud.conf.d/ and paste the following:

    File: /etc/salt/cloud.conf.d/
      - 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.

  2. 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/
  3. Salt Cloud will ask you to confirm the target configuration:

    The following virtual machines are set to be created:
    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/
  • 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:

      File: /etc/salt/cloud
      enable_hard_maps: True
    2. Execute salt-cloud with the --hard option:

       salt-cloud -d -m /etc/salt/cloud.conf.d/
    3. Confirm the deletion when prompted.

This page was originally published on

Your Feedback Is Important

Let us know if this guide was helpful to you.

Join the conversation.
Read other comments or post your own below. Comments must be respectful, constructive, and relevant to the topic of the guide. Do not post external links or advertisements. Before posting, consider if your comment would be better addressed by contacting our Support team or asking on our Community Site.
The Disqus commenting system for Linode Docs requires the acceptance of Functional Cookies, which allow us to analyze site usage so we can measure and improve performance. To view and create comments for this article, please update your Cookie Preferences on this website and refresh this web page. Please note: You must have JavaScript enabled in your browser.