mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 00:55:19 +00:00
321 lines
11 KiB
ReStructuredText
321 lines
11 KiB
ReStructuredText
================================
|
|
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='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.
|
|
|
|
.. 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 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.
|
|
|
|
.. code-block:: yaml
|
|
|
|
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.
|
|
|
|
.. code-block:: yaml
|
|
|
|
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.
|
|
|
|
.. 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)
|
|
|
|
Reactor
|
|
-------
|
|
Examples of using the reactor with Salt Cloud are available in the
|
|
:formula_url:`ec2-autoscale-reactor <ec2-autoscale-reactor>` and
|
|
:formula_url:`salt-cloud-reactor <salt-cloud-reactor>` formulas.
|