Salt Cloud works primarily by executing a script on the virtual machines as
soon as they become available. The script that is executed is referenced in the
cloud profile as the
script. In older versions, this was the
argument. This was changed in 0.8.2.
A number of legacy scripts exist in the deploy directory in the saltcloud source tree. The preferred method is currently to use the salt-bootstrap script. A stable version is included with each release tarball starting with 0.8.4. The most updated version can be found at:
Note that, somewhat counter-intuitively, this script is referenced as
bootstrap-salt in the configuration.
You can specify a deploy script in the cloud configuration file
/etc/salt/cloud by default):
Or in a provider:
my-provider: # snip... script: bootstrap-salt
Or in a profile:
my-profile: provider: my-provider # snip... script: bootstrap-salt
If you do not specify a script argument in your cloud configuration file, provider configuration or profile configuration, the "bootstrap-salt" script will be used by default.
If you want to be assured of always using the latest Salt Bootstrap script, there are a few generic templates available in the deploy directory of your saltcloud source tree:
curl-bootstrap curl-bootstrap-git python-bootstrap wget-bootstrap wget-bootstrap-git
These are example scripts which were designed to be customized, adapted, and refit to meet your needs. One important use of them is to pass options to the salt-bootstrap script, such as updating to specific git tags.
If the Salt Bootstrap script does not meet your needs, you may write your own. The script should be written in shell and is a Jinja template. Deploy scripts need to execute a number of functions to do a complete salt setup. These functions include:
Install the salt minion. If this can be done via system packages this method is HIGHLY preferred.
Add the salt minion keys before the minion is started for the first time. The minion keys are available as strings that can be copied into place in the Jinja template under the dict named "vm".
Start the salt-minion daemon and enable it at startup time.
Set up the minion configuration file from the "minion" data available in the Jinja template.
A good, well commented example of this process is the Fedora deployment script:
A number of legacy deploy scripts are included with the release tarball. None of them are as functional or complete as Salt Bootstrap, and are still included for academic purposes.
Custom deploy scripts are picked up from
default, but you can change the location of deploy scripts with the cloud
deploy_scripts_search_path. Additionally, if your deploy
script has the extension
.sh, you can leave out the extension in your
For example, if your custom deploy script is located in
/etc/salt/cloud.deploy.d/my_deploy.sh, you could specify it in a cloud
profile like this:
my-profile: provider: my-provider # snip... script: my_deploy
You're also free to use the full path to the script if you like. Using full
paths, your script doesn't have to live inside
whatever you've configured with
Once a minion has been deployed, it has the option to run a salt command.
Normally, this would be the
which would finish provisioning the VM. Another common option (for testing) is
test.version. This is configured in the
main cloud config file:
This is currently considered to be experimental functionality, and may not work well with all cloud hosts. If you experience problems with Salt Cloud hanging after Salt is deployed, consider using Startup States instead.
For whatever reason, you may want to skip the deploy script altogether. This results in a VM being spun up much faster, with absolutely no configuration. This can be set from the command line:
salt-cloud --no-deploy -p micro_aws my_instance
Or it can be set from the main cloud config file:
Or it can be set from the provider's configuration:
RACKSPACE.user: example_user RACKSPACE.apikey: 123984bjjas87034 RACKSPACE.deploy: False
Or even on the VM's profile settings:
ubuntu_aws: provider: my-ec2-config image: ami-7e2da54e size: t1.micro deploy: False
The default for deploy is True.
In the profile, you may also set the script option to
This is the slowest option, since it still uploads the None deploy script and executes it.
Salt Bootstrap can be updated automatically with
salt-cloud -u salt-cloud --update-bootstrap
Bear in mind that this updates to the latest stable version from:
To update Salt Bootstrap script to the develop version, run the following
command on the Salt minion host with
salt-call config.gather_bootstrap_script 'https://bootstrap.saltproject.io/develop/bootstrap-salt.sh'
Or just download the file manually:
curl -L 'https://bootstrap.saltproject.io/develop' > /etc/salt/cloud.deploy.d/bootstrap-salt.sh
When Salt Cloud deploys an instance, it uploads temporary files to /tmp/ for salt-bootstrap to put in place. After the script has run, they are deleted. To keep these files around (mostly for debugging purposes), the --keep-tmp option can be added:
salt-cloud -p myprofile mymachine --keep-tmp
For those wondering why /tmp/ was used instead of /root/, this had to be done for images which require the use of sudo, and therefore do not allow remote root logins, even for file transfers (which makes /root/ unavailable).
Custom deploy scripts are unlikely to need custom arguments to be passed to them, but salt-bootstrap has been extended quite a bit, and this may be necessary. script_args can be specified in either the profile or the map file, to pass arguments to the deploy script:
aws-amazon: provider: my-ec2-config image: ami-1624987f size: t1.micro ssh_username: ec2-user script: bootstrap-salt script_args: -c /tmp/
This has also been tested to work with pipes, if needed:
script_args: '| head'