# Using the Salt Modules for Cloud

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/

## Minion Keys

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.

## Execution Module

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:

### list_images

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

### list_sizes

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

### list_locations

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

### query

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:

`id`

  The name or ID of the instance, as used by the cloud provider.

`image`

  The disk image that was used to create this instance.

`private_ips`

  Any public IP addresses currently assigned to this instance.

`public_ips`

  Any private IP addresses currently assigned to this instance.

`size`

  The size of the instance; can refer to RAM, CPU(s), disk space, etc., depending on the cloud provider.

`state`

  The running state of the instance; for example, `running`, `stopped`, `pending`, etc. This state is dependent upon the provider.

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

### full_query

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

### select_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

### profile

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.

### create

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='t1.micro' 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.

### destroy

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

### action

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 dependent upon the module for the specific cloud provider. The following actions are available for all cloud providers:

`list_nodes`

  This is a direct call to the `query` function as described above, but is only performed against a single cloud provider. A provider configuration must be included.

`list_nodes_select`

  This is a direct call to the `full_query` function as described above, but is only performed against a single cloud provider. A provider configuration must be included.

`list_nodes_select`

  This is a direct call to the `select_query` function as described above, but is only performed against a single cloud provider. A provider configuration must be included.

`show_instance`

  This is a thin wrapper around `list_nodes`, which returns the full information about a single instance. An instance name must be provided.

## State Module

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

### cloud.present

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:
        - cloud_provider: my-ec2-config
        - image: ami-1624987f
        - size: 't1.micro'
        - ssh_username: ec2-user
        - securitygroup: default
        - delvol_on_destroy: True

### cloud.profile

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.profile:
        - profile: ec2-centos64-x64

### cloud.absent

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

## Runner Module

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:

- list_images

- list_sizes

- list_locations

- query

- full_query

- select_query

- profile

- destroy

- action

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

## CloudClient

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)

## Reactor

Examples of using the reactor with Salt Cloud are available in the ec2-autoscale-reactor and salt-cloud-reactor formulas.