mirror of
https://github.com/saltstack/salt.git
synced 2025-04-17 10:10:20 +00:00
moved previous intro to new quick start topic (topics/cloud/qs.rst)
added new intro that explains the salt cloud configuration files added an inheritance and minion startup state example to topics/cloud/config.rst
This commit is contained in:
Jacob Hammons
parent
826fea6582
commit
26d4991cb3
6 changed files with 190 additions and 106 deletions
BIN
doc/_static/cloud-settings-inheritance.png
vendored
Normal file
BIN
doc/_static/cloud-settings-inheritance.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
|
|
@ -1,3 +1,5 @@
|
|||
.. _salt-cloud-config:
|
||||
|
||||
==================
|
||||
Core Configuration
|
||||
==================
|
||||
|
|
@ -39,11 +41,26 @@ be used here.
|
|||
In particular, this is the location to specify the location of the salt master
|
||||
and its listening port, if the port is not set to the default.
|
||||
|
||||
Similar to most other settings, Minion configuration settings are inherited
|
||||
across configuration files. For example, the master setting might be contained
|
||||
in the main ``cloud`` configuration file as demonstrated above, but additional
|
||||
settings can be placed in the provider or profile:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
ec2-web:
|
||||
size: t1.micro
|
||||
minion:
|
||||
environment: test
|
||||
startup_states: sls
|
||||
sls_list:
|
||||
- web
|
||||
|
||||
Cloud Configuration Syntax
|
||||
==========================
|
||||
|
||||
The data specific to interacting with public clouds is set up here.
|
||||
The data specific to interacting with public clouds is set up :ref:`here
|
||||
<cloud-provider-specifics>`.
|
||||
|
||||
Cloud provider configuration settings can live in several places. The first is in
|
||||
``/etc/salt/cloud``:
|
||||
|
|
|
|||
|
|
@ -7,120 +7,54 @@ Salt Cloud
|
|||
.. raw:: html
|
||||
:file: index.html
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
Configuration
|
||||
=============
|
||||
Salt Cloud provides a powerful interface to interact with cloud hosts. This
|
||||
interface is tightly integrated with Salt, and new virtual machines
|
||||
are automatically connected to your Salt master after creation.
|
||||
|
||||
Salt Cloud is built-in to Salt and is configured on and executed from your Salt Master.
|
||||
Since Salt Cloud is designed to be an automated system, most configuration
|
||||
is done using the following YAML configuration files:
|
||||
|
||||
Define a Provider
|
||||
-----------------
|
||||
- ``/etc/salt/cloud``: The main configuration file, contains global settings
|
||||
that apply to all cloud hosts. See :ref:`Salt Cloud Configuration
|
||||
<salt-cloud-config>`.
|
||||
|
||||
The first step is to add the credentials for your cloud host. Credentials
|
||||
and other settings provided by the cloud host are stored in provider configuration files.
|
||||
Provider configurations contain the details needed to connect to a cloud host such as EC2, GCE, Rackspace, etc.,
|
||||
and any global options that you want set on your cloud minions (such as the location of your Salt Master).
|
||||
- ``/etc/salt/cloud.providers.d/*.provider.conf``: Contains settings that
|
||||
configure a specific cloud host, such as credentials, region settings, and so
|
||||
on. Since configuration varies significantly between each cloud host,
|
||||
a separate file is created for each cloud host. In Salt Cloud, a provider is
|
||||
synonymous with a cloud host (Amazon EC2, Google Compute Engine, Rackspace,
|
||||
and so on). See :ref:`Provider Specifics <cloud-provider-specifics>`.
|
||||
|
||||
On your Salt Master, browse to ``/etc/salt/cloud.providers.d/`` and create a file called ``<provider>.provider.conf``,
|
||||
replacing ``<provider>`` with ``ec2``, ``softlayer``, and so on. The name helps you identify the contents, and is not
|
||||
important as long as the file ends in ``.conf``.
|
||||
- ``/etc/salt/cloud.profiles.d/*.profile.conf``: Contains settings that define
|
||||
a specific VM type. Each profile specifies a parent provider that defines the
|
||||
cloud host in which the VM is created. A profile defines the system type and
|
||||
image, and any other settings that are specific to this VM type. Based on
|
||||
your needs, you might define different profiles for web servers, database
|
||||
servers, and so on. See :ref:`VM Profiles <cloud-provider-specifics>`.
|
||||
|
||||
Next, browse to the :ref:`Provider specifics <cloud-provider-specifics>` and add any required settings for your
|
||||
cloud host to this file. Here is an example for Amazon EC2:
|
||||
Configuration Inheritance
|
||||
=========================
|
||||
Configuration settings are inherited in order from the cloud config =>
|
||||
providers => profile.
|
||||
|
||||
.. code-block:: yaml
|
||||
.. image:: /_static/cloud-settings-inheritance.png
|
||||
:align: center
|
||||
:width: 40%
|
||||
|
||||
my-ec2:
|
||||
driver: ec2
|
||||
# Set the EC2 access credentials (see below)
|
||||
#
|
||||
id: 'HJGRYCILJLKJYG'
|
||||
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
|
||||
# Make sure this key is owned by root with permissions 0400.
|
||||
#
|
||||
private_key: /etc/salt/my_test_key.pem
|
||||
keyname: my_test_key
|
||||
securitygroup: default
|
||||
# Optional: Set up the location of the Salt Master
|
||||
#
|
||||
minion:
|
||||
master: saltmaster.example.com
|
||||
For example, if you wanted to use the same image for
|
||||
all virtual machines for a specific provider, the image name could be placed in
|
||||
the provider file. This value is inherited by all profiles that use that
|
||||
provider, but is overridden if a image name is defined in the profile.
|
||||
|
||||
The required configuration varies between cloud hosts so make sure you read the provider specifics.
|
||||
Most configuration settings can be defined in any file, the main difference
|
||||
being how that setting is inherited.
|
||||
|
||||
List Cloud Provider Options
|
||||
---------------------------
|
||||
|
||||
You can now query the cloud provider you configured for available locations,
|
||||
images, and sizes. This information is used when you set up VM profiles.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud --list-locations <provider_name> # my-ec2 in the previous example
|
||||
salt-cloud --list-images <provider_name>
|
||||
salt-cloud --list-sizes <provider_name>
|
||||
|
||||
Replace ``<provider_name>`` with the name of the provider configuration you defined.
|
||||
|
||||
Create VM Profiles
|
||||
------------------
|
||||
|
||||
On your Salt Master, browse to ``/etc/salt/cloud.profiles.d/`` and create a file called ``<provider>.profiles.conf``,
|
||||
replacing ``<provider>`` with ``ec2``, ``softlayer``, and so on. The file must end in ``.conf``.
|
||||
|
||||
You can now add any custom profiles you'd like to define to this file. Here are a few examples:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
micro_ec2:
|
||||
provider: my-ec2
|
||||
image: ami-d514f291
|
||||
size: t1.micro
|
||||
|
||||
medium_ec2:
|
||||
provider: my-ec2
|
||||
image: ami-d514f291
|
||||
size: m3.medium
|
||||
|
||||
large_ec2:
|
||||
provider: my-ec2
|
||||
image: ami-d514f291
|
||||
size: m3.large
|
||||
|
||||
Notice that the ``provider`` in our profile matches the provider name that we defined? That is how Salt Cloud
|
||||
knows how to connect to create a VM with these attributes.
|
||||
|
||||
Create VMs
|
||||
----------
|
||||
|
||||
VMs are created by calling ``salt-cloud`` with the following options:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud -p <profile> <name1> <name2> ...
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud -p micro_ec2 minion1 minion2
|
||||
|
||||
Destroy VMs
|
||||
-----------
|
||||
|
||||
Add a ``-d`` and the minion name you provided to destroy:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud -d minion1 minion2
|
||||
|
||||
Query VMs
|
||||
---------
|
||||
|
||||
You can view details about the VMs you've created using ``--query``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud --query
|
||||
QuickStart
|
||||
==========
|
||||
The :ref:`Salt Cloud Quickstart <salt-cloud-qs>` walks you through defining
|
||||
a provider, a VM profile, and shows you how to create virtual machines using Salt Cloud.
|
||||
|
||||
Using Salt Cloud
|
||||
================
|
||||
|
|
@ -221,4 +155,5 @@ Tutorials
|
|||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
QuickStart <qs>
|
||||
Using Salt Cloud with the Event Reactor <reactor>
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _salt-cloud-map:
|
||||
|
||||
==============
|
||||
Cloud Map File
|
||||
==============
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _salt-cloud-profiles:
|
||||
|
||||
VM Profiles
|
||||
===========
|
||||
|
||||
|
|
|
|||
128
doc/topics/cloud/qs.rst
Normal file
128
doc/topics/cloud/qs.rst
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
.. _salt-cloud-qs:
|
||||
|
||||
=====================
|
||||
Salt Cloud Quickstart
|
||||
=====================
|
||||
|
||||
Salt Cloud is built-in to Salt and is configured on and executed from your Salt
|
||||
Master. On some platforms, Salt Cloud is installed by the ``salt-cloud``
|
||||
package.
|
||||
|
||||
This quickstart walks you through the basic steps of setting up a cloud host
|
||||
and defining some virtual machines to create.
|
||||
|
||||
Define a Provider
|
||||
-----------------
|
||||
The first step is to add the credentials for your cloud host. Credentials
|
||||
and other settings provided by the cloud host are stored in provider configuration files.
|
||||
Provider configurations contain the details needed to connect to a cloud host such as EC2, GCE, Rackspace, etc.,
|
||||
and any global options that you want set on your cloud minions (such as the location of your Salt Master).
|
||||
|
||||
On your Salt Master, browse to ``/etc/salt/cloud.providers.d/`` and create a file called ``<provider>.provider.conf``,
|
||||
replacing ``<provider>`` with ``ec2``, ``softlayer``, and so on. The name helps you identify the contents, and is not
|
||||
important as long as the file ends in ``.conf``.
|
||||
|
||||
Next, browse to the :ref:`Provider specifics <cloud-provider-specifics>` and add any required settings for your
|
||||
cloud host to this file. Here is an example for Amazon EC2:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
my-ec2:
|
||||
driver: ec2
|
||||
# Set the EC2 access credentials (see below)
|
||||
#
|
||||
id: 'HJGRYCILJLKJYG'
|
||||
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
|
||||
# Make sure this key is owned by root with permissions 0400.
|
||||
#
|
||||
private_key: /etc/salt/my_test_key.pem
|
||||
keyname: my_test_key
|
||||
securitygroup: default
|
||||
# Optional: Set up the location of the Salt Master
|
||||
#
|
||||
minion:
|
||||
master: saltmaster.example.com
|
||||
|
||||
The required configuration varies between cloud hosts so make sure you read the provider specifics.
|
||||
|
||||
List Cloud Provider Options
|
||||
---------------------------
|
||||
You can now query the cloud provider you configured for available locations,
|
||||
images, and sizes. This information is used when you set up VM profiles.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud --list-locations <provider_name> # my-ec2 in the previous example
|
||||
salt-cloud --list-images <provider_name>
|
||||
salt-cloud --list-sizes <provider_name>
|
||||
|
||||
Replace ``<provider_name>`` with the name of the provider configuration you defined.
|
||||
|
||||
Create VM Profiles
|
||||
------------------
|
||||
On your Salt Master, browse to ``/etc/salt/cloud.profiles.d/`` and create a file called ``<provider>.profiles.conf``,
|
||||
replacing ``<provider>`` with ``ec2``, ``softlayer``, and so on. The file must end in ``.conf``.
|
||||
|
||||
You can now add any custom profiles you'd like to define to this file. Here are a few examples:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
micro_ec2:
|
||||
provider: my-ec2
|
||||
image: ami-d514f291
|
||||
size: t1.micro
|
||||
|
||||
medium_ec2:
|
||||
provider: my-ec2
|
||||
image: ami-d514f291
|
||||
size: m3.medium
|
||||
|
||||
large_ec2:
|
||||
provider: my-ec2
|
||||
image: ami-d514f291
|
||||
size: m3.large
|
||||
|
||||
Notice that the ``provider`` in our profile matches the provider name that we defined? That is how Salt Cloud
|
||||
knows how to connect to create a VM with these attributes.
|
||||
|
||||
Create VMs
|
||||
----------
|
||||
VMs are created by calling ``salt-cloud`` with the following options:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud -p <profile> <name1> <name2> ...
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud -p micro_ec2 minion1 minion2
|
||||
|
||||
Destroy VMs
|
||||
-----------
|
||||
Add a ``-d`` and the minion name you provided to destroy:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud -d minion1 minion2
|
||||
|
||||
Query VMs
|
||||
---------
|
||||
You can view details about the VMs you've created using ``--query``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-cloud --query
|
||||
|
||||
Cloud Map
|
||||
---------
|
||||
Now that you know how to create and destoy individual VMs, next you should
|
||||
learn how to use a cloud map to create a number of VMs at once.
|
||||
|
||||
Cloud maps let you define a map of your infrastructure and quickly provision
|
||||
any number of VMs. On subsequent runs, any VMs that do not exist are created,
|
||||
and VMs that are already configured are left unmodified.
|
||||
|
||||
See :ref:`Cloud Map File <salt-cloud-map>`.
|
||||
|
||||
Loading…
Add table
Reference in a new issue