Environments¶

Global templates¶

A global template directory allows files to be pre-loaded in the global environment. A global template is determined by your cloud operator. An entry in the user template takes precedence over the global environment. OpenStack includes a default global template, but your cloud operator can add additional template entries.

The cloud operator can add new global templates by putting template files in a configurable directory wherever the Orchestration engine runs. The configuration variable is named template_dir and is found in the [DEFAULT] section of /etc/heat/heat.conf. The default for that directory is /etc/heat/templates. 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_tmpl.yaml file from the example below has been put in the template_dir, other templates which we used to create stacks could contain following way to include my_tmpl.yaml in it:

resourceA:
  type: {get_file: "my_tmpl.yaml"}

Define values for template arguments¶

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

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

Define defaults to parameters¶

You can define default values for all template arguments in the parameter_defaults section of an environment file. These defaults are passed into all template resources:

parameter_defaults:
  KeyName: heat_key

Mapping resources¶

You can map one resource to another in the resource_registry section of an environment file. The resource you provide in this manner must have an identifier, and must reference either another resource’s ID or the URL of an existing template file.

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

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

You can use wildcards to map multiple resources, for example to map all OS::Neutron resources to OS::Network:

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

Override a resource with a custom resource¶

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 schemes are file, http and https.

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

Pause stack creation, update or deletion on a given resource¶

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

To set a hook, add either hooks: $hook_name (for example hooks: pre-update) to the resource’s dictionary. You can also use a list (hooks: [pre-create, pre-update]) to stop on several actions.

You can combine hooks with other resources properties such as provider templates or type mapping:

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 pauses the resource action until the hook clears. Any resources that depend on the paused action wait as well. Non-dependent resources are created in parallel unless they have their own hooks.

It is possible to perform a wild card match using an asterisk (*) in the resource name. For example, the following entry pauses while creating app_server and database_server, but not server or app_network:

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

Clear hooks by signaling the resource with {unset_hook: $hook_name} (for example {unset_hook: pre-update}).

Retrieving events¶

By default events are stored in the database and can be retrieved via the API. Using the environment, you can register an endpoint which will receive events produced by your stack, so that you don’t have to poll Heat.

You can specify endpoints using the event_sinks property:

event_sinks:
  - type: zaqar-queue
    target: myqueue
    ttl: 1200

Restrict update or replace of a given resource¶

If you want to restrict update or replace of a resource when your stack is being updated, you can set restricted_actions in the resources section of resource_registry.

To restrict update or replace, add restricted_actions: update or restricted_actions: replace to the resource dictionary. You can also use [update, replace] to restrict both actions.

You can combine restricted actions with other resources properties such as provider templates or type mapping or hooks:

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

It is possible to perform a wild card match using an asterisk (*) in the resource name. For example, the following entry restricts replace for app_server and database_server, but not server or app_network:

resource_registry:
  resources:
    "*_server":
      restricted_actions: replace