Chapter 4. Configuration hooks

Use configuration hooks to inject your own custom configuration functions into the overcloud deployment process. You can create hooks to inject custom configuration before and after the main overcloud services configuration, and hooks for modifying and including Puppet-based configuration.

4.1. First boot: customizing first boot configuration

Director uses cloud-init to perform configuration on all nodes after the initial creation of the overcloud. You can use the NodeUserData resource types to call cloud-init.

OS::TripleO::NodeUserData
cloud-init configuration to apply to all nodes.
OS::TripleO::Controller::NodeUserData
cloud-init configuration to apply to Controller nodes.
OS::TripleO::Compute::NodeUserData
cloud-init configuration to apply to Compute nodes.
OS::TripleO::CephStorage::NodeUserData
cloud-init configuration to apply to Ceph Storage nodes.
OS::TripleO::ObjectStorage::NodeUserData
cloud-init configuration to apply to Object Storage nodes.
OS::TripleO::BlockStorage::NodeUserData
cloud-init configuration to apply to Block Storage nodes.
OS::TripleO::[ROLE]::NodeUserData
cloud-init configuration to apply to custom nodes. Replace [ROLE] with the composable role name.

In this example, update the nameserver with a custom IP address on all nodes:

  1. Create a basic heat template ~/templates/nameserver.yaml that runs a script to append the resolv.conf file on each node with a specific nameserver. You can use the OS::TripleO::MultipartMime resource type to send the configuration script.

    heat_template_version: 2014-10-16
    
    description: >
      Extra hostname configuration
    
    resources:
      userdata:
        type: OS::Heat::MultipartMime
        properties:
          parts:
          - config: {get_resource: nameserver_config}
    
      nameserver_config:
        type: OS::Heat::SoftwareConfig
        properties:
          config: |
            #!/bin/bash
            echo "nameserver 192.168.1.1" >> /etc/resolv.conf
    
    outputs:
      OS::stack_id:
        value: {get_resource: userdata}
  2. Create an environment file ~/templates/firstboot.yaml that registers your heat template as the OS::TripleO::NodeUserData resource type.

    resource_registry:
      OS::TripleO::NodeUserData: /home/stack/templates/nameserver.yaml
  3. To add the first boot configuration to your overcloud, add the environment file to the stack, along with your other environment files:

    $ openstack overcloud deploy --templates \
        ...
        -e /home/stack/templates/firstboot.yaml \
        ...

    This adds the configuration to all nodes when they are first created and boot for the first time. Subsequent inclusion of these templates, such as updating the overcloud stack, does not run these scripts.

Important

You can only register the NodeUserData resources to one heat template per resource. Subsequent usage overrides the heat template to use.

4.2. Pre-configuration: customizing specific overcloud roles

Important

Previous versions of this document used the OS::TripleO::Tasks::*PreConfig resources to provide pre-configuration hooks on a per role basis. The heat template collection requires dedicated use of these hooks, which means that you should not use them for custom use. Instead, use the OS::TripleO::*ExtraConfigPre hooks outlined here.

The overcloud uses Puppet for the core configuration of OpenStack components. Director provides a set of hooks that you can use to perform custom configuration for specific node roles after the first boot completes and before the core configuration begins. These hooks include:

OS::TripleO::ControllerExtraConfigPre
Additional configuration applied to Controller nodes before the core Puppet configuration.
OS::TripleO::ComputeExtraConfigPre
Additional configuration applied to Compute nodes before the core Puppet configuration.
OS::TripleO::CephStorageExtraConfigPre
Additional configuration applied to Ceph Storage nodes before the core Puppet configuration.
OS::TripleO::ObjectStorageExtraConfigPre
Additional configuration applied to Object Storage nodes before the core Puppet configuration.
OS::TripleO::BlockStorageExtraConfigPre
Additional configuration applied to Block Storage nodes before the core Puppet configuration.
OS::TripleO::[ROLE]ExtraConfigPre
Additional configuration applied to custom nodes before the core Puppet configuration. Replace [ROLE] with the composable role name.

In this example, append the resolv.conf file on all nodes of a particular role with a variable nameserver:

  1. Create a basic heat template ~/templates/nameserver.yaml that runs a script to write a variable nameserver to the resolv.conf file of a node:

    heat_template_version: 2014-10-16
    
    description: >
      Extra hostname configuration
    
    parameters:
      server:
        type: string
      nameserver_ip:
        type: string
      DeployIdentifier:
        type: string
    
    resources:
      CustomExtraConfigPre:
        type: OS::Heat::SoftwareConfig
        properties:
          group: script
          config:
            str_replace:
              template: |
                #!/bin/sh
                echo "nameserver _NAMESERVER_IP_" > /etc/resolv.conf
              params:
                _NAMESERVER_IP_: {get_param: nameserver_ip}
    
      CustomExtraDeploymentPre:
        type: OS::Heat::SoftwareDeployment
        properties:
          server: {get_param: server}
          config: {get_resource: CustomExtraConfigPre}
          actions: ['CREATE','UPDATE']
          input_values:
            deploy_identifier: {get_param: DeployIdentifier}
    
    outputs:
      deploy_stdout:
        description: Deployment reference, used to trigger pre-deploy on changes
        value: {get_attr: [CustomExtraDeploymentPre, deploy_stdout]}

    In this example, the resources section contains the following parameters:

    CustomExtraConfigPre
    This defines a software configuration. In this example, we define a Bash script and heat replaces _NAMESERVER_IP_ with the value stored in the nameserver_ip parameter.
    CustomExtraDeploymentPre

    This executes a software configuration, which is the software configuration from the CustomExtraConfigPre resource. Note the following:

    • The config parameter references the CustomExtraConfigPre resource so that heat knows which configuration to apply.
    • The server parameter retrieves a map of the overcloud nodes. This parameter is provided by the parent template and is mandatory in templates for this hook.
    • The actions parameter defines when to apply the configuration. In this case, you want to apply the configuration when the overcloud is created. Possible actions include CREATE, UPDATE, DELETE, SUSPEND, and RESUME.
    • input_values contains a parameter called deploy_identifier, which stores the DeployIdentifier from the parent template. This parameter provides a timestamp to the resource for each deployment update to ensure that the resource reapplies on subsequent overcloud updates.
  2. Create an environment file ~/templates/pre_config.yaml that registers your heat template to the role-based resource type. For example, to apply the configuration only to Controller nodes, use the ControllerExtraConfigPre hook:

    resource_registry:
      OS::TripleO::ControllerExtraConfigPre: /home/stack/templates/nameserver.yaml
    
    parameter_defaults:
      nameserver_ip: 192.168.1.1
  3. Add the environment file to the stack, along with your other environment files:

    $ openstack overcloud deploy --templates \
        ...
        -e /home/stack/templates/pre_config.yaml \
        ...

    This applies the configuration to all Controller nodes before the core configuration begins on either the initial overcloud creation or subsequent updates.

Important

You can register each resource to only one heat template per hook. Subsequent usage overrides the heat template to use.

4.3. Pre-configuration: customizing all overcloud roles

The overcloud uses Puppet for the core configuration of OpenStack components. Director provides a hook that you can use to configure all node types after the first boot completes and before the core configuration begins:

OS::TripleO::NodeExtraConfig
Additional configuration applied to all nodes roles before the core Puppet configuration.

In this example, append the resolv.conf file on each node with a variable nameserver:

  1. Create a basic heat template ~/templates/nameserver.yaml that runs a script to append the resolv.conf file of each node with a variable nameserver:

    heat_template_version: 2014-10-16
    
    description: >
      Extra hostname configuration
    
    parameters:
      server:
        type: string
      nameserver_ip:
        type: string
      DeployIdentifier:
        type: string
    
    resources:
      CustomExtraConfigPre:
        type: OS::Heat::SoftwareConfig
        properties:
          group: script
          config:
            str_replace:
              template: |
                #!/bin/sh
                echo "nameserver _NAMESERVER_IP_" >> /etc/resolv.conf
              params:
                _NAMESERVER_IP_: {get_param: nameserver_ip}
    
      CustomExtraDeploymentPre:
        type: OS::Heat::SoftwareDeployment
        properties:
          server: {get_param: server}
          config: {get_resource: CustomExtraConfigPre}
          actions: ['CREATE','UPDATE']
          input_values:
            deploy_identifier: {get_param: DeployIdentifier}
    
    outputs:
      deploy_stdout:
        description: Deployment reference, used to trigger pre-deploy on changes
        value: {get_attr: [CustomExtraDeploymentPre, deploy_stdout]}

    In this example, the resources section contains the following parameters:

    CustomExtraConfigPre
    This parameter defines a software configuration. In this example, you define a Bash script and heat replaces _NAMESERVER_IP_ with the value stored in the nameserver_ip parameter.
    CustomExtraDeploymentPre

    This parameter executes a software configuration, which is the software configuration from the CustomExtraConfigPre resource. Note the following:

    • The config parameter references the CustomExtraConfigPre resource so that heat knows which configuration to apply.
    • The server parameter retrieves a map of the overcloud nodes. This parameter is provided by the parent template and is mandatory in templates for this hook.
    • The actions parameter defines when to apply the configuration. In this case, you only apply the configuration when the overcloud is created. Possible actions include CREATE, UPDATE, DELETE, SUSPEND, and RESUME.
    • The input_values parameter contains a sub-parameter called deploy_identifier, which stores the DeployIdentifier from the parent template. This parameter provides a timestamp to the resource for each deployment update to ensure that the resource reapplies on subsequent overcloud updates.
  2. Create an environment file ~/templates/pre_config.yaml that registers your heat template as the OS::TripleO::NodeExtraConfig resource type.

    resource_registry:
      OS::TripleO::NodeExtraConfig: /home/stack/templates/nameserver.yaml
    
    parameter_defaults:
      nameserver_ip: 192.168.1.1
  3. Add the environment file to the stack, along with your other environment files:

    $ openstack overcloud deploy --templates \
        ...
        -e /home/stack/templates/pre_config.yaml \
        ...

    This applies the configuration to all nodes before the core configuration begins on either the initial overcloud creation or subsequent updates.

Important

You can register the OS::TripleO::NodeExtraConfig to only one heat template. Subsequent usage overrides the heat template to use.

4.4. Post-configuration: customizing all overcloud roles

Important

Previous versions of this document used the OS::TripleO::Tasks::*PostConfig resources to provide post-configuration hooks on a per role basis. The heat template collection requires dedicated use of these hooks, which means that you should not use them for custom use. Instead, use the OS::TripleO::NodeExtraConfigPost hook outlined here.

A situation might occur where you have completed the creation of your overcloud but you want to add additional configuration to all roles, either on initial creation or on a subsequent update of the overcloud. In this case, use the following post-configuration hook:

OS::TripleO::NodeExtraConfigPost
Additional configuration applied to all nodes roles after the core Puppet configuration.

In this example, append the resolv.conf file on each node with a variable nameserver:

  1. Create a basic heat template ~/templates/nameserver.yaml that runs a script to append the resolv.conf file of each node with a variable nameserver:

    heat_template_version: 2014-10-16
    
    description: >
      Extra hostname configuration
    
    parameters:
      servers:
        type: json
      nameserver_ip:
        type: string
      DeployIdentifier:
        type: string
      EndpointMap:
        default: {}
        type: json
    
    resources:
      CustomExtraConfig:
        type: OS::Heat::SoftwareConfig
        properties:
          group: script
          config:
            str_replace:
              template: |
                #!/bin/sh
                echo "nameserver _NAMESERVER_IP_" >> /etc/resolv.conf
              params:
                _NAMESERVER_IP_: {get_param: nameserver_ip}
    
      CustomExtraDeployments:
        type: OS::Heat::SoftwareDeploymentGroup
        properties:
          servers:  {get_param: servers}
          config: {get_resource: CustomExtraConfig}
          actions: ['CREATE','UPDATE']
          input_values:
            deploy_identifier: {get_param: DeployIdentifier}

    In this example, the resources section contains the following parameters:

    CustomExtraConfig
    This defines a software configuration. In this example, you define a Bash script and heat replaces _NAMESERVER_IP_ with the value stored in the nameserver_ip parameter.
    CustomExtraDeployments

    This executes a software configuration, which is the software configuration from the CustomExtraConfig resource. Note the following:

    • The config parameter references the CustomExtraConfig resource so that heat knows which configuration to apply.
    • The servers parameter retrieves a map of the overcloud nodes. This parameter is provided by the parent template and is mandatory in templates for this hook.
    • The actions parameter defines when to apply the configuration. In this case, you want apply the configuration when the overcloud is created. Possible actions include CREATE, UPDATE, DELETE, SUSPEND, and RESUME.
    • input_values contains a parameter called deploy_identifier, which stores the DeployIdentifier from the parent template. This parameter provides a timestamp to the resource for each deployment update to ensure that the resource reapplies on subsequent overcloud updates.
  2. Create an environment file ~/templates/post_config.yaml that registers your heat template as the OS::TripleO::NodeExtraConfigPost: resource type.

    resource_registry:
      OS::TripleO::NodeExtraConfigPost: /home/stack/templates/nameserver.yaml
    
    parameter_defaults:
      nameserver_ip: 192.168.1.1
  3. Add the environment file to the stack, along with your other environment files:

    $ openstack overcloud deploy --templates \
        ...
        -e /home/stack/templates/post_config.yaml \
        ...

    This applies the configuration to all nodes after the core configuration completes on either initial overcloud creation or subsequent updates.

Important

You can register the OS::TripleO::NodeExtraConfigPost to only one heat template. Subsequent usage overrides the heat template to use.

4.5. Puppet: Customizing hieradata for roles

The heat template collection contains a set of parameters that you can use to pass extra configuration to certain node types. These parameters save the configuration as hieradata for the Puppet configuration on the node:

ControllerExtraConfig
Configuration to add to all Controller nodes.
ComputeExtraConfig
Configuration to add to all Compute nodes.
BlockStorageExtraConfig
Configuration to add to all Block Storage nodes.
ObjectStorageExtraConfig
Configuration to add to all Object Storage nodes.
CephStorageExtraConfig
Configuration to add to all Ceph Storage nodes.
[ROLE]ExtraConfig
Configuration to add to a composable role. Replace [ROLE] with the composable role name.
ExtraConfig

Configuration to add to all nodes.

  1. To add extra configuration to the post-deployment configuration process, create an environment file that contains these parameters in the parameter_defaults section. For example, to increase the reserved memory for Compute hosts to 1024 MB and set the VNC keymap to Japanese, use the following entries in the ComputeExtraConfig parameter:

    parameter_defaults:
      ComputeExtraConfig:
        nova::compute::reserved_host_memory: 1024
        nova::compute::vnc_keymap: ja
  2. Include this environment file in the openstack overcloud deploy command, along with any other environment files relevant to your deployment.
Important

You can define each parameter only once. Subsequent usage overrides previous values.

4.6. Puppet: Customizing hieradata for individual nodes

You can set Puppet hieradata for individual nodes using the heat template collection:

  1. Identify the system UUID from the introspection data for a node:

    $ openstack baremetal introspection data save 9dcc87ae-4c6d-4ede-81a5-9b20d7dc4a14 | jq .extra.system.product.uuid

    This command returns a system UUID. For example:

    "f5055c6c-477f-47fb-afe5-95c6928c407f"
  2. Create an environment file to define node-specific hieradata and register the per_node.yaml template to a pre-configuration hook. Include the system UUID of the node that you want to configure in the NodeDataLookup parameter:

    resource_registry:
      OS::TripleO::ComputeExtraConfigPre: /usr/share/openstack-tripleo-heat-templates/puppet/extraconfig/pre_deploy/per_node.yaml
    parameter_defaults:
      NodeDataLookup: '{"f5055c6c-477f-47fb-afe5-95c6928c407f": {"nova::compute::vcpu_pin_set": [ "2", "3" ]}}'
  3. Include this environment file in the openstack overcloud deploy command, along with any other environment files relevant to your deployment.

The per_node.yaml template generates a set of hieradata files on nodes that correspond to each system UUID and contains the hieradata that you define. If a UUID is not defined, the resulting hieradata file is empty. In this example, the per_node.yaml template runs on all Compute nodes as defined by the OS::TripleO::ComputeExtraConfigPre hook, but only the Compute node with system UUID f5055c6c-477f-47fb-afe5-95c6928c407f receives hieradata.

You can use this mechanism to tailor each node according to specific requirements.

For more information about NodeDataLookup, see Altering the disk layout in Ceph Storage nodes in the Deploying an overcloud with containerized Red Hat Ceph guide.

4.7. Puppet: Applying custom manifests

In certain circumstances, you might want to install and configure some additional components on your overcloud nodes. You can achieve this with a custom Puppet manifest that applies to nodes after the main configuration completes. As a basic example, you might want to install motd on each node

  1. Create a heat template ~/templates/custom_puppet_config.yaml that launches Puppet configuration.

    heat_template_version: 2014-10-16
    
    description: >
      Run Puppet extra configuration to set new MOTD
    
    parameters:
      servers:
        type: json
    
    resources:
      ExtraPuppetConfig:
        type: OS::Heat::SoftwareConfig
        properties:
          config: {get_file: motd.pp}
          group: puppet
          options:
            enable_hiera: True
            enable_facter: False
    
      ExtraPuppetDeployments:
        type: OS::Heat::SoftwareDeploymentGroup
        properties:
          config: {get_resource: ExtraPuppetConfig}
          servers: {get_param: servers}

    This example includes the /home/stack/templates/motd.pp within the template and passes it to nodes for configuration. The motd.pp file contains the Puppet classes necessary to install and configure motd.

  2. Create an environment file ~templates/puppet_post_config.yaml that registers your heat template as the OS::TripleO::NodeExtraConfigPost: resource type.

    resource_registry:
      OS::TripleO::NodeExtraConfigPost: /home/stack/templates/custom_puppet_config.yaml
  3. Include this environment file in the openstack overcloud deploy command, along with any other environment files relevant to your deployment.

    $ openstack overcloud deploy --templates \
        ...
        -e /home/stack/templates/puppet_post_config.yaml \
        ...

    This applies the configuration from motd.pp to all nodes in the overcloud.