182 lines
4.9 KiB
ReStructuredText
182 lines
4.9 KiB
ReStructuredText
..
|
|
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.
|
|
|
|
Template resources provide a feature similar to the
|
|
:hotref:`AWS::CloudFormation::Stack` resource, but also provide a way to:
|
|
|
|
* Define new resource types and build your own resource library.
|
|
* Override the default behaviour of existing resource types.
|
|
|
|
To achieve this:
|
|
|
|
* The Orchestration client gets the associated template files and passes them
|
|
along in the ``files`` section of the ``POST stacks/`` API request.
|
|
* The environment in the Orchestration engine manages the mapping of resource
|
|
type to template creation.
|
|
* The Orchestration engine translates template parameters into resource
|
|
properties.
|
|
|
|
The following examples illustrate how you can use a custom template to define
|
|
new types of resources. These examples use a custom template stored in a
|
|
:file:`my_nova.yaml` file:
|
|
|
|
.. code-block:: yaml
|
|
|
|
heat_template_version: 2014-10-16
|
|
|
|
parameters:
|
|
key_name:
|
|
type: string
|
|
description: Name of a KeyPair
|
|
|
|
resources:
|
|
server:
|
|
type: OS::Nova::Server
|
|
properties:
|
|
key_name: {get_param: key_name}
|
|
flavor: m1.small
|
|
image: ubuntu-trusty-x86_64
|
|
|
|
|
|
|
|
Use the template filename as type
|
|
=================================
|
|
|
|
The following template defines the :file:`my_nova.yaml` file as value for the
|
|
``type`` property of a resource:
|
|
|
|
.. code-block:: yaml
|
|
|
|
heat_template_version: 2014-10-16
|
|
|
|
resources:
|
|
my_server:
|
|
type: my_nova.yaml
|
|
properties:
|
|
key_name: my_key
|
|
|
|
The ``key_name`` argument of the ``my_nova.yaml`` template gets its value from
|
|
the ``key_name`` property of the new template.
|
|
|
|
.. note::
|
|
|
|
The above reference to ``my_nova.yaml`` assumes it is in the same directory.
|
|
You can use any of the following forms:
|
|
|
|
* Relative path (``my_nova.yaml``)
|
|
* Absolute path (``file:///home/user/templates/my_nova.yaml``)
|
|
* Http URL (``http://example.com/templates/my_nova.yaml``)
|
|
* Https URL (``https://example.com/templates/my_nova.yaml``)
|
|
|
|
To create the stack run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ heat stack-create -f main.yaml stack1
|
|
|
|
|
|
Define a new resource type
|
|
==========================
|
|
|
|
You can associate a name to the ``my_nova.yaml`` template in an environment
|
|
file. If the name is already known by the Orchestration module then your new
|
|
resource will override the default one.
|
|
|
|
In the following example a new ``OS::Nova::Server`` resource overrides the
|
|
default resource of the same name.
|
|
|
|
An :file:`env.yaml` environment file holds the definition of the new resource:
|
|
|
|
.. code-block:: yaml
|
|
|
|
resource_registry:
|
|
"OS::Nova::Server": my_nova.yaml
|
|
|
|
.. note::
|
|
|
|
See :ref:`environments` for more detail about environment files.
|
|
|
|
You can now use the new ``OS::Nova::Server`` in your new template:
|
|
|
|
.. code-block:: yaml
|
|
|
|
heat_template_version: 2014-10-16
|
|
|
|
resources:
|
|
my_server:
|
|
type: OS::Nova::Server
|
|
properties:
|
|
key_name: my_key
|
|
|
|
To create the stack run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ heat stack-create -f main.yaml -e env.yaml example-two
|
|
|
|
|
|
Get access to nested attributes
|
|
===============================
|
|
There are implicit attributes of a template resource. Accessing
|
|
nested attributes require heat_template_version '2014-10-16' or
|
|
higher and can be accessed as follows:
|
|
|
|
.. code-block:: yaml
|
|
|
|
heat_template_version: 2014-10-16
|
|
|
|
resources:
|
|
my_server:
|
|
type: my_nova.yaml
|
|
|
|
outputs:
|
|
test_out:
|
|
value: {get_attr: my_server, resource.server, first_address}
|
|
|
|
|
|
Making your template resource more "transparent"
|
|
================================================
|
|
.. note::
|
|
|
|
Available since 2015.1 (Kilo).
|
|
|
|
If you wish to be able to return the ID of one of the inner resources
|
|
instead of the nested stack's identifier, you can add the special reserved
|
|
output "OS::stack_id" to your template resource.
|
|
|
|
.. code-block:: yaml
|
|
|
|
heat_template_version: 2014-10-16
|
|
|
|
resources:
|
|
server:
|
|
type: OS::Nova::Server
|
|
|
|
outputs:
|
|
OS::stack_id:
|
|
value: {get_resource: server}
|
|
|
|
Now when you use "get_resource" from the outer template heat
|
|
will use the nova server id and not the template resource identifier.
|