In addition to the salt-cloud command, Salt Cloud can be called from Salt, in a variety of different ways. Most users will be interested in either the execution module or the state module, but it is also possible to call Salt Cloud as a runner.
Because the actual work will be performed on a remote minion, the normal Salt Cloud configuration must exist on any target minion that needs to execute a Salt Cloud command. Because Salt Cloud now supports breaking out configuration into individual files, the configuration is easily managed using Salt's own file.managed state function. For example, the following directories allow this configuration to be managed easily:
/etc/salt/cloud.providers.d/
/etc/salt/cloud.profiles.d/
Keep in mind that when creating minions, Salt Cloud will create public and private minion keys, upload them to the minion, and place the public key on the machine that created the minion. It will not attempt to place any public minion keys on the master, unless the minion which was used to create the instance is also the Salt Master. This is because granting arbitrary minions access to modify keys on the master is a serious security risk, and must be avoided.
The cloud module is available to use from the command line. At the moment, almost every standard Salt Cloud feature is available to use. The following commands are available:
This command is designed to show images that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). Listing images requires a provider to be configured, and specified:
salt myminion cloud.list_images my-cloud-provider
This command is designed to show sizes that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). This command is not available for all cloud providers; see the provider-specific documentation for details. Listing sizes requires a provider to be configured, and specified:
salt myminion cloud.list_sizes my-cloud-provider
This command is designed to show locations that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). This command is not available for all cloud providers; see the provider-specific documentation for details. Listing locations requires a provider to be configured, and specified:
salt myminion cloud.list_locations my-cloud-provider
This command is used to query all configured cloud providers, and display all instances associated with those accounts. By default, it will run a standard query, returning the following fields:
This command may also be used to perform a full query or a select query, as described below. The following usages are available:
salt myminion cloud.query
salt myminion cloud.query list_nodes
salt myminion cloud.query list_nodes_full
This command behaves like the query command, but lists all information concerning each instance as provided by the cloud provider, in addition to the fields returned by the query command.
salt myminion cloud.full_query
This command behaves like the query command, but only returned select fields as defined in the /etc/salt/cloud configuration file. A sample configuration for this section of the file might look like:
query.selection:
- id
- key_name
This configuration would only return the id and key_name fields, for those cloud providers that support those two fields. This would be called using the following command:
salt myminion cloud.select_query
This command is used to create an instance using a profile that is configured on the target minion. Please note that the profile must be configured before this command can be used with it.
salt myminion cloud.profile ec2-centos64-x64 my-new-instance
Please note that the execution module does not run in parallel mode. Using multiple minions to create instances can effectively perform parallel instance creation.
This command is similar to the profile command, in that it is used to create a new instance. However, it does not require a profile to be pre-configured. Instead, all of the options that are normally configured in a profile are passed directly to Salt Cloud to create the instance:
salt myminion cloud.create my-ec2-config my-new-instance \
image=ami-1624987f size='Micro Instance' ssh_username=ec2-user \
securitygroup=default delvol_on_destroy=True
Please note that the execution module does not run in parallel mode. Using multiple minions to create instances can effectively perform parallel instance creation.
This command is used to destroy an instance or instances. This command will search all configured providers and remove any instance(s) which matches the name(s) passed in here. The results of this command are non-reversable and should be used with caution.
salt myminion cloud.destroy myinstance
salt myminion cloud.destroy myinstance1,myinstance2
This command implements both the action and the function commands used in the standard salt-cloud command. If one of the standard action commands is used, an instance name must be provided. If one of the standard function commands is used, a provider configuration must be named.
salt myminion cloud.action start instance=myinstance
salt myminion cloud.action show_image provider=my-ec2-config \
image=ami-1624987f
The actions available are largely dependant upon the module for the specific cloud provider. The following actions are available for all cloud providers:
A subset of the execution module is available through the cloud state module. Not all functions are currently included, because there is currently insufficient code for them to perform statefully. For example, a command to create an istance may be issued with a series of options, but those options cannot currently be statefully managed. Additional states to manage these options will be released at a later time.
This state will ensure that an instance is present inside a particular cloud provider. Any option that is normally specified in the cloud.create execution module and function may be declared here, but only the actual presence of the instance will be managed statefully.
my-instance-name:
cloud.present:
- provider: my-ec2-config
- image: ami-1624987f
- size: 'Micro Instance'
- ssh_username: ec2-user
- securitygroup: default
- delvol_on_destroy: True
This state will ensure that an instance is present inside a particular cloud provider. This function calls the cloud.profile execution module and function, but as with cloud.present, only the actual presence of the instance will be managed statefully.
my-instance-name:
cloud.present:
- profile ec2-centos64-x64
This state will ensure that an instance (identified by name) does not exist in any of the cloud providers configured on the target minion. Please note that this state is non-reversable and may be considered especially destructive when issued as a cloud state.
my-instance-name:
cloud.absent
The cloud runner module is executed on the master, and performs actions using the configuration and Salt modules on the master itself. This means that any public minion keys will also be properly accepted by the master.
Using the functions in the runner module is no different than using those in the execution module, outside of the behavior described in the above paragraph. The following functions are available inside the runner:
Outside of the standard usage of salt-run itself, commands are executed as usual:
salt-run cloud.profile ec2-centos64-x86_64 my-instance-name
The execution, state and runner modules ultimately all use the CloudClient library that ships with Salt. To use the CloudClient library locally (either on the master or a minion), create a client object and issue a command against it:
import salt.cloud
import pprint
client = salt.cloud.CloudClient('/etc/salt/cloud')
nodes = client.query()
pprint.pprint(nodes)
Current Salt release: 2014.1.6
Docs for previous releases on salt.rtfd.org.
Getting Started With Rackspace
Getting Started With SoftLayer