Chapter 4. Adding heat templates and environment files with the director Operator

If you want to customize your overcloud or enable certain features, you must create heat templates and environment files for the customizations you want. You can include your custom templates and environment files with your deployment to configure your overcloud. In the context of the director Operator, you store these files in ConfigMap resources before running an overcloud deployment.

4.1. Understanding custom template usage with the director Operator

The director Operator converts a core set of templates into Ansible playbooks that you apply to provisioned nodes when you are ready to configure the Red Hat OpenStack Platform software on each node.

To add your own custom heat templates and custom roles file into the overcloud deployment, you must archive the template files into a tarball file and include the binary contents of the tarball file in an OpenShift ConfigMap named tripleo-tarball-config. This tarball file can contain complex directory structures to extend the core set of templates. The director Operator extracts the files and directories from the tarball file into the same directory as the core set of heat templates. If any of your custom templates have the same name as a template in the core collection, the custom template overrides the core template.

Note

All references in the environment files must be relative to the TripleO Heat Templates where the tarball is extracted.

For example, your tarball file might contain the following YAML files:

$ tar -tf custom-config.tar.gz
custom-template.yaml
net-config-static-bridge.yaml
net-config-static.yaml
roles_data.yaml

The custom-template.yaml file is a new custom template that does not override any existing templates. However, the net-config-static-bridge.yaml and net-config-static.yaml files override the default heat templates for preprovisioned node network configuration and the roles_data.yaml file overrides the default roles configuration.

Additional resources

4.2. Adding custom templates to the overcloud configuration

Archive your custom templates into a tarball file so that you can include these templates as a part of your overcloud deployment.

Prerequisites

  • Ensure your OpenShift Container Platform cluster is operational and you have installed the director Operator correctly.
  • Ensure that you have installed the oc command line tool on your workstation.
  • Create the custom templates that you want to apply to provisioned nodes.

Procedure

  1. Navigate to the location of your custom templates:

    $ cd ~/custom_templates
  2. Archive the templates into a tarball:

    $ tar -cvzf custom-config.tar.gz *.yaml
  3. Create the tripleo-tarball-config ConfigMap and use the tarball as data:

    $ oc create configmap tripleo-tarball-config --from-file=custom-config.tar.gz -n openstack

Verification

  1. View the ConfigMap:

    $ oc get configmap/tripleo-tarball-config -n openstack

4.3. Understanding custom environment file usage with the director Operator

To enable features or set parameters in the overcloud, you must include environment files with your deployment runs. The director Operator uses a ConfigMap named heat-env-config to store and retrieve environment files. Use the following syntax for the data in the heat-env-config ConfigMap:

...
data:
  <environment_file_name>: |+
    <environment_file_contents>

For example, your heat-env-config ConfigMap might contain two environment files:

...
data:
  network_environment.yaml: |+
    resource_registry:
      OS::TripleO::Compute::Net::SoftwareConfig: net-config-static-bridge-compute.yaml
  cloud_name.yaml: |+
    parameter_defaults:
      CloudDomain: ocp4.example.com
      CloudName: overcloud.ocp4.example.com
      CloudNameInternal: overcloud.internalapi.ocp4.example.com
      CloudNameStorage: overcloud.storage.ocp4.example.com
      CloudNameStorageManagement: overcloud.storagemgmt.ocp4.example.com
      CloudNameCtlplane: overcloud.ctlplane.ocp4.example.com
  • The first environment file is named network_environment.yaml and contains a resource_registry section to map network interface configuration to the appropriate heat templates.
  • The second environment file is named cloud_name.yaml and contains a parameter_defaults section to set parameters relating to overcloud host names.
  • When the director Operator deploys the overcloud, the Operator includes both files from the heat-env-config ConfigMap with the deployment.

Additional resources

4.4. Adding custom environment files to the overcloud configuration

Upload a set of custom environment files from a directory to a ConfigMap that you can include as a part of your overcloud deployment.

Prerequisites

  • Ensure your OpenShift Container Platform cluster is operational and you have installed the director Operator correctly.
  • Ensure that you have installed the oc command line tool on your workstation.
  • Create custom environment files for your overcloud deployment.

Procedure

  1. Create the heat-env-config ConfigMap and use the directory that contains the environment files as data:

    $ oc create configmap -n openstack heat-env-config --from-file=~/custom_environment_files/ --dry-run=client -o yaml | oc apply -f -

Verification

  1. View the ConfigMap:

    $ oc get configmap/heat-env-config -n openstack