Merge pull request #31733 from jacobhammons/cloud-docs

docs to clarify cloud configuration

doc/topics/cloud/config.rst

@@ -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``:

doc/topics/cloud/index.rst

@@ -7,120 +7,57 @@ Salt Cloud
 .. raw:: html
  :file: index.html
 
-Getting Started
-===============
-
-Salt Cloud is built-in to Salt and is configured on and executed from your Salt Master.
-
-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
+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.
+
+Since Salt Cloud is designed to be an automated system, most configuration
+is done using the following YAML configuration files:
+
+- ``/etc/salt/cloud``: The main configuration file, contains global settings
+  that apply to all cloud hosts. See :ref:`Salt Cloud Configuration
+  <salt-cloud-config>`.
+
+- ``/etc/salt/cloud.providers.d/*.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
+  should be 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>`.
+
+- ``/etc/salt/cloud.profiles.d/*.conf``: Contains settings that define
+  a specific VM type. A profile defines the systems specs and image, and any
+  other settings that are specific to this VM type. Each specific VM type is
+  called a profile, and multiple profiles can be defined in a profile file.
+  Each profile references a parent provider that defines the cloud host in
+  which the VM is created (the provider settings are in the provider
+  configuration explained above).  Based on your needs, you might define
+  different profiles for web servers, database servers, and so on. See :ref:`VM
+  Profiles <cloud-provider-specifics>`.
+
+Configuration Inheritance
+=========================
+Configuration settings are inherited in order from the cloud config =>
+providers => profile.
+
+.. image:: /_static/cloud-settings-inheritance.png
+   :align: center
+   :width: 40%
+
+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.
+
+Most configuration settings can be defined in any file, the main difference
+being how that setting is inherited.
+
+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 +158,5 @@ Tutorials
 .. toctree::
     :maxdepth: 3
 
+    QuickStart <qs>
     Using Salt Cloud with the Event Reactor <reactor>

doc/topics/cloud/map.rst

@@ -1,3 +1,5 @@
+.. _salt-cloud-map:
+
 ==============
 Cloud Map File
 ==============

doc/topics/cloud/profiles.rst

@@ -1,3 +1,5 @@
+.. _salt-cloud-profiles:
+
 VM Profiles
 ===========
 

doc/topics/cloud/qs.rst

@@ -0,0 +1,138 @@
+.. _salt-cloud-qs:
+
+=====================
+Salt Cloud Quickstart
+=====================
+
+Salt Cloud is built-in to Salt, and the easiest way to run Salt Cloud is
+directly from your Salt Master. On most platforms you can install the
+``salt-cloud`` package from the same repo that you used to install Salt.
+
+This quickstart walks you through the basic steps of setting up a cloud host
+and defining some virtual machines to create.
+
+.. note:: Salt Cloud has its own process and does not rely on the Salt Master,
+   so it can be installed on a standalone minion instead of your Salt Master.
+
+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>.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 ``<profile>.conf``, replacing ``<profile>`` 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 to a cloud host 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>`.
+