salt-cloud(7) - Linux man page

Name

salt-cloud - Salt Cloud Documentation

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:

fedora_rackspace:
  provider: rackspace
  image: Fedora 17
  size: 256 server
  script: Fedora

A few key peices of information need to be declared and can change based on the public cloud provider. A number of additional parameters can also be inserted:

centos_rackspace:
  provider: rackspace
  image: CentOS 6.2
  size: 1024 server
  script: RHEL6
  minion:
    master: salt.example.com
  grains:
    role: webserver

Some parameters can be specified in the main Salt cloud config 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 config file.

Larger Example

rhel_aws: provider: aws image: ami-e565ba8c size: Micro Instance script: RHEL6 minion: cheese: edam ubuntu_aws: provider: aws image: ami-7e2da54e size: Micro Instance script: Ubuntu minion: cheese: edam ubuntu_rackspace: provider: rackspace image: Ubuntu 12.04 LTS size: 256 server script: Ubuntu minion: cheese: edam fedora_rackspace: provider: rackspace image: Fedora 17 size: 256 server script: Fedora minion: cheese: edam cent_linode: provider: linode image: CentOS 6.2 64bit size: Linode 512 script: RHEL6 cent_gogrid: provider: gogrid image: 12834 size: 512MB script: RHEL6 cent_joyent: provider: joyent image: centos-6 script: RHEL6 size: Small 1GB

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.

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

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:

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

A map file may also be used with the various query options:

$ salt-cloud -m /path/to/mapfile -Q
{'aws': {'web1': {'id': 'i-e6aqfegb',
                     'image': None,
                     'private_ips': [],
                     'public_ips': [],
                     'size': None,
                     'state': 0}},
         'web2': {'Absent'}}

$ salt-cloud -m /path/to/mapfile -d
The following virtual machines are set to be destroyed:
  web1
  web2

Proceed? [N/y]

Writing Cloud Provider Modules

Salt cloud runs on a module system similar to the main Salt project. The modules inside saltcloud exist in the saltcloud/clouds directory of the salt-cloud source.

Adding a provider requires that a cloud module is created. The cloud module needs to only impliment a single function create, which will accept a single virtual machine data structure. Whatever functions need to be called to execute the create function can and should be included in the provider module.

A good example to follow for writing a cloud provider module is the module provided for Linode:

https://github.com/saltstack/salt-cloud/blob/master/saltcloud/clouds/linode.py

If possible it is prefered that libcloud is used to connect to public cloud systems, but if libcloud support is not available or another system makes more sense then by all means, use the other system to connect to the cloud provider.

Os Support For Cloud Vms

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 os 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:

https://github.com/saltstack/salt-bootstrap

If you do not specify a script argument, this script will be used at the default.

If the Salt Bootstrap script does not meet your needs, you may write your own. The script should be written in bash and is a Jinja template. Deploy scripts need to execute a number of functions to do a complete salt setup. These functions include:

1. Install the salt minion. If this can be done via system packages this method is HIGHLY preferred. 2. 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". 3. Start the salt-minion daemon and enable it at startup time. 4. 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: https://github.com/saltstack/salt-cloud/blob/master/saltcloud/deploy/Fedora.sh 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.

Other Generic Deploy Scripts

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

Post-Deploy Commands

Once a minion has been deployed, it has the option to run a salt command. Normally, this would be the state.highstate command, which would finish provisioning the VM. Another common option is state.sls, or for just testing, test.ping. This is configured in the main cloud config file: start_action: state.highstate This is currently considered to be experimental functionality, and may not work well with all providers. If you experience problems with Salt Cloud hanging after Salt is deployed, consider using Startup States instead: http://docs.saltstack.org/en/latest/ref/states/startup.html

Skipping the Deploy Script

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: deploy: False The default for deploy is True. In the profile, you may also set the script option to None: script: None This is the slowest option, since it still uploads the None deploy script and executes it.

Updating Salt Bootstrap

Salt Bootstrap can be updated automatically with salt-cloud: salt-cloud -u salt-cloud --update-bootstrap Bear in mind that this updates to the latest (unstable) version, so use with caution.

Keeping /tmp/ Files

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

Deploy Script Arguments

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: aws image: ami-1624987f size: Micro Instance 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

Core Configuration

A number of core configuration options and some options that are global to the vm profiles can be set in the cloud config file. By default this file is located at /etc/salt/cloud.

Minion Configuration

The default minion configuration is set up in this file. This is where the minions that are created derive their configuration. minion: master: saltmaster.example.com This is the location in particular to specify the location of the salt master.

Cloud Configurations

The data specific to interacting with public clouds is set up here.

Rackspace

Rackspace cloud requires two configuration options: RACKSPACE.user: example_user RACKSPACE.apikey: 123984bjjas87034

Amazon AWS

A number of configuration options are required for Amazon AWS: AWS.id: HJGRYCILJLKJYG AWS.key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn' AWS.keyname: test AWS.securitygroup: quick-start AWS.private_key: /root/test.pem

Linode

Linode requires a single api key, but the default root password also needs to be set: LINODE.apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf LINODE.password: F00barbaz The password needs to be 8 characters and contain lowercase, uppercase and numbers.

Joyent Cloud

The Joyent cloud requires three configuration paramaters. The user name and password that are used to log into the Joyent system, and 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, JOYENT.user: fred JOYENT.password: saltybacon JOYENT.private_key: /root/joyent.pem

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 GOGRID.apikey and the GOGRID.sharedsecret configuration paramaters need to be set in the config file to enable interfacing with GoGrid: GOGRID.apikey: asdff7896asdh789 GOGRID.sharedsecret: saltybacon

OpenStack

OpenStack configuration differs between providers, and at the moment several options need to be specified. This module has been officially tested against the HP and the Rackspace implementations, and some examples are provided for both. # For HP OPENSTACK.identity_url: 'https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/' OPENSTACK.compute_name: Compute OPENSTACK.compute_region: 'az-1.region-a.geo-1' OPENSTACK.tenant: myuser-tenant1 OPENSTACK.user: myuser OPENSTACK.ssh_key_name: mykey OPENSTACK.ssh_key_file: '/etc/salt/hpcloud/mykey.pem' OPENSTACK.password: mypass # For Rackspace OPENSTACK.identity_url: 'https://identity.api.rackspacecloud.com/v2.0/tokens' OPENSTACK.compute_name: cloudServersOpenStack OPENSTACK.compute_region: DFW OPENSTACK.tenant: 5555555 OPENSTACK.user: myuser OPENSTACK.password: mypass OPENSTACK.protocol: ipv4 If you have an API key for your provider, it may be specified instead of a password: OPENSTACK.apikey: 901d3f579h23c8v73q9

IBM SmartCloud Enterprise

In addition to a username and password, the IBM SCE module requires an SSH key, which is currently configured inside IBM's web interface. A location is also required to create instances, but not to query their cloud. This is important, because you need to use salt-cloud --list-locations (with the other options already set) in order to find the name of the location that you want to use. IBMSCE.user: myuser@mycorp.com IBMSCE.password: mypass IBMSCE.ssh_key_name: mykey IBMSCE.ssh_key_file: '/etc/salt/ibm/mykey.pem' IBMSCE.location: Raleigh

Miscellaneous Salt Cloud Options

This page describes various miscellaneous options available in Salt Cloud

Delete SSH Keys

When Salt Cloud deploys an instance, the SSH pub key for the instance is added to the known_hosts file for the user that ran the salt-cloud command. When an instance is deployed, a cloud provider generally recycles the IP address for the instance. When Salt Cloud attempts to deploy an instance using a recycled IP address that has previously been accessed from the same machine, the old key in the known_hosts file will cause a conflict. In order to mitigate this issue, Salt Cloud can be configured to remove old keys from the known_hosts file when destroying the node. In order to do this, the following line needs to be added to the main cloud configuration file: delete_sshkeys: True

Release Notes And Upgrade Instructions

Salt Cloud 0.6.0 Release Notes

The new Salt project, Salt Cloud, is introduced with version 0.6.0. Salt Cloud has been developed to ease the automation and integration of Salt with public cloud providers by allowing cloud vms to be cleanly defined, created and automatically hooked back into a Salt Master. While Salt Cloud is primarily made to build cloud vms to tie into a Salt Mater, it has been created in a generic way, so that it can be used to provision and hook systems of any type via the familiar Salt modules system. This release supports three public cloud providers (all via libcloud), Amazon EC2, Rackspace Cloud and Linode.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.6.0.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.6.0.tar.gz Packages are not yet available, Salt Cloud requires three dependencies, the salt libs, libcloud, and paramiko.

Extensible With Cloud Modules

The Salt loader system has been employed to make adding support for additional public cloud systems just as modular and simple as adding support for new package managers in Salt. Adding support for a new cloud provider is extremely simple, just add a cloud module and everything cleanly links together.

Define VM Profiles

The way a vms is created is done via profiles. Profiles are used to define what properties a vm will have, the cloud provider, the size and the image. centos_rackspace: provider: rackspace image: CentOS 6.2 size: 1024 server os: RHEL6 minion: grains: role: webserver master: salt.example.com This profile will be used to create vms on Rackspace cloud with the CentOS 6.2 image and the Rackspace 1024 vm size. Particulars of the minion config can also be specified. Individual vms can be created from profiles: # salt-cloud -p centos_rackspace web1 This command creates a vms with the name web1 on the Rackspace cloud and connects the new vm to a Salt Master located at salt.example.com. The new VM has the Salt id of web1.

Define Maps of Profiles

When it is desired to have a predefined mapping of many, or a specific group of vms then a cloud map can be defined: centos_rackspace: web1 web2 web3 web4 centos_linode: redis1 riak1 riak2 riak3 ubuntu_ec2: dev1 dev2 cassandra1 cassandra2 cassandra3 This map file will create vms named web 1-4 using the centos_rackspace profile on rackspace, the redis and riak vms on linode and the dev and Cassandra vms on ec2. It can be run with salt-cloud: # salt-cloud -m mapfile When creating more than one vm the -P option can be passed, to make the vms provision in parallel, greatly speeding up large scale expansions of vms.

Salt Cloud 0.7.0 Release Notes

Salt Cloud marches forward with the 0.7.0 release. As is customary for Salt Stack projects the 0.7.0 release is intended to be much more robust and deliver a more complete core feature set. Salt Cloud 0.7.0 is just that. With new tools to help look into what is available on cloud providers, new additions to make cloud management more stateful and the addition of more supported cloud platforms 0.7.0 has greatly enhanced the capabilities of the overall Salt platform.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.7.0.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.7.0.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch, and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. Package availability will be announced on the salt mailing list.

New Cloud Provider Support

The following cloud providers are now supported:
Amazon AWS: http://aws.amazon.com/ec2/
Rackspace Cloud: http://www.rackspace.com/cloud/
Linode
http://www.linode.com/
Joyent
http://joyent.com/
GoGrid
http://www.gogrid.com/

List Available Resources

Setting up Salt Cloud requires knowlege of the available sizes and images on cloud providers. Listing the available images and sizes can now be done with the salt-cloud command: [root@saltmaster]# salt-cloud --list-sizes linode linode Linode 1024 bandwidth: 400 disk: 40960 id: 3 name: Linode 1024 ram: 1024 uuid: 56e6f495190cb2ed1a343f7159ad447cf27d906d Linode 12GB bandwidth: 2000 disk: 491520 id: 8 name: Linode 12GB ram: 12288 uuid: 3d1731ebefdbcb4c283957b43d45f89a01f67c5f Linode 1536 bandwidth: 600 disk: 61440 id: 4 name: Linode 1536 ram: 1536 uuid: f0f28628cc70c5f2656aa3f313588d8509ee3787 Linode 16GB bandwidth: 2000 disk: 655360 id: 9 name: Linode 16GB ram: 16384 uuid: 208cc3c0a60c4eab6ed6861344fef0311c13ffd2 Linode 2048 bandwidth: 800 disk: 81920 id: 5 name: Linode 2048 ram: 2048 uuid: 0c9ee69dc7ef7a4cdce71963f8d18e76c61dd57f Linode 20GB bandwidth: 2000 disk: 819200 id: 10 name: Linode 20GB ram: 20480 uuid: e0a7b61e3830a120eec94459c9fc34ef7c9e0e36 Linode 4GB bandwidth: 1600 disk: 163840 id: 6 name: Linode 4GB ram: 4096 uuid: 09585e0f1d4ef4aad486cfa3d53f9d8960f575e7 Linode 512 bandwidth: 200 disk: 20480 id: 1 name: Linode 512 ram: 512 uuid: 3497f7def3d6081e6f65ac6e577296bc6b810c05 Linode 768 bandwidth: 300 disk: 30720 id: 2 name: Linode 768 ram: 768 uuid: da9f0dbc144aaa234aa5d555426863c8068a8c70 Linode 8GB bandwidth: 2000 disk: 327680 id: 7 name: Linode 8GB ram: 8192 uuid: e08f8a57551297b9310545430c67667f59120606

Destroy!

Salt Cloud can now destroy cloud vms as easily as it can create them. The new --destroy option can be passed to end the life of a vm:
$ salt-cloud -d web1
The map operation can now also destroy vms, the new hard option can be passed which makes vm maps much more stateful. With the hard option the vm maps are viewed as the absolute source of information for the state of cloud resources, and any vm that is not specified in the map file will be destroyed:
[root@saltmaster]# salt-cloud -m /etc/salt/cloud.map -H The following virtual machines are set to be created: web1 riak4 The following virtual machines are set to be destroyed: app7 devtest4 Proceed? [N/y]

Salt Cloud 0.8.0 Release Notes

Salt Cloud has reached another milestone, with the 0.8.0 release. This release includes many improvements to usability, error handling and general stability of the product.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.8.0.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.8.0.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch, and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. Package availability will be announced on the salt mailing list.

Increased Formatting Options

Additional options have been added to salt-cloud -Q, to support the same kinds of formatting already available in Salt: --raw-out --text-out --yaml-out --json-out --no-color

More Helpful Error Messages

As an ongoing effort, we have been cleaning up and adding error messages in an attempt to make salt-cloud more helpful when something goes wrong. This includes displaying messages as they are received from libcloud.

Specify Grains in Map Files

Previously, map files only had the ability to specify a profile name, and the node names that would be associated with it. Now you can also specify grains that will be laid down in each individual node: vm_profile: - mynodename: minion: master: salt-master grains: fromage: tasty These grains can also be specified in the profile itself. When this happens, the grains in map files will override grains in the profile. For example: vm_profile: provider: gogrid size: 512MB image: CentOS 6.2 (64-bit) w/ None os: RHEL6 minion: master: salt.mycompany.com grains: french: fries In this example, mynodename will include grains for both fromage and french, but the master will be salt-master, not salt-mycompany.com.

AWS Improvements

AWS is much more complex to work with than any of the other supported cloud providers. As such, additional configuration has been added in order to accomodate their usage:
AWS.ssh_username:: Because AWS images can include a variety of different usernames for the initial login, this option allows you to specify which one(s) to use to install salt upon firstboot.
AWS.ssh_interface:: AWS instances include both private and public IP addresses. By default, salt-cloud will use the public IP to login. In situations where the salt-master is also located within AWS, the private IP can be used instead.
AWS.location and AWS.availability_zone:: These options allow you to specify from within salt-cloud, which AWS locations your machines spin up in.

Ubuntu Fixes

Ubuntu packages automatically start the service upon installation, and needed to be handled differently in the deploy script. Configuration is now laid down before the package is installed, so that the minion can make its initial start happen with the correct configuration.

Salt Cloud 0.8.1 Release Notes

In a somewhat quicker timeline than usual, Salt Cloud 0.8.1 has been released! While many of the updates in this release focus on stability, users of map files and AWS also have some new features to look forward to.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.8.1.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.8.1.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch, and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. Package availability will be announced on the salt mailing list.

Full Query Option

The -Q or --query option only displays a small amount of information about each virtual machine. This is to keep command-line reports small and manageable. Now the -F or --full-query option can be used to display all of the information about a VM that salt-cloud knows about. The amount of information returned varies between providers, depending on the kinds of functionality available through them.

Increased Map Functionality

Previously, map files were only used for creating VMs. Now they can also be used to query and delete VMs. The -Q, -F and -d options can all be used in conjunction with -m, to display map-specific data. If a VM that is specified in the map does not exist, it will still show up under -Q and -F as "Absent". If a VM specified in the map does not exist when a -d is specified, it will of course be ignored.

Multiple Security Groups in AWS

AWS allows for multiple security groups to be applied to any given VM, but until this release, Salt Cloud only supported managing one. This update allows a list of security groups to be specified. In the main configuration file, an example of multiple security groups would look like: AWS.securitygroup: - default - extra In a profile, an example would be: micro_amazon: provider: aws image: ami-e565ba8c size: Micro Instance os: RHEL6 securitygroup: - default - extra

Bug Fixes

A number of bugs have been fixed in this release. Most of these were internal fixes related to authentication and deployment across various providers. Bug fixes in this release include: Ubuntu users may notice that deploying an instance has become significantly noisier. A change was made to make Ubuntu display information returned as packages are installed, which is more aligned with how yum-based machines already behaved. This also forced these VMs to deploy salt in a much more reliable manner. Requirements listed in requirements.txt are also pulled into setup.py, to make it easy to use the easy_install tool. Most cloud providers default to root as the initial user, but AWS typically providers a different user (ec2-user, ubuntu, bitnami, etc). Deployment on such images must be handled using sudo. Previously, sudo was used to issue all deployment commands, but this failed on images where sudo was not installed by default (such as FreeBSD). Now sudo will only be used with non-root logins.

Salt Cloud 0.8.2 Release Notes

This is a great release for Salt Cloud! New cloud providers have been added, and the deploy functionality has been embiggened! Read on to see the cromulent new features.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.8.2.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.8.2.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch, and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. Package availability will be announced on the salt mailing list.

Select Query Option

The last release of Salt Cloud added the -F/--full query option, to display all information available for a particular instance. We now also have the -S or --select-query option, which lets you specify which fields to display. Any fields not specified will not be displayed, and if you specify a field that doesn't exist on a particular provider, it will be ignored for them. Just add a query.selection option to /etc/salt/cloud like such: query.selection: - id - state - public_ips - keyname - TOTALXFER

os vs script

In a cloud profile, you need to specify which deploy script to use to install Salt on the newly-provisioned VM. The option for this has always been 'os', which has been confusing to some. As of this release, you may now specify 'script' instead of 'os'. If you specify both, the value for 'script' will be used. See the SmartOS Deploy Script below for an example.

SmartOS Deploy Script

Of particular interest to Joyent users may be the new SmartOS deploy script. Salt itself is not fully-supported on SmartOS just yet, in part because ZeroMQ is also not yet supported. When this script is used for deployment, it will automatically install the required libraries and build ZeroMQ, and then use easy_install to install the latest versions of PyZMQ and Salt. To use this, just specify SmartOS as the 'os' or 'script' option in your cloud.profiles: joyent_smartos: provider: joyent size: Extra Small 512 MB image: smartos script: SmartOS

OpenStack and IBM Modules

Support has been added for clouds using OpenStack (OPENSTACK) and for IBM's SmartCloud Enterprise (IBMSCE) offering. We know that people have already started using the OpenStack module, because pull requests have already been merged from the community. This module has been tested against both the HP and the Rackspace implementations of OpenStack. This can be a tricky module to configure, depending on your provider, so some examples are provided here: # For HP OPENSTACK.identity_url: 'https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/' OPENSTACK.compute_name: Compute OPENSTACK.compute_region: 'az-1.region-a.geo-1' OPENSTACK.tenant: myuser-tenant1 OPENSTACK.user: myuser OPENSTACK.ssh_key_name: mykey OPENSTACK.ssh_key_file: '/etc/salt/hpcloud/mykey.pem' OPENSTACK.password: mypass # For Rackspace OPENSTACK.identity_url: 'https://identity.api.rackspacecloud.com/v2.0/tokens' OPENSTACK.compute_name: cloudServersOpenStack OPENSTACK.compute_region: DFW OPENSTACK.tenant: 5555555 OPENSTACK.user: myuser OPENSTACK.password: mypass OPENSTACK.protocol: ipv4 It is important to note that currently, only password-based authentication is provided through the Salt Cloud OpenStack module. IBM has fewer things that need to be configured, but setting them up can be tricky as well. An example might look like: IBMSCE.user: myuser@mycorp.com IBMSCE.password: mypass IBMSCE.ssh_key_name: mykey IBMSCE.ssh_key_file: '/etc/salt/ibm/mykey.pem' IBMSCE.location: Raleigh The location currently must be configured in order to create an instance, but not to query the IBM cloud. This is important, because you need to use salt-cloud --list-locations (with the other options already set) in order to find the name of the location that you want to use.

OpenStack with Salt

This isn't specifically another Salt Cloud feature, but it should be noted that with the release of Salt 0.10.5, OpenStack is not only the first Cloud product, but in fact the first piece of software explicitly supported by both Salt Cloud (from a user perspective) and Salt itself (from an admin perspective).

Salt Cloud Logging

Those who have tried to hack on Salt Cloud may have discovered a complete lack of logging support. With this release, Salt Cloud has started to implement the logging features already available in Salt. The default log location is /var/log/salt/cloud (with a default level of warn), but it can be changed in your cloud configuration file: log_file: /var/log/salt/cloud log_level_logfile: debug If you would like to change the default logging level for the command line, you can also configure that in the same place: log_level: debug Check salt-cloud --help for a list of logging levels, which can also be specified from the command line.

Salt Cloud 0.8.3 Release Notes

Welcome to 0.8.3! While there are some new features, this release of Salt Cloud is primarily targeted at stability. Read on to see what's happened.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.8.3.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.8.3.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. Package availability will be announced on the salt mailing list.

No Deploy

Salt Cloud was originally intended to spin up machines and deploy Salt on them, but several use cases have arisen in which this is not the appropriate action. For instance, when booting into new platforms which may not even support Salt just yet, it makes no sense to try and install a non-existant package. In these instances, you can add the --no-deploy argument to the salt-cloud command to skip running the deploy script. It is also possible to configure Salt Cloud to default to never deploying: deploy: False

Firing Events

Salt Cloud is starting to make use of Salt's event system. If you are watching the event bus on the Salt Master, you can now watch for events to fire when minions are created or destroyed.

Start Actions

This is an experimental feature which some users may find handy. You may now configure a start_action for a deployed VM: start_action: state.highstate If configured, when the salt-cloud command runs the deploy script, it will open a subprocess to wait for the salt-minion service to start, and check in with the master (via the salt event bus). This feature does not currently work smoothly with all providers, particularly the ones which do not use "root" as the default login users. Your mileage will vary.

Exception Handling

There were a handful of spots in the code which would exit when an error occurred, sometimes without any meaningful error messages. This was was neither helpful to the user, nor Pythonic. Errors now should fire an exception of some sort, and if the error is Salt- or Salt Cloud-specific, a SaltException will be fired. This also helps pave the way for API usage of Salt Cloud.

Provider-Specific Actions

This is largely a programmatic addition at this point, which will continue to expand into userland. All providers supported by libcloud provide a minimum level of functionality that Salt Cloud takes advantage of. Most providers also include a number of "extra" functions which are non-standard. Some of these are critical in certain instances. For instance, most providers will shut down a VM for you when you send a destroy command, but Joyent requires you to manually shut it down first. This was previously only doable via their web interface. You may now pass a supported --action (or -a) to a cloud provider: salt-cloud --action stop joyentvm1 All cloud providers support the destroy command via an action: salt-cloud -a destroy mymachine1 mymachine2 mymachine2

Human-Readable States

Most of our cloud providers are accessed via libcloud, which provides a numerical code declaring the current state of the machine. This state is viewable via the various query options. Unfortunately, if you don't know what the codes mean, they're largely useless to you. Now, with the -Q or --query option, a human-readable state (i.e. RUNNING) will de displayed instead). It should be noted that because some users are running salt-cloud via another script, the -F/--full-query and -S/--select-query options still return the numerical code.

Various other Features and Stability Fixes

The above features addressed many stability issues. Additionally, the following have been addressed. Salt Cloud requires at least libcloud 0.11.4. If you are not running at least this version, an exception will be fired. A certain amount of minion configuration is required for all VMs. If you fail to specify any, a (mostly empty) minion config will be created for you. The default master for this config will be "salt". Previously, Joyent supported all Salt Cloud features without using Salt Cloud's own built-in deploy function. This is no longer the case, and so the Joyent module has been updated appropriately. Some log settings where previously ignored. This has been fixed. The Rackspace module previously would silently strip certain characters from a VM name. It now has a base set of characters that it will verify against, and raise an exception if an illegal character was specified. This functionality is also available for other cloud providers, but not currently set up for them. AWS introduced a new region in Sydney. This region is not available in the latest official libcloud release, but if you happen to be running libcloud out of trunk, it will be supported by Salt Cloud. Additional logging and PEP-8 fixes have also been applied. This should only affect developers.

Salt Cloud 0.8.4 Release Notes

Welcome to 0.8.4! Aside from various bug fixes, the most important improvements in this release are to the deploy scripts. Read on to see what's happened.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.8.4.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. The Ubuntu PPA is being managed by Sean Channel. Package availability will be announced on the salt mailing list.

Salt Bootstrap

By far the biggest change to Salt Cloud is the inclusion of the salt-bootstrap script, made possible by the genius of Alec Koumjian and Pedro Algarvio. From this point on, each release of Salt Cloud will include the latest stable version of bootstrap-salt-minion.sh in the deploy folder. This is a generic, POSIX-compliant deployment script, which autodetects your OS, and installs the latest version of Salt accordingly. For more information, see: https://github.com/saltstack/salt-bootstrap To use this deploy script explicitly, set the script option to bootstrap-salt-minion in the profile for your VM. For instance: aws-archlinux: provider: aws image: ami-0356da6a size: Micro Instance script: bootstrap-salt-minion ssh_username: root For those of you still using "os" in your profiles, it should be noted that this option was renamed to "script" in 0.8.2, and your configuration should be updated accordingly.

Optional Script Option

As mentioned above, usage of the "os" argument has been deprecated in favor of the "script" argument. However, "script" is now optional. If you do not specify this option, salt-cloud will default to bootstrap-salt-minion for you. If you do not want any deployment scripts run, you still have the following options available to you. From the command line, use the --no-deploy option: salt-cloud --no-deploy -p myprofile mymachine In the Salt Cloud configuration, set: deploy: False Or in the profile, set the script option to None: script: None

Other Generic Deploy Scripts

If you want to be assured of always using the latest Salt Bootstrap script, there are now a few generic templates available in the deploy directory of your saltcloud source tree: 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.

Salt Cloud 0.8.5 Release Notes

Welcome to 0.8.5! Some important things have happened in this release, that you'll want to take note of. The first thing that may trip you up when installing directly is that Paramiko is no longer a dependency, and botocore and sshpass are new dependencies. Read on to see what else has happened.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.8.5.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. The Ubuntu PPA is being managed by Sean Channel. Package availability will be announced on the salt mailing list.

Salt Bootstrap

In 0.8.4, the default deploy script was set to bootstrap-salt-minion. Since then, the Salt Boostrap script has been extended to be able to install more than just minions, and as such, has been renamed. It is now called bootstrap-salt, and has been renamed in Salt Cloud accordingly. Check out the salt-bootstrap project for more details: https://github.com/saltstack/salt-bootstrap Just another reminder: For those of you still using "os" in your profiles, this option was renamed to "script" in 0.8.2, and your configuration should be updated accordingly.

Updating Salt Bootstrap

If you like running the latest and greatest version of salt-bootstrap, but you're sick of tracking down the source directory to update it, a new option has been added to update it for you. salt-cloud -u salt-cloud --update-bootstrap Bear in mind that this updates to the latest (unstable) version, so use with caution.

Modify AWS Tags

One of the features of AWS is the ability to tag resources. In fact, under the hood, the names given to EC2 instances by salt-cloud are actually just stored as a tag called Name. The ability to manage tags on AWS instances has now been added to Salt Cloud. salt-cloud -a get_tags mymachine salt-cloud -a set_tags mymachine tag1=somestuff tag2='Other stuff' salt-cloud -a del_tags mymachine tag1,tag2,tag3

Rename AWS Instances

As mentioned above, AWS instances are named via a tag. However, renaming an instance by renaming its tag will cause the salt keys to mismatch. A rename function has been added which renames both the instance, and the salt keys. salt-cloud -a rename mymachine newname=yourmachine

AWS Termination Protection

AWS allows the user to enable and disable termination protection on a specific instance. An instance with this protection enabled cannot be destroyed. salt-cloud -a enable_term_protect mymachine salt-cloud -a disable_term_protect mymachine

Setting up New Salt Masters

It has become increasingly common for users to set up multi-hierarchal infrastructures using Salt Cloud. This sometimes involves setting up an instance to be a master in addition to a minion. With that in mind, you can now law down master configuration on a machine by specifying master options in the profile or map file. make_master: True This will cause Salt Cloud to generate master keys for the instance, and tell salt-bootstrap to install the salt-master package, in addition to the salt-minion package. The default master configuration is usually appropriate for most users, and will not be changed unless specific master configuration has been added to the profile or map: master: user: root interface: 0.0.0.0

Keeping /tmp/ Files

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

Deploy Script Arguments

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: aws image: ami-1624987f size: Micro Instance 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

Remove Old SSH Keys

When an instance is destroyed, its IP address is usually recycled back into the IP pool. When such an IP is reassigned to you, and the old key is still in your known_hosts file, the deploy script will fail due to mismatched SSH keys. To mitigate this, add the following to your main cloud configuration: delete_sshkeys: True

SALT CLOUD 0.6.0 RELEASE NOTES

The new Salt project, Salt Cloud, is introduced with version 0.6.0. Salt Cloud has been developed to ease the automation and integration of Salt with public cloud providers by allowing cloud vms to be cleanly defined, created and automatically hooked back into a Salt Master.

While Salt Cloud is primarily made to build cloud vms to tie into a Salt Mater, it has been created in a generic way, so that it can be used to provision and hook systems of any type via the familiar Salt modules system.

This release supports three public cloud providers (all via libcloud), Amazon EC2, Rackspace Cloud and Linode.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.6.0.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.6.0.tar.gz Packages are not yet available, Salt Cloud requires three dependencies, the salt libs, libcloud, and paramiko.

Extensible With Cloud Modules

The Salt loader system has been employed to make adding support for additional public cloud systems just as modular and simple as adding support for new package managers in Salt. Adding support for a new cloud provider is extremely simple, just add a cloud module and everything cleanly links together.

Define VM Profiles

The way a vms is created is done via profiles. Profiles are used to define what properties a vm will have, the cloud provider, the size and the image. centos_rackspace: provider: rackspace image: CentOS 6.2 size: 1024 server os: RHEL6 minion: grains: role: webserver master: salt.example.com This profile will be used to create vms on Rackspace cloud with the CentOS 6.2 image and the Rackspace 1024 vm size. Particulars of the minion config can also be specified. Individual vms can be created from profiles: # salt-cloud -p centos_rackspace web1 This command creates a vms with the name web1 on the Rackspace cloud and connects the new vm to a Salt Master located at salt.example.com. The new VM has the Salt id of web1.

Define Maps of Profiles

When it is desired to have a predefined mapping of many, or a specific group of vms then a cloud map can be defined: centos_rackspace: web1 web2 web3 web4 centos_linode: redis1 riak1 riak2 riak3 ubuntu_ec2: dev1 dev2 cassandra1 cassandra2 cassandra3 This map file will create vms named web 1-4 using the centos_rackspace profile on rackspace, the redis and riak vms on linode and the dev and Cassandra vms on ec2. It can be run with salt-cloud: # salt-cloud -m mapfile When creating more than one vm the -P option can be passed, to make the vms provision in parallel, greatly speeding up large scale expansions of vms.

SALT CLOUD 0.7.0 RELEASE NOTES

Salt Cloud marches forward with the 0.7.0 release. As is customary for Salt Stack projects the 0.7.0 release is intended to be much more robust and deliver a more complete core feature set. Salt Cloud 0.7.0 is just that.

With new tools to help look into what is available on cloud providers, new additions to make cloud management more stateful and the addition of more supported cloud platforms 0.7.0 has greatly enhanced the capabilities of the overall Salt platform.

Documentation

The documentation for Salt Cloud can be found on Read the Docs: http://salt-cloud.readthedocs.org

Download

Salt Cloud can be downloaded and install via pypi or github: http://pypi.python.org/packages/source/s/salt-cloud/salt-cloud-0.7.0.tar.gz https://github.com/downloads/saltstack/salt-cloud/salt-cloud-0.7.0.tar.gz Some packages have been made available for salt-cloud and more on on their way. Packages for Arch, and FreeBSD are being made available thanks to the work of Christer Edwards, and packages for RHEL and Fedora are being created by Clint Savage. Package availability will be announced on the salt mailing list.

New Cloud Provider Support

The following cloud providers are now supported:
Amazon AWS: http://aws.amazon.com/ec2/
Rackspace Cloud: http://www.rackspace.com/cloud/
Linode
http://www.linode.com/
Joyent
http://joyent.com/
GoGrid
http://www.gogrid.com/

List Available Resources

Setting up Salt Cloud requires knowlege of the available sizes and images on cloud providers. Listing the available images and sizes can now be done with the salt-cloud command: [root@saltmaster]# salt-cloud --list-sizes linode linode Linode 1024 bandwidth: 400 disk: 40960 id: 3 name: Linode 1024 ram: 1024 uuid: 56e6f495190cb2ed1a343f7159ad447cf27d906d Linode 12GB bandwidth: 2000 disk: 491520 id: 8 name: Linode 12GB ram: 12288 uuid: 3d1731ebefdbcb4c283957b43d45f89a01f67c5f Linode 1536 bandwidth: 600 disk: 61440 id: 4 name: Linode 1536 ram: 1536 uuid: f0f28628cc70c5f2656aa3f313588d8509ee3787 Linode 16GB bandwidth: 2000 disk: 655360 id: 9 name: Linode 16GB ram: 16384 uuid: 208cc3c0a60c4eab6ed6861344fef0311c13ffd2 Linode 2048 bandwidth: 800 disk: 81920 id: 5 name: Linode 2048 ram: 2048 uuid: 0c9ee69dc7ef7a4cdce71963f8d18e76c61dd57f Linode 20GB bandwidth: 2000 disk: 819200 id: 10 name: Linode 20GB ram: 20480 uuid: e0a7b61e3830a120eec94459c9fc34ef7c9e0e36 Linode 4GB bandwidth: 1600 disk: 163840 id: 6 name: Linode 4GB ram: 4096 uuid: 09585e0f1d4ef4aad486cfa3d53f9d8960f575e7 Linode 512 bandwidth: 200 disk: 20480 id: 1 name: Linode 512 ram: 512 uuid: 3497f7def3d6081e6f65ac6e577296bc6b810c05 Linode 768 bandwidth: 300 disk: 30720 id: 2 name: Linode 768 ram: 768 uuid: da9f0dbc144aaa234aa5d555426863c8068a8c70 Linode 8GB bandwidth: 2000 disk: 327680 id: 7 name: Linode 8GB ram: 8192 uuid: e08f8a57551297b9310545430c67667f59120606

Destroy!

Salt Cloud can now destroy cloud vms as easily as it can create them. The new --destroy option can be passed to end the life of a vm:
$ salt-cloud -d web1
The map operation can now also destroy vms, the new hard option can be passed which makes vm maps much more stateful. With the hard option the vm maps are viewed as the absolute source of information for the state of cloud resources, and any vm that is not specified in the map file will be destroyed:
[root@saltmaster]# salt-cloud -m /etc/salt/cloud.map -H The following virtual machines are set to be created: web1 riak4 The following virtual machines are set to be destroyed: app7 devtest4 Proceed? [N/y]

Author

Thomas S. Hatch <thatch@saltstack.com> and many others, please see the Authors file

Copyright

2012, SaltStack, Inc.

Referenced By

salt-cloud(1)