Sync environment and composition docs from openstack-manuals

Change-Id: Ib9ca5ffa4df5fd9ed6245d359fe1a8a54a477433
Closes-bug: #1366845

doc/source/template_guide/composition.rst

@@ -0,0 +1,123 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _composition:
+
+====================
+Template composition
+====================
+
+When writing complex templates you are encouraged to break up your
+template into separate smaller templates. These can then be brought
+together using template resources. This is a mechanism to define a resource
+using a template, thus composing one logical stack with multiple templates.
+
+
+How to use template resources for composition
+---------------------------------------------
+
+Template resources do a very similar job to
+AWS::CloudFormation::Stack, but they are more powerful as they allow a
+template to "stand in for" any resource type.
+
+Template resources can be used to do the following:
+
+ * Define new resource types (make you own resource library).
+ * Override the default behaviour of existing resource types.
+
+The way this is achieved is:
+
+ * The heat client gets the associated template files and passes them
+   along in the "files" section of the "POST stacks/".
+ * The environment in Orchestration engine manages the mapping of resource type
+   to template creation.
+ * Translation of the template parameters into resource properties.
+
+Let's go through some examples. In all examples assume the
+same resource template. This is a simple wrapper around a nova server
+(my_nova.yaml).
+
+.. code-block:: yaml
+
+  heat_template_version: 2013-05-23
+  parameters:
+    key_name:
+      type: string
+      description: Name of a KeyPair
+  resources:
+    server:
+      type: OS::Nova::Server
+      properties:
+        key_name: {get_param: key_name}
+        flavor: my.best
+        image: the_one_i_always_use
+
+
+Example 1
+~~~~~~~~~
+
+In this example you will not map a resource type name at all, but
+directly specify the template URL as the resource type.
+
+Your main template (main.yaml) would look like this.
+
+.. code-block:: yaml
+
+  heat_template_version: 2013-05-23
+  resources:
+    my_server:
+      type: my_nova.yaml
+      properties:
+        key_name: my_key
+
+Some notes about URLs:
+
+The above reference to my_nova.yaml assumes it is in the same directory.
+You could use any of the following forms:
+
+ * Relative path (type: my_nova.yaml)
+ * Absolute path (type: file:///home/user/templates/my_nova.yaml)
+ * Http URL (type: http://example.com/templates/my_nova.yaml)
+ * Https URL (type: https://example.com/templates/my_nova.yaml)
+
+
+To create the stack, run::
+
+  $ heat stack-create -f main.yaml example-one
+
+Example 2
+~~~~~~~~~
+
+In this example you will use the environment (env.yaml) to override the
+OS::Nova::Server with my_nova to get the defaults you want.
+
+.. code-block:: yaml
+
+  resource_registry:
+    "OS::Nova::Server": my_nova.yaml
+
+A more detailed discussion on this can be found here :ref:`environments`
+
+Now you can use "OS::Nova::Server" in our top level template (main.yaml).
+
+.. code-block:: yaml
+
+  resources:
+    my_server:
+      type: OS::Nova::Server
+      properties:
+        key_name: my_key
+
+To create the stack, run::
+
+  $ heat stack-create -f main.yaml -e env.yaml example-two

doc/source/template_guide/environment.rst

@@ -18,11 +18,12 @@ Environments
 ============
 
 The environment is used to affect the runtime behaviour of the
-template. It provides a way to override the default resource
+template. It provides a way to override the resource
-implementation and the parameters passed to Heat.
+implementations and provide a mechanism to place parameters
+that the service needs.
 
 To fully understand the runtime behavior you also have to consider
-what plug-ins the cloud provider has installed.
+what plug-ins the cloud operator has installed.
 
 ------
 Format
@@ -44,21 +45,21 @@ Global and effective environments
 
 The environment used for a stack is the combination of (1) the
 environment given by the user with the template for the stack and (2)
-a global environment that is determined by the cloud provider.
+a global environment that is determined by the cloud operator.
-Combination is asymmetric: an entry in the first environment takes
+Combination is asymmetric: an entry in the user environment takes
-precedence over an entry in the second.  The OpenStack software
+precedence over the global environment.  The OpenStack software
 includes a default global environment, which supplies some resource
 types that are included in the standard documentation.  The cloud
-provider can add additional environment entries.
+operator can add additional environment entries.
 
-The cloud provider can add to the global environment
+The cloud operator can add to the global environment
 by putting environment files in a configurable directory wherever
 the heat engine runs.  The configuration variable is named
-"environment_dir" and is found in the "heat.common.config" module (AKA
+"environment_dir" is found in the "[DEFAULT]" section
-the "[DEFAULT]" section) of "/etc/heat/heat.conf".  The default for
+of "/etc/heat/heat.conf".  The default for that directory is
-that directory is "/etc/heat/environment.d".  Its contents are
+"/etc/heat/environment.d".  Its contents are combined in whatever
-combined in whatever order the shell delivers them when the heat
+order the shell delivers them when the service starts up,
-engine starts up, which is the time when these files are read.
+which is the time when these files are read.
 
 If the "my_env.yaml" file from the example above had been put in the
 "environment_dir" then the user's command line could be this:
@@ -100,7 +101,7 @@ will be mapped to "OS::Quantum*" accordingly.
 
 Please note that the template resource URL here must end with ".yaml"
 or ".template", or it will not be treated as a custom template
-resource.
+resource. The supported URL types are "http, https and file".
 
 4) Always map resource type X to Y
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/source/template_guide/index.rst

@@ -19,8 +19,9 @@ Template Guide
 
    hot_guide
    hot_spec
+   environment
+   composition
    openstack
    cfn
    contrib
-   environment
    functions