Menu Close
Settings Close

Language and Page Formatting Options

Chapter 6. Composable services

Red Hat OpenStack Platform (RHOSP) includes the ability to define custom roles and compose service combinations on roles. For more information, see Composable Services and Custom Roles in the Advanced Overcloud Customization guide. As part of the integration, you can define your own custom services and include them on chosen roles.

6.1. Examining composable service architecture

The core heat template collection contains two sets of composable service templates:

  • deployment contains the templates for key OpenStack services.
  • puppet/services contains legacy templates for configuring composable services. In some cases, the composable services use templates from this directory for compatibility. In most cases, the composable services use the templates in the deployment directory.

Each template contains a description that identifies its purpose. For example, the deployment/time/ntp-baremetal-puppet.yaml service template contains the following description:

description: >
  NTP service deployment using puppet, this YAML file
  creates the interface between the HOT template
  and the puppet manifest that actually installs
  and configure NTP.

These service templates are registered as resources specific to a Red Hat OpenStack Platform deployment. This means that you can call each resource using a unique heat resource namespace defined in the overcloud-resource-registry-puppet.j2.yaml file. All services use the OS::TripleO::Services namespace for their resource type.

Some resources use the base composable service templates directly:

resource_registry:
  ...
  OS::TripleO::Services::Ntp: deployment/time/ntp-baremetal-puppet.yaml
  ...

However, core services require containers and use the containerized service templates. For example, the keystone containerized service uses the following resource:

resource_registry:
  ...
  OS::TripleO::Services::Keystone: deployment/keystone/keystone-container-puppet.yaml
  ...

These containerized templates usually reference other templates to include dependencies. For example, the deployment/keystone/keystone-container-puppet.yaml template stores the output of the base template in the ContainersCommon resource:

resources:
  ContainersCommon:
    type: ../containers-common.yaml

The containerized template can then incorporate functions and data from the containers-common.yaml template.

The overcloud.j2.yaml heat template includes a section of Jinja2-based code to define a service list for each custom role in the roles_data.yaml file:

{{role.name}}Services:
  description: A list of service resources (configured in the heat
               resource_registry) which represent nested stacks
               for each service that should get installed on the {{role.name}} role.
  type: comma_delimited_list
  default: {{role.ServicesDefault|default([])}}

For the default roles, this creates the following service list parameters: ControllerServices, ComputeServices, BlockStorageServices, ObjectStorageServices, and CephStorageServices.

You define the default services for each custom role in the roles_data.yaml file. For example, the default Controller role contains the following content:

- name: Controller
  CountDefault: 1
  ServicesDefault:
    - OS::TripleO::Services::CACerts
    - OS::TripleO::Services::CephMon
    - OS::TripleO::Services::CephExternal
    - OS::TripleO::Services::CephRgw
    - OS::TripleO::Services::CinderApi
    - OS::TripleO::Services::CinderBackup
    - OS::TripleO::Services::CinderScheduler
    - OS::TripleO::Services::CinderVolume
    - OS::TripleO::Services::Core
    - OS::TripleO::Services::Kernel
    - OS::TripleO::Services::Keystone
    - OS::TripleO::Services::GlanceApi
    - OS::TripleO::Services::GlanceRegistry
...

These services are then defined as the default list for the ControllerServices parameter.

Note

You can also use an environment file to override the default list for the service parameters. For example, you can define ControllerServices as a parameter_default in an environment file to override the services list from the roles_data.yaml file.

6.2. Creating a user-defined composable service

This example examines how to create a user-defined composable service and focuses on implementing a message of the day (motd) service. In this example, the overcloud image contains a custom motd Puppet module loaded either through a configuration hook or through modifying the overcloud images.

Procedure

When you create your own service, you must define the following items in the heat template of your service:

parameters
  • ServiceData - A map of service specific data. Use an empty hash ({}) as the default value because values from the heat template override this parameter.
  • ServiceNetMap - A map of services to networks. Use an empty hash ({}) as the default value because values from the heat template override this parameter.
  • EndpointMap - A list of OpenStack service endpoints to protocols. Use an empty hash ({}) as the default value because values from the heat template override this parameter
  • DefaultPasswords - A list of default passwords. Use an empty hash ({}) as the default value because values from the heat template override this parameter.
  • RoleName - Name of the role that this service is deployed. Use an empty string ('') as the default value because values from the heat template override this parameter.
  • RoleParameters - Parameters specific to a role. These parameters are defined with the <RoleName>Parameters parameter, replace <RoleName> with the name of the role. Use an empty hash ({}) as the default value because values from the heat template override this parameter

Define any additional parameters that your service requires.

outputs
The following output parameters define the service configuration on the host. For more information, see Section 6.4, “Composable service parameters”.

The following is an example heat template (service.yaml) for the motd service:

heat_template_version: 2016-04-08

description: >
  Message of the day service configured with Puppet

parameters:
  ServiceNetMap:
    default: {}
    type: json
  DefaultPasswords:
    default: {}
    type: json
  EndpointMap:
    default: {}
    type: json
  MotdMessage: 1
    default: |
      Welcome to my Red Hat OpenStack Platform environment!

    type: string
    description: The message to include in the motd

outputs:
  role_data:
    description: Motd role using composable services.
    value:
      service_name: motd
      config_settings: 2
        motd::content: {get_param: MotdMessage}
      step_config: | 3
        if hiera('step') >= 2 {
          include ::motd
        }
1
The template includes a MotdMessage parameter that defines the message of the day. The parameter includes a default message but you can override it by using the same parameter in a custom environment file.
2
The outputs section defines some service hieradata in config_settings. The motd::content hieradata stores the content from the MotdMessage parameter. The motd Puppet class eventually reads this hieradata and passes the user-defined message to the /etc/motd file.
3
The outputs section includes a Puppet manifest snippet in step_config. The snippet checks if the configuration has reached step 2 and, if so, runs the motd Puppet class.

6.3. Including a user-defined composable services

You can configure the custom motd service only on the overcloud Controller nodes. This requires a custom environment file and custom roles data file included with your deployment. Replace example input in this procedure according to your requirements.

Procedure

  1. Add the new service to an environment file, env-motd.yaml, as a registered heat resource within the OS::TripleO::Services namespace. In this example, the resource name for our motd service is OS::TripleO::Services::Motd:

    resource_registry:
      OS::TripleO::Services::Motd: /home/stack/templates/motd.yaml
    
    parameter_defaults:
      MotdMessage: |
        You have successfully accessed my Red Hat OpenStack Platform environment!

    This custom environment file also includes a new message that overrides the default for MotdMessage.

    The deployment now includes the motd service. However, each role that requires this new service must have an updated ServicesDefault listing in a custom roles_data.yaml file.

  2. Create a copy of the default roles_data.yaml file:

    $ cp /usr/share/openstack-tripleo-heat-templates/roles_data.yaml ~/custom_roles_data.yaml
  3. To edit this file, scroll to the Controller role and include the service in the ServicesDefault listing:

    - name: Controller
      CountDefault: 1
      ServicesDefault:
        - OS::TripleO::Services::CACerts
        - OS::TripleO::Services::CephMon
        - OS::TripleO::Services::CephExternal
    ...
        - OS::TripleO::Services::FluentdClient
        - OS::TripleO::Services::VipHosts
        - OS::TripleO::Services::Motd           # Add the service to the end
  4. When you create an overcloud, include the resulting environment file and the custom_roles_data.yaml file with your other environment files and deployment options:

    $ openstack overcloud deploy --templates -e /home/stack/templates/env-motd.yaml -r ~/custom_roles_data.yaml [OTHER OPTIONS]

6.4. Composable service parameters

The following parameters are used for the outputs in all composable services:

service_name

The name of your service. You can use this to apply configuration from other composable services with service_config_settings.

config_settings

Custom hieradata settings for your service.

kolla_config

Creates a map of the kolla configuration in the container. The format begins with the absolute path of the configuration file as a key and then uses the following sub-parameters as the value of the key:

command
The command to run when the container starts.
config_files
The location of the service configuration files (source) and the destination on the container (dest) before the service starts. Also includes options to either merge or replace these files on the container (merge), whether to preserve the file permissions and other properties (preserve_properties).
permissions
Set permissions for certain directories on the containers. Requires a path and an owner (which is a user:group combination). You can also apply the permissions recursively (recurse).

The following is an example of the kolla_config parameter for the keystone service:

kolla_config:
  /var/lib/kolla/config_files/keystone.json:
    command: /usr/sbin/httpd -DFOREGROUND
    config_files:
      - source: "/var/lib/kolla/config_files/src/*"
        dest: "/"
        merge: true
        preserve_properties: true
  /var/lib/kolla/config_files/keystone_cron.json:
    command: /usr/sbin/crond -n
    config_files:
      - source: "/var/lib/kolla/config_files/src/*"
        dest: "/"
        merge: true
        preserve_properties: true
    permissions:
      - path: /var/log/keystone
        owner: keystone:keystone
        recurse: true

docker_config

Data passed to the paunch command to configure containers at each step.

  • step_0 - Containers configuration files generated per hiera settings.
  • step_1 - Load Balancer configuration

    1. Baremetal configuration
    2. Container configuration
  • step_2 - Core Services (Database/Rabbit/NTP/etc.)

    1. Baremetal configuration
    2. Container configuration
  • step_3 - Early OpenStack Service setup (Ringbuilder, etc.)

    1. Baremetal configuration
    2. Container configuration
  • step_4 - General OpenStack Services

    1. Baremetal configuration
    2. Container configuration
    3. Keystone container post initialization (tenant, service, endpoint creation)
  • step_5 - Service activation (Pacemaker)

    1. Baremetal configuration
    2. Container configuration

The YAML file uses a set of parameters to define the container to run at each step and the podman settings associated with each container. For example:

docker_config:
  step_3:
    keystone:
      start_order: 2
      image: *keystone_image
      net: host
      privileged: false
      restart: always
      healthcheck:
        test: /openstack/healthcheck
      volumes: *keystone_volumes
      environment:
        - KOLLA_CONFIG_STRATEGY=COPY_ALWAYS

This creates a keystone container and uses the respective parameters to define details, including the image to use, the networking type, and environment variables.

puppet_config

This section is a nested set of key value pairs that drive the creation of configuration files using Puppet. The following required parameters are included:

puppet_tags
Puppet resource tag names that are used to generate configuration files with Puppet. Only the named configuration resources are used to generate a file. Any service that specifies tags has the default tags of file,concat,file_line,augeas,cron appended to the setting. Example: keystone_config
config_volume
The name of the volume (directory) where the configuration files are generated for this service. Use this as the location to bind mount into the running Kolla container for configuration.
config_image
The name of the container image that will be used for generating configuration files. This is often the same container that the runtime service uses. Some services share a common set of configuration files which are generated in a common base container.
step_config
This setting controls the manifest that is used to create configuration files with Puppet. Use the following Puppet tags together with the manifest to generate a configuration directory for this container.

container_puppet_tasks

Provides data to drive the container-puppet.py tool directly. The task is executed once within the cluster, not on each node, and is useful for several Puppet snippets required for initialization of things like keystone endpoints and database users. For example:

container_puppet_tasks:
  # Keystone endpoint creation occurs only on single node
  step_3:
    config_volume: 'keystone_init_tasks'
    puppet_tags: 'keystone_config,keystone_domain_config,keystone_endpoint,keystone_identity_provider,keystone_paste_ini,keystone_role,keystone_service,keystone_tenant,keystone_user,keystone_user_role,keystone_domain'
    step_config: 'include ::tripleo::profile::base::keystone'
    config_image: *keystone_config_image

global_config_settings

Custom hieradata settings distributed to all roles.

service_config_settings

Custom hieradata settings for another service. For example, your service might require that its endpoints are registered in OpenStack Identity (keystone). This provides parameters from one service to another and provides a method of cross-service configuration, even if the services are on different roles.

step_config

This is a Puppet snippet to configure the service. This snippet is added to a combined manifest created and run at each step of the service configuration process:

  • Step 1 - Load balancer configuration
  • Step 2 - Core high availability and general services (Database, RabbitMQ, NTP)
  • Step 3 - Early OpenStack Platform Service setup (Storage, Ring Building)
  • Step 4 - General OpenStack Platform services
  • Step 5 - Service activation (Pacemaker) and OpenStack Identity (keystone) role and user creation

In any referenced puppet manifest, you can use the step hieradata (using hiera('step')) to define specific actions at specific steps during the deployment process.

host_prep_tasks

This is an ansible snippet to execute on the node host to prepare it for containerized services. For example, you might need to create a specific directory to mount to the container during its creation.

external_deploy_tasks

Execute Ansible tasks on the undercloud and run at each step in the deployment process.

upgrade_tasks

This is an ansible snippet to help with upgrading the service. The snippet is added to a combined playbook. Each operation uses a tag to define a step, which includes the following items:

  • common - Applies to all steps
  • step0 - Validation
  • step1 - Stop all OpenStack services.
  • step2 - Stop all Pacemaker-controlled services
  • step3 - Package update and new package installation
  • step4 - Start OpenStack service required for database upgrade
  • step5 - Upgrade database

upgrade_batch_tasks

Performs a similar function to upgrade_tasks but only executes a batch set of Ansible tasks in the order they are listed. The default is 1, but you can change this per role by using the upgrade_batch_size parameter in a roles_data.yaml file.

post_upgrade_tasks

Executes Ansible tasks after the completion of the upgrade process.

external_upgrade_tasks

Execute Ansible tasks on the undercloud and run at each step in the upgrade process.

update_tasks

Ansible snippet to help with minor version updates for a service. The snippet is added to a combined playbook. Each operation uses a tag to define a step, which includes the following items:

  • common - Applies to all steps
  • step0 - Validation
  • step1 - Stop all OpenStack services.
  • step2 - Stop all Pacemaker-controlled services
  • step3 - Package update and new package installation
  • step4 - Start OpenStack service required for database upgrade
  • step5 - Upgrade database

post_update_tasks

Executes Ansible tasks after the completion of the update process.

external_update_tasks

Execute Ansible tasks on the undercloud and run at each step in the minor version update process.