================================ 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: .. code-block:: yaml /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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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. .. code-block:: bash 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: .. code-block:: yaml 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: .. code-block:: bash 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. .. code-block:: bash 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: .. code-block:: bash 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. 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. .. code-block:: bash 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. .. code-block:: bash 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 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. 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. .. code-block:: yaml 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 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. .. code-block:: yaml my-instance-name: cloud.present: - 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. .. code-block:: yaml 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: .. code-block:: bash 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: .. code-block:: python import salt.cloud import pprint client = salt.cloud.CloudClient('/etc/salt/cloud') nodes = client.query() pprint.pprint(nodes)