5.5 KiB

Raw Blame History

Environments

The environment is used to affect the runtime behavior of the template. It provides a way to override the resource 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 operator has installed.

Format

It is a yaml text file with three main sections "resource_registry", "parameters" and "parameter_defaults".

Command line usage

heat stack-create my_stack -e my_env.yaml -P "some_parm=bla" -f my_tmpl.yaml

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 operator. Combination is asymmetric: an entry in the user environment takes 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 operator can add additional environment entries.

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" 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

Usage examples

1) Pass parameters into heat

parameters:
  KeyName: heat_key
  InstanceType: m1.micro
  ImageId: F18-x86_64-cfntools

2) Define defaults to parameters

This is especially useful when you have many template resources and you want the same value in each. Note: these defaults will get passed down into all template resources. :

parameter_defaults:
  KeyName: heat_key

3) Deal with the mapping of Quantum to Neutron

resource_registry:
  "OS::Quantum*": "OS::Neutron*"

So all existing resources which can be matched with "OS::Neutron*" will be mapped to "OS::Quantum*" accordingly.

4) Override a resource type with a custom template resource

resource_registry:
  "AWS::EC2::Instance": file:///home/mine/my_instance_with_better_defaults.yaml

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. The supported URL types are "http, https and file".

5) Always map resource type X to Y

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

6) Use default resources except one for a particular resource in the template

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

7) Pause stack creation/update on a given resource

If you want to debug your stack as it's being created or updated or if you want to run it in phases you can set pre-create and pre-update hooks in the resources section of resource_registry.

To set a hook, add either hooks: pre-create or hooks: pre-update to the resource's dictionary. You can also use the [pre-create, pre-update] to stop on both actions.

Hooks can be combined with other resources properties (e.g. provider templates or type mapping).

Example:

resource_registry:
  resources:
    my_server:
      "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml
      hooks: pre-create
    nested_stack:
      nested_resource:
        hooks: pre-update
      another_resource:
        hooks: [pre-create, pre-update]

When heat encounters a resource that has a hook, it will pause the resource action until the hook is cleared. Any resources that depend on it will wait as well. Any resources that don't will be created in parallel (unless they have hooks, too).

It is also possible to do a partial match by putting an asterisk (*) in the name.

This example:

resource_registry:
  resources:
    "*_server":
      hooks: pre-create

will pause while creating app_server and database_server but not server or app_network.

Hook is cleared by signaling the resource with {unset_hook: pre-create} (or pre-update).

5.5 KiB Raw Blame History