Chapter 7. Working with heat templates

The custom configurations in this guide use heat templates and environment files to define certain aspects of the overcloud. This chapter contains a basic introduction to the structure of heat templates in the context of Red Hat OpenStack Platform. The purpose of a template is to define and create a stack, which is a collection of resources that heat creates, and the configuration of the resources. Resources are objects in OpenStack and can include compute resources, network configurations, security groups, scaling rules, and custom resources.

The structure of a heat template has three main sections:

Parameters

Parameters are settings passed to heat. Use these parameters to define and customize both default and non-default values. Define these parameters in the parameters section of a template.

Resources

Resources are the specific objects that you want to create and configure as part of a stack. OpenStack contains a set of core resources that span across all components. Define resources in the resources section of a template.

Output

These are values passed from heat after the stack creation. You can access these values either through the heat API or through the client tools. Define these values in the output section of a template.

When heat processes a template, it creates a stack for the template and a set of child stacks for resource templates. This hierarchy of stacks descends from the main stack that you define with your template. You can view the stack hierarchy with the following command: 

$ heat stack-list --show-nested

7.1. Core heat templates

Red Hat OpenStack Platform contains a core heat template collection for the overcloud. You can find this collection in the /usr/share/openstack-tripleo-heat-templates directory.

There are many heat templates and environment files in this collection. This section contains information about the main files and directories that you can use to customize your deployment.

overcloud.j2.yaml

This file is the main template file used to create the overcloud environment. This file uses Jinja2 syntax and iterates over certain sections in the template to create custom roles. The Jinja2 formatting is rendered into YAML during the overcloud deployment process.

overcloud-resource-registry-puppet.j2.yaml

This file is the main environment file that you use to create the overcloud environment. This file contains a set of configurations for Puppet modules on the overcloud image. After the director writes the overcloud image to each node, heat starts the Puppet configuration for each node using the resources registered in this environment file. This file uses Jinja2 syntax and iterates over certain sections in the template to create custom roles. The Jinja2 formatting is rendered into YAML during the overcloud deployment process.

roles_data.yaml

This file contains definitions of the roles in an overcloud, and maps services to each role.

network_data.yaml

This file contains definitions of the networks in an overcloud and their properties, including subnets, allocation pools, and VIP status. The default network_data.yaml file contains only the default networks: External, Internal Api, Storage, Storage Management, Tenant, and Management. You can create a custom network_data.yaml file and include it in the openstack overcloud deploy command with the -n option.

plan-environment.yaml

This file contains definitions of the metadata for your overcloud plan, including the plan name, the main template that you want to use, and environment files that you want to apply to the overcloud.

capabilities-map.yaml

This file contains a mapping of environment files for an overcloud plan. Use this file to describe and enable environment files in the director web UI. If you include custom environment files in the environments directory but do not define these files in the capabilities-map.yaml file, you can find these environment files in the Other sub-tab of the Overall Settings page on the web UI.

environments

This directory contains additional heat environment files that you can use with your overcloud creation. These environment files enable extra functions for your Red Hat OpenStack Platform environment. For example, you can use the cinder-netapp-config.yaml environment file to enable NetApp back end storage for the Block Storage service (cinder). If you include custom environment files in the environments directory but do not define these files in the capabilities-map.yaml file, you can find these environment files in the Other sub-tab of the Overall Settings page on the web UI.

network

This directory contains a set of heat templates that you can use to create isolated networks and ports.

puppet

This directory contains puppet templates. The overcloud-resource-registry-puppet.j2.yaml environment file uses the files in the puppet directory to drive the application of the Puppet configuration on each node.

puppet/services

This directory contains heat templates for all services in the composable service architecture.

extraconfig

This directory contains templates that you can use to enable extra functionality. For example, you can use the extraconfig/pre_deploy/rhel-registration directory to register your nodes with the Red Hat Content Delivery network, or with your own Red Hat Satellite server.