mirror of
https://github.com/saltstack/salt.git
synced 2025-04-17 10:10:20 +00:00
Merge pull request #9357 from techhat/clouddocs
Add doc about using Salt Cloud from Salt
This commit is contained in:
Colton Myers
commit
99ad03ca99
3 changed files with 350 additions and 2 deletions
|
|
@ -96,13 +96,21 @@ Troubleshooting Steps
|
|||
Extending Salt Cloud
|
||||
====================
|
||||
|
||||
Salt cloud extensions work in a way similar to Salt modules. Therefore
|
||||
Salt Cloud extensions work in a way similar to Salt modules. Therefore
|
||||
extending Salt cloud to manage more public cloud providers and operating
|
||||
systems is easy.
|
||||
|
||||
* :doc:`Adding Cloud Providers <cloud>`
|
||||
* :doc:`Adding OS Support <deploy>`
|
||||
|
||||
Using Salt Cloud from Salt
|
||||
==========================
|
||||
|
||||
Several Salt Cloud modules exist within Salt itself in order to manage cloud
|
||||
instances using Salt's own powerful feature set.
|
||||
|
||||
* :doc:`Using Salt Cloud from Salt <salt>`
|
||||
|
||||
Feature Comparison
|
||||
==================
|
||||
|
||||
|
|
|
|||
338
doc/topics/cloud/salt.rst
Normal file
338
doc/topics/cloud/salt.rst
Normal file
|
|
@ -0,0 +1,338 @@
|
|||
================================
|
||||
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, or directly from the local API.
|
||||
|
||||
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 dependant 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)
|
||||
|
||||
|
||||
APIClient
|
||||
---------
|
||||
Salt Cloud may also be called using Salt's standard APIClient, which requires
|
||||
``external_auth`` to be configured on the Salt Master. Once the master has been
|
||||
configured properly, this library may be used to issue Salt Cloud commands:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.client.api
|
||||
client = salt.client.api.APIClient()
|
||||
cmd = {
|
||||
'eauth': 'pam',
|
||||
'fun': 'runner.cloud.profile',
|
||||
'kwarg': {
|
||||
'prof': 'ec2-centos64-x86_64',
|
||||
'names': 'my-instance-name',
|
||||
},
|
||||
'password': 'verybadpass',
|
||||
'username': 'myuser',
|
||||
}
|
||||
client.run(cmd)
|
||||
|
||||
|
|
@ -163,7 +163,7 @@ def action(
|
|||
instance=None,
|
||||
**kwargs):
|
||||
'''
|
||||
Execute a single action on the given map/provider/instance
|
||||
Execute a single action on the given provider/instance
|
||||
|
||||
CLI Example:
|
||||
|
||||
|
|
@ -171,6 +171,8 @@ def action(
|
|||
|
||||
salt '*' cloud.action start instance=myinstance
|
||||
salt '*' cloud.action stop instance=myinstance
|
||||
salt '*' cloud.action show_image provider=my-ec2-config \
|
||||
image=ami-1624987f
|
||||
'''
|
||||
client = _get_client()
|
||||
info = client.action(fun, cloudmap, names, provider, instance, kwargs)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue