neulab/tldr huggingface dataset:
• /etc/salt/cloud.profiles.d/*.conf: Contains settings that define a specific VM type. A profile defines the systems specs and image, and any other settings that are specific to this VM type. Each specific VM type is called a profile, and multiple profiles can be defined in a profile file.  Each profile references a parent provider that defines the cloud host in which the VM is created (the provider settings are in the provider configuration explained above).  Based on your needs, you might define different profiles for web servers, database servers, and so on. See VM Profiles.
Configuration Inheritance Configuration settings are inherited in order from the cloud config => providers => profile.  [image]
For example, if you wanted to use the same image for all virtual machines for a specific provider, the image name could be placed in the provider file. This value is inherited by all profiles that use that provider, but is overridden if a image name is defined in the profile.
Most configuration settings can be defined in any file, the main difference being how that setting is inherited.
QuickStart The Salt Cloud Quickstart walks you through defining a provider, a VM profile, and shows you how to create virtual machines using Salt Cloud.
Note that if you installed Salt via Salt Bootstrap, it may not have automatically installed salt-cloud for you. Use your distribution's package manager to install the salt-cloud package from the same repo that you used to install Salt.  These repos will automatically be setup by Salt Bootstrap.
Alternatively, the -L option can be passed to the Salt Bootstrap script when installing Salt. The -L option will install salt-cloud and the required libcloud package.
Using Salt Cloud salt-cloud Provision virtual machines in the cloud with Salt
Synopsis salt-cloud -m /etc/salt/cloud.map
salt-cloud -m /etc/salt/cloud.map NAME
salt-cloud -m /etc/salt/cloud.map NAME1 NAME2
salt-cloud -p PROFILE NAME
salt-cloud -p PROFILE NAME1 NAME2 NAME3 NAME4 NAME5 NAME6
Description Salt Cloud is the system used to provision virtual machines on various public clouds via a cleanly controlled profile and mapping system.
Options --version Print the version of Salt that is running.
--versions-report Show program's dependencies and version number, and then exit
-c CONFIG_DIR, --config-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is /etc/salt.
Execution Options -L LOCATION, --location=LOCATION Specify which region to connect to.
-a ACTION, --action=ACTION Perform an action that may be specific to this cloud provider. This argument requires one or more instance names to be specified.
-f <FUNC-NAME> <PROVIDER>, --function=<FUNC-NAME> <PROVIDER> Perform an function that may be specific to this cloud provider, that does not apply to an instance. This argument requires a provider to be specified (i.e.: nova).
-p PROFILE, --profile=PROFILE Select a single profile to build the named cloud VMs from. The profile must be defined in the specified profiles file.
-m MAP, --map=MAP Specify a map file to use. If used without any other options, this option will ensure that all of the mapped VMs are created. If the named VM already exists then it will be skipped.
-H, --hard When specifying a map file, the default behavior is to ensure that all of the VMs specified in the map file are created. If the --hard option is set, then any VMs that exist on configured cloud providers that are not specified in the map file will be destroyed. Be advised that this can be a destructive operation and should be used with care.
-d, --destroy Pass in the name(s) of VMs to destroy, salt-cloud will search the configured cloud providers for the specified names and destroy the VMs. Be advised that this is a destructive operation and should be used with care. Can be used in conjunction with the -m option to specify a map of VMs to be deleted.
-P, --parallel Normally when building many cloud VMs they are executed serially. The -P option will run each cloud vm build in a separate process allowing for large groups of VMs to be build at once.
Be advised that some cloud provider's systems don't seem to be well suited for this influx of vm creation. When creating large groups of VMs watch the cloud provider carefully.
-u, --update-bootstrap Update salt-bootstrap to the latest stable bootstrap release.
-y, --assume-yes Default yes in answer to all confirmation questions.
-k, --keep-tmp Do not remove files from /tmp/ after deploy.sh finishes.
--show-deploy-args Include the options used to deploy the minion in the data returned.
--script-args=SCRIPT_ARGS Script arguments to be fed to the bootstrap script when deploying the VM.
Query Options -Q, --query Execute a query and return some information about the nodes running on configured cloud providers
-F, --full-query Execute a query and print out all available information about all cloud VMs.  Can be used in conjunction with -m to display only information about the specified map.
-S, --select-query Execute a query and print out selected information about all cloud VMs.  Can be used in conjunction with -m to display only information about the specified map.
--list-providers Display a list of configured providers.
--list-profiles New in version 2014.7.0.
Display a list of configured profiles. Pass in a cloud provider to view the provider's associated profiles, such as digitalocean, or pass in all to list all the configured profiles.
Cloud Providers Listings --list-locations=LIST_LOCATIONS Display a list of locations available in configured cloud providers. Pass the cloud provider that available locations are desired on, such as "linode", or pass "all" to list locations for all configured cloud providers
--list-images=LIST_IMAGES Display a list of images available in configured cloud providers. Pass the cloud provider that available images are desired on, such as "linode", or pass "all" to list images for all configured cloud providers
--list-sizes=LIST_SIZES Display a list of sizes available in configured cloud providers. Pass the cloud provider that available sizes are desired on, such as "AWS", or pass "all" to list sizes for all configured cloud providers
Cloud Credentials --set-password=<USERNAME> <PROVIDER> Configure password for a cloud provider and save it to the keyring.  PROVIDER can be specified with or without a driver, for example: "--set-password bob rackspace" or more specific "--set-password bob rackspace:openstack" DEPRECATED!
Output Options --out  Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: highstate, json, key, overstatestage, pprint, raw, txt, yaml, and many others.
Some outputters are formatted only for data returned from specific functions.  If an outputter is used that does not support the data passed into it, then Salt will fall back on the pprint outputter and display the return data using the Python pprint standard library module.
--out-indent OUTPUT_INDENT, --output-indent OUTPUT_INDENT Print the output indented by the provided value in spaces. Negative values disable indentation. Only applicable in outputters that support indentation.
--out-file=OUTPUT_FILE, --output-file=OUTPUT_FILE Write the output to the specified file.
--out-file-append, --output-file-append Append the output to the specified file.
--no-color Disable all colored output
--force-color Force colored output
NOTE: When using colored output the color codes are as follows:
green denotes success, red denotes failure, blue denotes changes and success and yellow denotes a expected future change in configuration.
--state-output=STATE_OUTPUT, --state_output=STATE_OUTPUT Override the configured state_output value for minion output. One of 'full', 'terse', 'mixed', 'changes' or 'filter'. Default: 'none'.
--state-verbose=STATE_VERBOSE, --state_verbose=STATE_VERBOSE Override the configured state_verbose value for minion output. Set to True or False. Default: none.
Examples To create 4 VMs named web1, web2, db1, and db2 from specified profiles:
salt-cloud -p fedora_rackspace web1 web2 db1 db2
To read in a map file and create all VMs specified therein:
salt-cloud -m /path/to/cloud.map
To read in a map file and create all VMs specified therein in parallel:
salt-cloud -m /path/to/cloud.map -P
To delete any VMs specified in the map file:
salt-cloud -m /path/to/cloud.map -d
To delete any VMs NOT specified in the map file:
salt-cloud -m /path/to/cloud.map -H
To display the status of all VMs specified in the map file:
salt-cloud -m /path/to/cloud.map -Q
See also salt-cloud(7) salt(7) salt-master(1) salt-minion(1)
Salt Cloud basic usage Salt Cloud needs, at least, one configured Provider and Profile to be functional.
Creating a VM To create a VM with salt cloud, use command:
salt-cloud -p <profile> name_of_vm
Assuming there is a profile configured as following:
fedora_rackspace: provider: my-rackspace-config image: Fedora 17 size: 256 server script: bootstrap-salt
Then, the command to create new VM named fedora_http_01 is:
salt-cloud -p fedora_rackspace fedora_http_01
Destroying a VM To destroy a created-by-salt-cloud VM, use command:
salt-cloud -d name_of_vm
For example, to delete the VM created on above example, use:
salt-cloud -d fedora_http_01
VM Profiles Salt cloud designates virtual machines inside the profile configuration file.  The profile configuration file defaults to /etc/salt/cloud.profiles and is a yaml configuration. The syntax for declaring profiles is simple:
It should be noted that the script option defaults to bootstrap-salt, and does not normally need to be specified. Further examples in this document will not show the script option.
A few key pieces of information need to be declared and can change based on the cloud provider. A number of additional parameters can also be inserted:
centos_rackspace: provider: my-rackspace-config image: CentOS 6.2 size: 1024 server minion: master: salt.example.com append_domain: webs.example.com grains: role: webserver
The image must be selected from available images. Similarly, sizes must be selected from the list of sizes. To get a list of available images and sizes use the following command:
salt-cloud --list-images openstack salt-cloud --list-sizes openstack
Some parameters can be specified in the main Salt cloud configuration file and then are applied to all cloud profiles. For instance if only a single cloud provider is being used then the provider option can be declared in the Salt cloud configuration file.
Multiple Configuration Files In addition to /etc/salt/cloud.profiles, profiles can also be specified in any file matching cloud.profiles.d/*conf which is a sub-directory relative to the profiles configuration file(with the above configuration file as an example, /etc/salt/cloud.profiles.d/*.conf).  This allows for more extensible configuration, and plays nicely with various configuration management tools as well as version control systems.
Larger Example rhel_ec2: provider: my-ec2-config image: ami-e565ba8c size: t1.micro minion: cheese: edam
ubuntu_ec2: provider: my-ec2-config image: ami-7e2da54e size: t1.micro minion: cheese: edam
ubuntu_rackspace: provider: my-rackspace-config image: Ubuntu 12.04 LTS size: 256 server minion: cheese: edam
fedora_rackspace: provider: my-rackspace-config image: Fedora 17 size: 256 server minion: cheese: edam
cent_linode: provider: my-linode-config image: CentOS 6.2 64bit size: Linode 512
cent_gogrid: provider: my-gogrid-config image: 12834 size: 512MB
cent_joyent: provider: my-joyent-config image: centos-7 size: g4-highram-16G
Cloud Map File A number of options exist when creating virtual machines. They can be managed directly from profiles and the command line execution, or a more complex map file can be created. The map file allows for a number of virtual machines to be created and associated with specific profiles. The map file is designed to be run once to create these more complex scenarios using salt-cloud.
Map files have a simple format, specify a profile and then a list of virtual machines to make from said profile:
fedora_small: - web1 - web2 - web3 fedora_high: - redis1 - redis2 - redis3 cent_high: - riak1 - riak2 - riak3
This map file can then be called to roll out all of these virtual machines. Map files are called from the salt-cloud command with the -m option:
$ salt-cloud -m /path/to/mapfile
Remember, that as with direct profile provisioning the -P option can be passed to create the virtual machines in parallel:
$ salt-cloud -m /path/to/mapfile -P
NOTE: Due to limitations in the GoGrid API, instances cannot be provisioned in parallel with the GoGrid driver. Map files will work with GoGrid, but the -P argument should not be used on maps referencing GoGrid instances.
A map file can also be enforced to represent the total state of a cloud deployment by using the --hard option. When using the hard option any vms that exist but are not specified in the map file will be destroyed:
$ salt-cloud -m /path/to/mapfile -P -H
Be careful with this argument, it is very dangerous! In fact, it is so dangerous that in order to use it, you must explicitly enable it in the main configuration file.
enable_hard_maps: True
A map file can include grains and minion configuration options:
fedora_small: - web1: minion: log_level: debug grains: cheese: tasty omelet: du fromage - web2: minion: log_level: warn grains: cheese: more tasty omelet: with peppers
Any top level data element from your profile may be overridden in the map file:
fedora_small: - web1: size: t2.micro - web2: size: t2.nano
As of Salt 2017.7.0, nested elements are merged, and can can be specified individually without having to repeat the complete definition for each top level data element. In this example a separate MAC is assigned to each VMware instance while inheriting device parameters for for disk and network configuration:
nyc-vm: - db1: devices: network: Network Adapter 1: mac: '44:44:44:44:44:41' - db2: devices: network: Network Adapter 1: mac: '44:44:44:44:44:42'
A map file may also be used with the various query options:
$ salt-cloud -m /path/to/mapfile -Q {'ec2': {'web1': {'id': 'i-e6aqfegb', 'image': None, 'private_ips': [], 'public_ips': [], 'size': None, 'state': 0}}, 'web2': {'Absent'}}
...or with the delete option:
$ salt-cloud -m /path/to/mapfile -d The following virtual machines are set to be destroyed: web1 web2
Proceed? [N/y]
WARNING: Specifying Nodes with Maps on the Command Line Specifying the name of a node or nodes with the maps options on the command line is not supported. This is especially important to remember when using --destroy with maps; salt-cloud will ignore any arguments passed in which are not directly relevant to the map file. When using ``--destroy`` with a map, every node in the map file will be deleted! Maps don't provide any useful information for destroying individual nodes, and should not be used to destroy a subset of a map.
Requiring Other Instances The requires directive can be used in map files to ensure that one instance is created and available before another is created.
fedora_high: - db1: size: m5.xlarge - web1: size: m5.large requires: - db1
This requisite is passed to the instance definition dicitonary in a map file and accepts a list of instance names as defined in the map.
Setting up New Salt Masters Bootstrapping a new master in the map is as simple as:
fedora_small: - web1: make_master: True - web2 - web3
Notice that ALL bootstrapped minions from the map will answer to the newly created salt-master.
To make any of the bootstrapped minions answer to the bootstrapping salt-master as opposed to the newly created salt-master, as an example:
fedora_small: - web1: make_master: True minion: master: <the local master ip address> local_master: True - web2 - web3
The above says the minion running on the newly created salt-master responds to the local master, ie, the master used to bootstrap these VMs.
fedora_small: - web1: make_master: True - web2 - web3: minion: master: <the local master ip address> local_master: True
The above example makes the web3 minion answer to the local master, not the newly created master.
Using Direct Map Data When using modules that access the CloudClient directly (notably, the cloud execution and runner modules), it is possible to pass in the contents of a map file, rather than a path to the location of the map file.
Normally when using these modules, the path to the map file is passed in using:
salt-run cloud.map_run /path/to/cloud.map
To pass in the actual map data, use the map_data argument:
salt-run cloud.map_run map_data='{"centos7": [{"saltmaster": {"minion": \ {"transport": "tcp"}, "make_master": true, "master": {"transport": \ "tcp"}}}, {"minion001": {"minion": {"transport": "tcp"}}}]}'
Cloud Actions Once a VM has been created, there are a number of actions that can be performed on it. The "reboot" action can be used across all providers, but all other actions are specific to the cloud provider. In order to perform an action, you may specify it from the command line, including the name(s) of the VM to perform the action on:
$ salt-cloud -a reboot vm_name $ salt-cloud -a reboot vm1 vm2 vm2
Or you may specify a map which includes all VMs to perform the action on:
$ salt-cloud -a reboot -m /path/to/mapfile
The following is an example list of actions currently supported by salt-cloud:
all providers: - reboot ec2: - start - stop joyent: - stop linode: - start - stop
Another useful reference for viewing more salt-cloud actions is the Salt Cloud Feature Matrix.
Cloud Functions Cloud functions work much the same way as cloud actions, except that they don't perform an operation on a specific instance, and so do not need a machine name to be specified. However, since they perform an operation on a specific cloud provider, that provider must be specified.
$ salt-cloud -f show_image ec2 image=ami-fd20ad94
There are three universal salt-cloud functions that are extremely useful for gathering information about instances on a provider basis:
• list_nodes: Returns some general information about the instances for the given provider.
• list_nodes_full: Returns all information about the instances for the given provider.
• list_nodes_select: Returns select information about the instances for the given provider.
$ salt-cloud -f list_nodes linode $ salt-cloud -f list_nodes_full linode $ salt-cloud -f list_nodes_select linode
Another useful reference for viewing salt-cloud functions is the Salt Cloud Feature Matrix.
Core Configuration Install Salt Cloud Salt Cloud is now part of Salt proper.  It was merged in as of Salt version 2014.1.0.
On Ubuntu, install Salt Cloud by using following command:
sudo add-apt-repository ppa:saltstack/salt sudo apt-get update sudo apt-get install salt-cloud
If using Salt Cloud on macOS, curl-ca-bundle must be installed. Presently, this package is not available via brew, but it is available using MacPorts:
sudo port install curl-ca-bundle
Salt Cloud depends on apache-libcloud.  Libcloud can be installed via pip with pip install apache-libcloud.
Installing Salt Cloud for development Installing Salt for development enables Salt Cloud development as well, just make sure apache-libcloud is installed as per above paragraph.
See these instructions: Installing Salt for development.
Core Configuration A number of core configuration options and some options that are global to the VM profiles can be set in the cloud configuration file. By default this file is located at /etc/salt/cloud.
Thread Pool Size When salt cloud is operating in parallel mode via the -P argument, you can control the thread pool size by specifying the pool_size parameter with a positive integer value.
By default, the thread pool size will be set to the number of VMs that salt cloud is operating on.
pool_size: 10
Minion Configuration The default minion configuration is set up in this file. Minions created by salt-cloud derive their configuration from this file. Almost all parameters found in Configuring the Salt Minion can be used here.
minion: master: saltmaster.example.com
In particular, this is the location to specify the location of the salt master and its listening port, if the port is not set to the default.
Similar to most other settings, Minion configuration settings are inherited across configuration files. For example, the master setting might be contained in the main cloud configuration file as demonstrated above, but additional settings can be placed in the provider, profile or map configuration files:
ec2-web: size: t1.micro minion: environment: test startup_states: sls sls_list: - web
When salt cloud creates a new minion, it can automatically add grain information to the minion configuration file identifying the sources originally used to define it.
The generated grain information will appear similar to:
grains: salt-cloud: driver: ec2 provider: my_ec2:ec2 profile: ec2-web
The generation of the salt-cloud grain can be suppressed by the option enable_cloud_grains: 'False' in the cloud configuration file.
Cloud Configuration Syntax The data specific to interacting with public clouds is set up here.
Cloud provider configuration settings can live in several places. The first is in /etc/salt/cloud:
# /etc/salt/cloud providers: my-aws-migrated-config: id: HJGRYCILJLKJYG key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn' keyname: test securitygroup: quick-start private_key: /root/test.pem driver: ec2
Cloud provider configuration data can also be housed in /etc/salt/cloud.providers or any file matching /etc/salt/cloud.providers.d/*.conf. All files in any of these locations will be parsed for cloud provider data.
Using the example configuration above:
# /etc/salt/cloud.providers # or could be /etc/salt/cloud.providers.d/*.conf my-aws-config: id: HJGRYCILJLKJYG key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn' keyname: test securitygroup: quick-start private_key: /root/test.pem driver: ec2
NOTE: Salt Cloud provider configurations within /etc/cloud.provider.d/ should not specify the providers starting key.
It is also possible to have multiple cloud configuration blocks within the same alias block.  For example:
production-config: - id: HJGRYCILJLKJYG key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn' keyname: test securitygroup: quick-start private_key: /root/test.pem driver: ec2
- user: example_user apikey: 123984bjjas87034 driver: rackspace
However, using this configuration method requires a change with profile configuration blocks.  The provider alias needs to have the provider key value appended as in the following example:
rhel_aws_dev: provider: production-config:ec2 image: ami-e565ba8c size: t1.micro
rhel_aws_prod: provider: production-config:ec2 image: ami-e565ba8c size: High-CPU Extra Large Instance
database_prod: provider: production-config:rackspace image: Ubuntu 12.04 LTS size: 256 server
Notice that because of the multiple entries, one has to be explicit about the provider alias and name, from the above example, production-config: ec2.
This data interactions with the salt-cloud binary regarding its --list-location, --list-images, and --list-sizes which needs a cloud provider as an argument. The argument used should be the configured cloud provider alias. If the provider alias has multiple entries, <provider-alias>: <provider-name> should be used.
To allow for a more extensible configuration, --providers-config, which defaults to /etc/salt/cloud.providers, was added to the cli parser.  It allows for the providers' configuration to be added on a per-file basis.
Pillar Configuration It is possible to configure cloud providers using pillars. This is only used when inside the cloud module. You can setup a variable called cloud that contains your profile, provider, and map to pass that information to the cloud servers instead of having to copy the full configuration to every minion. In your pillar file, you would use something like this:
cloud: ssh_key_name: saltstack ssh_key_file: /root/.ssh/id_rsa update_cachedir: True diff_cache_events: True
providers: my-openstack: driver: openstack region_name: ORD cloud: mycloud
profiles: ubuntu-openstack: provider: my-openstack size: ds512M image: CentOS 7 script_args: git develop
maps: my-dev-map: ubuntu-openstack: - dev-test01 - dev-test02 - dev-test03 - dev-test04 my-prd-map: ubuntu-openstack: - prd-web01 - prd-web02 minion: id: custom-minion-id-app1-stack1-frontend grains: roles: - webserver deployment: datacenter4-openstack - prod-db01 - prod-db02
Cloud Configurations Scaleway To use Salt Cloud with Scaleway, you need to get an access key and an API token. API tokens are unique identifiers associated with your Scaleway account.  To retrieve your access key and API token, log-in to the Scaleway control panel, open the pull-down menu on your account name and click on "My Credentials" link.
If you do not have API token you can create one by clicking the "Create New Token" button on the right corner.
my-scaleway-config: access_key: 15cf404d-4560-41b1-9a0c-21c3d5c4ff1f token: a7347ec8-5de1-4024-a5e3-24b77d1ba91d driver: scaleway
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-scaleway-config.
Rackspace Rackspace cloud requires two configuration options; a user and an apikey:
my-rackspace-config: user: example_user apikey: 123984bjjas87034 driver: rackspace
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-rackspace-config.
Amazon AWS A number of configuration options are required for Amazon AWS including id, key, keyname, securitygroup, and private_key:
my-aws-quick-start: id: HJGRYCILJLKJYG key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn' keyname: test securitygroup: quick-start private_key: /root/test.pem driver: ec2
my-aws-default: id: HJGRYCILJLKJYG key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn' keyname: test securitygroup: default private_key: /root/test.pem driver: ec2
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be either provider: my-aws-quick-start or provider: my-aws-default.
Linode Linode requires a single API key, but the default root password also needs to be set:
my-linode-config: apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf password: F00barbaz ssh_pubkey: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHEOLLbeXgaqRQT9NBAopVz366SdYc0KKX33vAnq+2R user@host ssh_key_file: ~/.ssh/id_ed25519 driver: linode
The password needs to be 8 characters and contain lowercase, uppercase, and numbers.
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-linode-config
Joyent Cloud The Joyent cloud requires three configuration parameters: The username and password that are used to log into the Joyent system, as well as the location of the private SSH key associated with the Joyent account. The SSH key is needed to send the provisioning commands up to the freshly created virtual machine.
my-joyent-config: user: fred password: saltybacon private_key: /root/joyent.pem driver: joyent
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-joyent-config
GoGrid To use Salt Cloud with GoGrid, log into the GoGrid web interface and create an API key. Do this by clicking on "My Account" and then going to the API Keys tab.
The apikey and the sharedsecret configuration parameters need to be set in the configuration file to enable interfacing with GoGrid:
my-gogrid-config: apikey: asdff7896asdh789 sharedsecret: saltybacon driver: gogrid
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-gogrid-config.
OpenStack Using Salt for OpenStack uses the shade <https://docs.openstack.org/shade/latest/> driver managed by the openstack-infra team.
This driver can be configured using the /etc/openstack/clouds.yml file with os-client-config <https://docs.openstack.org/os-client-config/latest/>
myopenstack: driver: openstack region_name: RegionOne cloud: mycloud
Or by just configuring the same auth block directly in the cloud provider config.
myopenstack: driver: openstack region_name: RegionOne auth: username: 'demo' password: secret project_name: 'demo' auth_url: 'http://openstack/identity'
Both of these methods support using the vendor <https://docs.openstack.org/os-client-config/latest/user/vendor-support.html> options.
For more information, look at Openstack Cloud Driver Docs
DigitalOcean Using Salt for DigitalOcean requires a client_key and an api_key. These can be found in the DigitalOcean web interface, in the "My Settings" section, under the API Access tab.
my-digitalocean-config: driver: digitalocean personal_access_token: xxx location: New York 1
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-digital-ocean-config.
Parallels Using Salt with Parallels requires a user, password and URL. These can be obtained from your cloud provider.
my-parallels-config: user: myuser password: xyzzy url: https://api.cloud.xmission.com:4465/paci/v1.0/ driver: parallels
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-parallels-config.
Proxmox Using Salt with Proxmox requires a user, password, and URL. These can be obtained from your cloud host. Both PAM and PVE users can be used.
my-proxmox-config: driver: proxmox user: saltcloud@pve password: xyzzy url: your.proxmox.host
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: my-proxmox-config.
LXC The lxc driver uses saltify to install salt and attach the lxc container as a new lxc minion. As soon as we can, we manage baremetal operation over SSH. You can also destroy those containers via this driver.
devhost10-lxc: target: devhost10 driver: lxc
And in the map file:
devhost10-lxc: provider: devhost10-lxc from_container: ubuntu backing: lvm sudo: True size: 3g ip: 10.0.3.9 minion: master: 10.5.0.1 master_port: 4506 lxc_conf: - lxc.utsname: superlxc
NOTE: In the cloud profile that uses this provider configuration, the syntax for the provider required field would be provider: devhost10-lxc.
Saltify The Saltify driver is a new, experimental driver designed to install Salt on a remote machine, virtual or bare metal, using SSH. This driver is useful for provisioning machines which are already installed, but not Salted. For more information about using this driver and for configuration examples, please see the Getting Started with Saltify documentation.
Vagrant The Vagrant driver is a new, experimental driver for controlling a VagrantBox virtual machine, and installing Salt on it. The target host machine must be a working salt minion, which is controlled via the salt master using salt-api.  For more information, see Getting Started With Vagrant.
Extending Profiles and Cloud Providers Configuration As of 0.8.7, the option to extend both the profiles and cloud providers configuration and avoid duplication was added. The extends feature works on the current profiles configuration, but, regarding the cloud providers configuration, only works in the new syntax and respective configuration files, i.e. /etc/salt/salt/cloud.providers or /etc/salt/cloud.providers.d/*.conf.
NOTE: Extending cloud profiles and providers is not recursive. For example, a profile that is extended by a second profile is possible, but the second profile cannot be extended by a third profile.
Also, if a profile (or provider) is extending another profile and each contains a list of values, the lists from the extending profile will override the list from the original profile. The lists are not merged together.
Extending Profiles Some example usage on how to use extends with profiles. Consider /etc/salt/salt/cloud.profiles containing:
development-instances: provider: my-ec2-config size: t1.micro ssh_username: ec2_user securitygroup: - default deploy: False
Amazon-Linux-AMI-2012.09-64bit: image: ami-54cf5c3d extends: development-instances
Fedora-17: image: ami-08d97e61 extends: development-instances
CentOS-5: provider: my-aws-config image: ami-09b61d60 extends: development-instances
The above configuration, once parsed would generate the following profiles data:
[ { "deploy": False, "image": "ami-08d97e61", "profile": "Fedora-17", "provider": "my-ec2-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, { "deploy": False, "image": "ami-09b61d60", "profile": "CentOS-5", "provider": "my-aws-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, { "deploy": False, "image": "ami-54cf5c3d", "profile": "Amazon-Linux-AMI-2012.09-64bit", "provider": "my-ec2-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, { "deploy": False, "profile": "development-instances", "provider": "my-ec2-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, ]
Extending Providers Some example usage on how to use extends within the cloud providers configuration.  Consider /etc/salt/salt/cloud.providers containing:
my-develop-envs: - id: HJGRYCILJLKJYG key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn' keyname: test securitygroup: quick-start private_key: /root/test.pem location: ap-southeast-1 availability_zone: ap-southeast-1b driver: ec2
- user: myuser@mycorp.com password: mypass ssh_key_name: mykey ssh_key_file: '/etc/salt/ibm/mykey.pem' location: Raleigh driver: ibmsce
my-productions-envs: - extends: my-develop-envs:ibmsce user: my-production-user@mycorp.com location: us-east-1 availability_zone: us-east-1
The above configuration, once parsed would generate the following providers data:
{ "providers": { "my-develop-envs": [ { "availability_zone": "ap-southeast-1b", "id": "HJGRYCILJLKJYG", "key": "kdjgfsgm;woormgl/aserigjksjdhasdfgn", "keyname": "test", "location": "ap-southeast-1", "private_key": "/root/test.pem", "driver": "aws", "securitygroup": "quick-start", }, { "location": "Raleigh", "password": "mypass", "driver": "ibmsce", "ssh_key_file": "/etc/salt/ibm/mykey.pem", "ssh_key_name": "mykey", "user": "myuser@mycorp.com", }, ], "my-productions-envs": [ { "availability_zone": "us-east-1", "location": "us-east-1", "password": "mypass", "driver": "ibmsce", "ssh_key_file": "/etc/salt/ibm/mykey.pem", "ssh_key_name": "mykey", "user": "my-production-user@mycorp.com", } ], } }
Windows Configuration Spinning up Windows Minions It is possible to use Salt Cloud to spin up Windows instances, and then install Salt on them. This functionality is available on all cloud providers that are supported by Salt Cloud. However, it may not necessarily be available on all Windows images.
Requirements NOTE: Support winexe and impacket has been deprecated and will be removed in 3001. These dependencies are replaced by pypsexec and smbprotocol respectivly. These are pure python alternatives that are compatible with all supported python versions.
Salt Cloud makes use of impacket and winexe to set up the Windows Salt Minion installer.
impacket is usually available as either the impacket or the python-impacket package, depending on the distribution. More information on impacket can be found at the project home:
• impacket project home
winexe is less commonly available in distribution-specific repositories. However, it is currently being built for various distributions in 3rd party channels:
• RPMs at pbone.net
• openSUSE Build Service
• pypsexec project home
• smbprotocol project home
Optionally WinRM can be used instead of winexe if the python module pywinrm is available and WinRM is supported on the target Windows version. Information on pywinrm can be found at the project home:
• pywinrm project home
Additionally, a copy of the Salt Minion Windows installer must be present on the system on which Salt Cloud is running. This installer may be downloaded from saltstack.com:
• SaltStack Download Area
Self Signed Certificates with WinRM Salt-Cloud can use versions of pywinrm<=0.1.1 or pywinrm>=0.2.1.
For versions greater than 0.2.1, winrm_verify_ssl needs to be set to False if the certificate is self signed and not verifiable.
Firewall Settings Because Salt Cloud makes use of smbclient and winexe, port 445 must be open on the target image. This port is not generally open by default on a standard Windows distribution, and care must be taken to use an image in which this port is open, or the Windows firewall is disabled.
If supported by the cloud provider, a PowerShell script may be used to open up this port automatically, using the cloud provider's userdata. The following script would open up port 445, and apply the changes:
<powershell> New-NetFirewallRule -Name "SMB445" -DisplayName "SMB445" -Protocol TCP -LocalPort 445 Set-Item (dir wsman:\localhost\Listener\*\Port -Recurse).pspath 445 -Force Restart-Service winrm </powershell>
For EC2, this script may be saved as a file, and specified in the provider or profile configuration as userdata_file. For instance:
my-ec2-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/windows-firewall.ps1
NOTE: From versions 2016.11.0 and 2016.11.3, this file was passed through the master's renderer to template it. However, this caused issues with non-YAML data, so templating is no longer performed by default.  To template the userdata_file, add a userdata_template option to the cloud profile:
my-ec2-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/windows-firewall.ps1 userdata_template: jinja
If no userdata_template is set in the cloud profile, then the master configuration will be checked for a userdata_template value.  If this is not set, then no templating will be performed on the userdata_file.
To disable templating in a cloud profile when a userdata_template has been set in the master configuration file, simply set userdata_template to False in the cloud profile:
my-ec2-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/windows-firewall.ps1 userdata_template: False
If you are using WinRM on EC2 the HTTPS port for the WinRM service must also be enabled in your userdata. By default EC2 Windows images only have insecure HTTP enabled. To enable HTTPS and basic authentication required by pywinrm consider the following userdata example:
<powershell> New-NetFirewallRule -Name "SMB445" -DisplayName "SMB445" -Protocol TCP -LocalPort 445 New-NetFirewallRule -Name "WINRM5986" -DisplayName "WINRM5986" -Protocol TCP -LocalPort 5986
winrm quickconfig -q winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="300"}' winrm set winrm/config '@{MaxTimeoutms="1800000"}' winrm set winrm/config/service/auth '@{Basic="true"}'
$SourceStoreScope = 'LocalMachine' $SourceStorename = 'Remote Desktop'
$SourceStore = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $SourceStorename, $SourceStoreScope $SourceStore.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadOnly)
$cert = $SourceStore.Certificates | Where-Object -FilterScript { $_.subject -like '*' }
$DestStoreScope = 'LocalMachine' $DestStoreName = 'My'
$DestStore = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $DestStoreName, $DestStoreScope $DestStore.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadWrite) $DestStore.Add($cert)
$SourceStore.Close() $DestStore.Close()
winrm create winrm/config/listener?Address=*+Transport=HTTPS `@`{CertificateThumbprint=`"($cert.Thumbprint)`"`}
Restart-Service winrm </powershell>
No certificate store is available by default on EC2 images and creating one does not seem possible without an MMC (cannot be automated). To use the default EC2 Windows images the above copies the RDP store.
Configuration Configuration is set as usual, with some extra configuration settings. The location of the Windows installer on the machine that Salt Cloud is running on must be specified. This may be done in any of the regular configuration files (main, providers, profiles, maps). For example:
Setting the installer in /etc/salt/cloud.providers:
my-softlayer: driver: softlayer user: MYUSER1138 apikey: 'e3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9' minion: master: saltmaster.example.com win_installer: /root/Salt-Minion-2014.7.0-AMD64-Setup.exe win_username: Administrator win_password: letmein smb_port: 445
The default Windows user is Administrator, and the default Windows password is blank.
If WinRM is to be used use_winrm needs to be set to True. winrm_port can be used to specify a custom port (must be HTTPS listener).  And winrm_verify_ssl can be set to False to use a self signed certificate.
Auto-Generated Passwords on EC2 On EC2, when the win_password is set to auto, Salt Cloud will query EC2 for an auto-generated password. This password is expected to take at least 4 minutes to generate, adding additional time to the deploy process.
When the EC2 API is queried for the auto-generated password, it will be returned in a message encrypted with the specified keyname. This requires that the appropriate private_key file is also specified. Such a profile configuration might look like:
windows-server-2012: provider: my-ec2-config image: ami-c49c0dac size: m1.small securitygroup: windows keyname: mykey private_key: /root/mykey.pem userdata_file: /etc/salt/windows-firewall.ps1 win_installer: /root/Salt-Minion-2014.7.0-AMD64-Setup.exe win_username: Administrator win_password: auto
Cloud Provider Specifics Getting Started With Aliyun ECS The Aliyun ECS (Elastic Computer Service) is one of the most popular public cloud hosts in China. This cloud host can be used to manage aliyun instance using salt-cloud.
http://www.aliyun.com/
Dependencies This driver requires the Python requests library to be installed.
Configuration Using Salt for Aliyun ECS requires aliyun access key id and key secret. These can be found in the aliyun web interface, in the "User Center" section, under "My Service" tab.
# Note: This example is for /etc/salt/cloud.providers or any file in the # /etc/salt/cloud.providers.d/ directory.
my-aliyun-config: # aliyun Access Key ID id: wDGEwGregedg3435gDgxd # aliyun Access Key Secret key: GDd45t43RDBTrkkkg43934t34qT43t4dgegerGEgg location: cn-qingdao driver: aliyun
NOTE: Changed in version 2015.8.0.
The provider parameter in cloud provider definitions was renamed to driver. This change was made to avoid confusion with the provider parameter that is used in cloud profile definitions. Cloud provider definitions now use driver to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use provider to refer to provider configurations that you define.
Profiles Cloud Profiles Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory:
aliyun_centos: provider: my-aliyun-config size: ecs.t1.small location: cn-qingdao securitygroup: G1989096784427999 image: centos6u3_64_20G_aliaegis_20130816.vhd
Sizes can be obtained using the --list-sizes option for the salt-cloud command:
# salt-cloud --list-sizes my-aliyun-config my-aliyun-config: ---------- aliyun: ---------- ecs.c1.large: ---------- CpuCoreCount: 8 InstanceTypeId: ecs.c1.large MemorySize: 16.0
...SNIP...
Images can be obtained using the --list-images option for the salt-cloud command:
# salt-cloud --list-images my-aliyun-config my-aliyun-config: ---------- aliyun: ---------- centos5u8_64_20G_aliaegis_20131231.vhd: ---------- Architecture: x86_64 Description:
ImageId: centos5u8_64_20G_aliaegis_20131231.vhd ImageName: CentOS 5.8 64位 ImageOwnerAlias: system ImageVersion: 1.0 OSName: CentOS  5.8 64位 Platform: CENTOS5 Size: 20 Visibility: public ...SNIP...
Locations can be obtained using the --list-locations option for the salt-cloud command:
my-aliyun-config: ---------- aliyun: ---------- cn-beijing: ---------- LocalName: 北京 RegionId: cn-beijing cn-hangzhou: ---------- LocalName: 杭州 RegionId: cn-hangzhou cn-hongkong: ---------- LocalName: 香港 RegionId: cn-hongkong cn-qingdao: ---------- LocalName: 青岛 RegionId: cn-qingdao
Security Group can be obtained using the -f list_securitygroup option for the salt-cloud command:
# salt-cloud --location=cn-qingdao -f list_securitygroup my-aliyun-config my-aliyun-config: ---------- aliyun: ---------- G1989096784427999: ---------- Description: G1989096784427999 SecurityGroupId: G1989096784427999
NOTE: Aliyun ECS REST API documentation is available from Aliyun ECS API.
Getting Started With Azure New in version 2014.1.0.
Azure is a cloud service by Microsoft providing virtual machines, SQL services, media services, and more. This document describes how to use Salt Cloud to create a virtual machine on Azure, with Salt installed.
More information about Azure is located at http://www.windowsazure.com/.
Dependencies • Microsoft Azure SDK for Python >= 1.0.2
• The python-requests library, for Python < 2.7.9.
• A Microsoft Azure account
• OpenSSL (to generate the certificates)
• Salt
Configuration Set up the provider config at /etc/salt/cloud.providers.d/azure.conf:
# Note: This example is for /etc/salt/cloud.providers.d/azure.conf
my-azure-config: driver: azure subscription_id: 3287abc8-f98a-c678-3bde-326766fd3617 certificate_path: /etc/salt/azure.pem
# Set up the location of the salt master # minion: master: saltmaster.example.com
# Optional management_host: management.core.windows.net
The certificate used must be generated by the user. OpenSSL can be used to create the management certificates. Two certificates are needed: a .cer file, which is uploaded to Azure, and a .pem file, which is stored locally.
To create the .pem file, execute the following command:
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout /etc/salt/azure.pem -out /etc/salt/azure.pem
To create the .cer file, execute the following command:
openssl x509 -inform pem -in /etc/salt/azure.pem -outform der -out /etc/salt/azure.cer
After creating these files, the .cer file will need to be uploaded to Azure via the "Upload a Management Certificate" action of the "Management Certificates" tab within the "Settings" section of the management portal.
Optionally, a management_host may be configured, if necessary for the region.
Cloud Profiles Set up an initial profile at /etc/salt/cloud.profiles:
azure-ubuntu: provider: my-azure-config image: 'b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-12_04_3-LTS-amd64-server-20131003-en-us-30GB' size: Small location: 'East US' ssh_username: azureuser ssh_password: verybadpass slot: production media_link: 'http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds' virtual_network_name: azure-virtual-network subnet_name: azure-subnet
These options are described in more detail below. Once configured, the profile can be realized with a salt command:
salt-cloud -p azure-ubuntu newinstance
This will create an salt minion instance named newinstance in Azure. If the command was executed on the salt-master, its Salt key will automatically be signed on the master.
Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:
salt newinstance test.version
Profile Options The following options are currently available for Azure.
provider The name of the provider as configured in /etc/salt/cloud.providers.d/azure.conf.
image The name of the image to use to create a VM. Available images can be viewed using the following command:
salt-cloud --list-images my-azure-config
size The name of the size to use to create a VM. Available sizes can be viewed using the following command:
salt-cloud --list-sizes my-azure-config
location The name of the location to create a VM in. Available locations can be viewed using the following command:
salt-cloud --list-locations my-azure-config
affinity_group The name of the affinity group to create a VM in. Either a location or an affinity_group may be specified, but not both. See Affinity Groups below.
ssh_username The user to use to log into the newly-created VM to install Salt.
ssh_password The password to use to log into the newly-created VM to install Salt.
slot The environment to which the hosted service is deployed. Valid values are staging or production. When set to production, the resulting URL of the new VM will be <vm_name>.cloudapp.net. When set to staging, the resulting URL will contain a generated hash instead.