openstack-manuals/doc/hot-guide/source/environment.rst

Environments

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.

To fully understand the runtime behavior you have to consider what plug-ins are installed on the cloud you're using.

Environment file format

The environment is a yaml text file that contains two main sections:

parameters

A map of key/pair values.

resource_registry

Definition of custom resources.

Use the -e option of the heat stack-create command to create a stack using with the environment defined in such a file.

You can also provide environment parameters as a list of key/value pairs using the -P option of the heat stack-create command.

In the following example the environment is read from the my_env.yaml file and an extra parameter is provided using the -P option:

$ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml

Global and effective environments

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.

Define values for a template arguments

You can define values for the template arguments in the parameters section of an environment file:

parameters:
  KeyName: my_keypair
  InstanceType: m1.tiny
  ImageId: F18-x86_64-cfntools

Create and override resources

You can create or override resources in the resource_registry 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.

The following example maps the new OS::Networking::FloatingIP resource to the existing OS::Nova::FloatingIP resource:

resource_registry:
  "OS::Networking::FloatingIP": "OS::Nova::FloatingIP"

You can use wildcards to map multiple resources:

resource_registry:
  "OS::Network*": "OS::Neutron*"

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:

resource_registry:
  "AWS::EC2::Instance": file:///path/to/my_instance.yaml

The supported URL scheme are file, http and https.

Note

The template file extension must be .yaml or .template, or it will not be treated as a custom template resource.

You can limit the usage of a custom resource to a specific resource of the template:

resource_registry:
  resources:
    my_db_server:
      "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml