openstack-manuals/doc/user-guide/hot/section_environment.xml

<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="environments">
  <!--WARNING: This file is automatically generated. Do not edit it.-->
  <title>Environments</title>
  <para>The environment affects the runtime behaviour of a template. It provides a way
to override the resource implementations and a mechanism to place parameters
that the service needs.</para>
  <para>To fully understand the runtime behavior you have to consider what plug-ins are
installed on the cloud you're using.</para>
  <section xml:id="environment-file-format">
    <?dbhtml stop-chunking?>
    <title>Environment file format</title>
    <para>The environment is a yaml text file that contains two main sections:</para>
    <variablelist role="definition_list">
      <varlistentry>
        <term>
          <literal>parameters</literal>
        </term>
        <listitem>
          <para>A map of key/pair values.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <literal>resource_registry</literal>
        </term>
        <listitem>
          <para>Definition of custom resources.</para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>Use the -e option of the <command>heat stack-create</command> command to
create a stack using with the environment defined in such a file.</para>
    <para>You can also provide environment parameters as a list of key/value pairs using
the -P option of the <command>heat stack-create</command> command.</para>
    <para>In the following example the environment is read from the <literal>my_env.yaml</literal>
file and an extra parameter is provided using the -P option:</para>
    <programlisting language="console">$ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml</programlisting>
  </section>
  <section xml:id="global-and-effective-environments">
    <?dbhtml stop-chunking?>
    <title>Global and effective environments</title>
    <para>The environment used for a stack is the combination of the environment you
use with the template for the stack, and a global environment that is
determined by your cloud operator. An entry in the user environment takes
precedence over the global environment. OpenStack includes a default global
environment, but you cloud operator can add additional environment entries.</para>
    <!--TODO:
move this to a heat section in the admin-guide-cloud

The cloud operator can add to the global environment
by putting environment files in a configurable directory wherever
the Orchestration engine runs. The configuration variable is named
"environment_dir" is found in the "[DEFAULT]" section
of "/etc/heat/heat.conf". The default for that directory is
"/etc/heat/environment.d". Its contents are combined in whatever
order the shell delivers them when the service starts up,
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:

::

   heat stack-create my_stack -P "some_parm=bla" -f my_tmpl.yaml-->
  </section>
  <section xml:id="define-values-for-a-template-arguments">
    <?dbhtml stop-chunking?>
    <title>Define values for a template arguments</title>
    <para>You can define values for the template arguments in the <literal>parameters</literal> section
of an environment file:</para>
    <programlisting language="yaml">parameters:
  KeyName: my_keypair
  InstanceType: m1.tiny
  ImageId: F18-x86_64-cfntools</programlisting>
  </section>
  <section xml:id="create-and-override-resources">
    <?dbhtml stop-chunking?>
    <title>Create and override resources</title>
    <para>You can create or override resources in the <literal>resource_registry</literal> section of an
environment file. The resource you provide in this manner must have an
identifier, and references either other resources IDs or the URL of an existing
template file.</para>
    <para>The following example maps the new <literal>OS::Networking::FloatingIP</literal>
resource to the existing <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIP.html">OS::Nova::FloatingIP</link></literal> resource:</para>
    <programlisting language="yaml">resource_registry:
  "OS::Networking::FloatingIP": "OS::Nova::FloatingIP"</programlisting>
    <para>You can use wilcards to map multiple resources:</para>
    <programlisting language="yaml">resource_registry:
  "OS::Network*": "OS::Neutron*"</programlisting>
    <para>To create or override a resource with a custom resource, create a template file
to define this resource, and provide the URL to the template file in the
environment file:</para>
    <programlisting language="yaml">resource_registry:
  "AWS::EC2::Instance": file:///path/to/my_instance.yaml</programlisting>
    <para>The supported URL scheme are <literal>file</literal>, <literal>http</literal> and <literal>https</literal>.</para>
    <note>
      <para>The template file extension must be <literal>.yaml</literal> or <literal>.template</literal>, or it will
not be treated as a custom template resource.</para>
    </note>
    <para>You can limit the usage of a custom resource to a specific resource of the
template:</para>
    <programlisting language="yaml">resource_registry:
  resources:
    my_db_server:
      "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml</programlisting>
  </section>
</section>