Chapter 4. Installing director

4.1. Configuring the director

The director installation process requires certain settings in the undercloud.conf configuration file, which the director reads from the stack user’s home directory. This procedure demonstrates how to use the default template as a foundation for your configuration.

Procedure

  1. Copy the default template to the stack user’s home directory:

    [stack@director ~]$ cp \
      /usr/share/python-tripleoclient/undercloud.conf.sample \
      ~/undercloud.conf
  2. Edit the undercloud.conf file. This file contains settings to configure your undercloud. If you omit or comment out a parameter, the undercloud installation uses the default value.

4.2. Director configuration parameters

The following list contains information about parameters for configuring the undercloud.conf file. Keep all parameters within their relevant sections to avoid errors.

Defaults

The following parameters are defined in the [DEFAULT] section of the undercloud.conf file:

additional_architectures

A list of additional (kernel) architectures that an overcloud supports. Currently the overcloud supports ppc64le architecture.

Note

When enabling support for ppc64le, you must also set ipxe_enabled to False

certificate_generation_ca
The certmonger nickname of the CA that signs the requested certificate. Use this option only if you have set the generate_service_certificate parameter. If you select the local CA, certmonger extracts the local CA certificate to /etc/pki/ca-trust/source/anchors/cm-local-ca.pem and adds the certificate to the trust chain.
clean_nodes
Defines whether to wipe the hard drive between deployments and after introspection.
cleanup
Cleanup temporary files. Set this to False to leave the temporary files used during deployment in place after the command is run. This is useful for debugging the generated files or if errors occur.
container_cli
The CLI tool for container management. Leave this parameter set to podman since Red Hat Enterprise Linux 8 only supports podman.
container_healthcheck_disabled
Disables containerized service health checks. It is recommended to keep health checks enabled and leave this option set to false.
container_images_file

Heat environment file with container image information. This can either be:

  • Parameters for all required container images
  • Or the ContainerImagePrepare parameter to drive the required image preparation. Usually the file containing this parameter is named containers-prepare-parameter.yaml.
container_insecure_registries
A list of insecure registries for podman to use. Use this parameter if you want to pull images from another source, such as a private container registry. In most cases, podman has the certificates to pull container images from either the Red Hat Container Catalog or from your Satellite server if the undercloud is registered to Satellite.
container_registry_mirror
An optional registry-mirror configured that podman uses.
custom_env_files
Additional environment file to add to the undercloud installation.
deployment_user
The user installing the undercloud. Leave this parameter unset to use the current default user (stack).
discovery_default_driver
Sets the default driver for automatically enrolled nodes. Requires enable_node_discovery enabled and you must include the driver in the enabled_hardware_types list.
enable_ironic; enable_ironic_inspector; enable_mistral; enable_tempest; enable_validations; enable_zaqar
Defines the core services to enable for director. Leave these parameters set to true.
enable_node_discovery
Automatically enroll any unknown node that PXE-boots the introspection ramdisk. New nodes use the fake_pxe driver as a default but you can set discovery_default_driver to override. You can also use introspection rules to specify driver information for newly enrolled nodes.
enable_novajoin
Defines whether to install the novajoin metadata service in the Undercloud.
enable_routed_networks
Defines whether to enable support for routed control plane networks.
enable_swift_encryption
Defines whether to enable Swift encryption at-rest.
enable_telemetry
Defines whether to install OpenStack Telemetry services (gnocchi, aodh, panko) in the undercloud. Set enable_telemetry parameter to true if you want to install and configure telemetry services automatically. The default value is false, which disables telemetry on the undercloud. This parameter is required if using other products that consume metrics data, such as Red Hat CloudForms.
enabled_hardware_types
A list of hardware types to enable for the undercloud.
generate_service_certificate
Defines whether to generate an SSL/TLS certificate during the undercloud installation, which is used for the undercloud_service_certificate parameter. The undercloud installation saves the resulting certificate /etc/pki/tls/certs/undercloud-[undercloud_public_vip].pem. The CA defined in the certificate_generation_ca parameter signs this certificate.
heat_container_image
URL for the heat container image to use. Leave unset.
heat_native
Use native heat templates. Leave as true.
hieradata_override
Path to hieradata override file. If set, the undercloud installation copies this file to the /etc/puppet/hieradata directory and sets it as the first file in the hierarchy. Use this parameter to provide custom configuration to services beyond the undercloud.conf parameters.
inspection_extras
Defines whether to enable extra hardware collection during the inspection process. This parameter requires python-hardware or python-hardware-detect package on the introspection image.
inspection_interface
The bridge the director uses for node introspection. This is a custom bridge that the director configuration creates. The LOCAL_INTERFACE attaches to this bridge. Leave this as the default br-ctlplane.
inspection_runbench
Runs a set of benchmarks during node introspection. Set this parameter to true to enable the benchmarks. This option is necessary if you intend to perform benchmark analysis when inspecting the hardware of registered nodes.
ipa_otp
Defines the one time password to register the Undercloud node to an IPA server. This is required when enable_novajoin is enabled.
ipxe_enabled
Defines whether to use iPXE or standard PXE. The default is true, which enables iPXE. Set to false to set to standard PXE.
local_interface

The chosen interface for the director’s Provisioning NIC. This is also the device the director uses for DHCP and PXE boot services. Change this value to your chosen device. To see which device is connected, use the ip addr command. For example, this is the result of an ip addr command:

2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
    link/ether 52:54:00:75:24:09 brd ff:ff:ff:ff:ff:ff
    inet 192.168.122.178/24 brd 192.168.122.255 scope global dynamic eth0
       valid_lft 3462sec preferred_lft 3462sec
    inet6 fe80::5054:ff:fe75:2409/64 scope link
       valid_lft forever preferred_lft forever
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noop state DOWN
    link/ether 42:0b:c2:a5:c1:26 brd ff:ff:ff:ff:ff:ff

In this example, the External NIC uses eth0 and the Provisioning NIC uses eth1, which is currently not configured. In this case, set the local_interface to eth1. The configuration script attaches this interface to a custom bridge defined with the inspection_interface parameter.

local_ip
The IP address defined for the director’s Provisioning NIC. This is also the IP address that the director uses for DHCP and PXE boot services. Leave this value as the default 192.168.24.1/24 unless you use a different subnet for the Provisioning network, for example, if it conflicts with an existing IP address or subnet in your environment.
local_mtu
MTU to use for the local_interface.
local_subnet
The local subnet to use for PXE boot and DHCP interfaces. The local_ip address should reside in this subnet. The default is ctlplane-subnet.
net_config_override
Path to network configuration override template. If you set this parameter, the undercloud uses a JSON format template to configure the networking with os-net-config. The undercloud ignores the network parameters set in undercloud.conf. See /usr/share/python-tripleoclient/undercloud.conf.sample for an example.
networks_file
Networks file to override for heat.
output_dir
Directory to output state, processed heat templates, and Ansible deployment files.
overcloud_domain_name

The DNS domain name to use when deploying the overcloud.

Note

When configuring the overcloud, the CloudDomain parameter must be set to a matching value. Set this parameter in an environment file when you configure your overcloud.

roles_file
The roles file to override for undercloud installation. It is highly recommended to leave unset so that the director installation uses the default roles file.
scheduler_max_attempts
Maximum number of times the scheduler attempts to deploy an instance. This value must be greater or equal to the number of bare metal nodes that you expect to deploy at once to work around potential race condition when scheduling.
service_principal
The Kerberos principal for the service using the certificate. Use this parameter only if your CA requires a Kerberos principal, such as in FreeIPA.
subnets
List of routed network subnets for provisioning and introspection. See Subnets for more information. The default value includes only the ctlplane-subnet subnet.
templates
Heat templates file to override.
undercloud_admin_host
The IP address or hostname defined for director Admin API endpoints over SSL/TLS. The director configuration attaches the IP address to the director software bridge as a routed IP address, which uses the /32 netmask.
undercloud_debug
Sets the log level of undercloud services to DEBUG. Set this value to true to enable.
undercloud_enable_selinux
Enable or disable SELinux during the deployment. It is highly recommended to leave this value set to true unless you are debugging an issue.
undercloud_hostname
Defines the fully qualified host name for the undercloud. If set, the undercloud installation configures all system host name settings. If left unset, the undercloud uses the current host name, but the user must configure all system host name settings appropriately.
undercloud_log_file
The path to a log file to store the undercloud install/upgrade logs. By default, the log file is install-undercloud.log within the home directory. For example, /home/stack/install-undercloud.log.
undercloud_nameservers
A list of DNS nameservers to use for the undercloud hostname resolution.
undercloud_ntp_servers
A list of network time protocol servers to help synchronize the undercloud date and time.
undercloud_public_host
The IP address or hostname defined for director Public API endpoints over SSL/TLS. The director configuration attaches the IP address to the director software bridge as a routed IP address, which uses the /32 netmask.
undercloud_service_certificate
The location and filename of the certificate for OpenStack SSL/TLS communication. Ideally, you obtain this certificate from a trusted certificate authority. Otherwise, generate your own self-signed certificate.
undercloud_timezone
Host timezone for the undercloud. If you specify no timezone, director uses the existing timezone configuration.
undercloud_update_packages
Defines whether to update packages during the undercloud installation.

Subnets

Each provisioning subnet is a named section in the undercloud.conf file. For example, to create a subnet called ctlplane-subnet, use the following sample in your undercloud.conf file:

[ctlplane-subnet]
cidr = 192.168.24.0/24
dhcp_start = 192.168.24.5
dhcp_end = 192.168.24.24
inspection_iprange = 192.168.24.100,192.168.24.120
gateway = 192.168.24.1
masquerade = true

You can specify as many provisioning networks as necessary to suit your environment.

gateway
The gateway for the overcloud instances. This is the undercloud host, which forwards traffic to the External network. Leave this as the default 192.168.24.1 unless you use a different IP address for the director or want to use an external gateway directly.
Note

The director configuration also enables IP forwarding automatically using the relevant sysctl kernel parameter.

cidr
The network that the director uses to manage overcloud instances. This is the Provisioning network, which the undercloud neutron service manages. Leave this as the default 192.168.24.0/24 unless you use a different subnet for the Provisioning network.
masquerade
Defines whether to masquerade the network defined in the cidr for external access. This provides the Provisioning network with a degree of network address translation (NAT) so that the Provisioning network has external access through the director.
dhcp_start; dhcp_end
The start and end of the DHCP allocation range for overcloud nodes. Ensure this range contains enough IP addresses to allocate your nodes.
dhcp_exclude
IP addresses to exclude in the DHCP allocation range.
host_routes
Host routes for the Neutron-managed subnet for the Overcloud instances on this network. This also configures the host routes for the local_subnet on the undercloud.

Modify the values of these parameters to suit your configuration. When complete, save the file.

4.3. Configuring the undercloud with environment files

You configure the main parameters for the undercloud through the undercloud.conf file. You can also configure Heat parameters specific to the undercloud installation. You accomplish this with an environment file containing your Heat parameters.

Procedure

  1. Create an environment file at /home/stack/templates/custom-undercloud-params.yaml.
  2. Edit this file and include your Heat parameters. The following example shows how to enable debugging for certain OpenStack Platform services:

    parameter_defaults:
      Debug: True

    Save this file when you have finished.

  3. Edit your undercloud.conf file and scroll to the custom_env_files parameter. Edit the parameter to point to your environment file:

    custom_env_files = /home/stack/templates/custom-undercloud-params.yaml
    Note

    You can specify multiple environment files using a comma-separated list.

The director installation includes this environment file during the next undercloud installation or upgrade operation.

4.4. Common Heat parameters for undercloud configuration

The following table shows some common Heat parameters you might set in a custom environment file for your undercloud.

ParameterDescription

AdminPassword

Sets the undercloud admin user password.

AdminEmail

Sets the undercloud admin user email address.

Debug

Enables debug mode.

Set these parameters in your custom environment file under the parameter_defaults section:

parameter_defaults:
  Debug: True
  AdminPassword: "myp@ssw0rd!"
  AdminEmail: "admin@example.com"

4.5. Installing the director

Complete the following procedure to install the director and perform some basic post-installation tasks.

Procedure

  1. Run the following command to install the director on the undercloud:

    [stack@director ~]$ openstack undercloud install

    This launches the director’s configuration script. The director installs additional packages and configures its services according to the configuration in the undercloud.conf. This script takes several minutes to complete.

    The script generates two files when complete:

    • undercloud-passwords.conf - A list of all passwords for the director’s services.
    • stackrc - A set of initialization variables to help you access the director’s command line tools.
  2. The script also starts all OpenStack Platform service containers automatically. Check the enabled containers using the following command:

    [stack@director ~]$ sudo podman ps
  3. To initialize the stack user to use the command line tools, run the following command:

    [stack@director ~]$ source ~/stackrc

    The prompt now indicates OpenStack commands authenticate and execute against the undercloud;

    (undercloud) [stack@director ~]$

The director installation is complete. You can now use the director’s command line tools.

4.6. Obtaining images for overcloud nodes

The director requires several disk images for provisioning overcloud nodes. This includes:

  • An introspection kernel and ramdisk - Used for bare metal system introspection over PXE boot.
  • A deployment kernel and ramdisk - Used for system provisioning and deployment.
  • An overcloud kernel, ramdisk, and full image - A base overcloud system that is written to the node’s hard disk.

The following procedure shows how to obtain and install these images.

4.6.1. Single CPU architecture overclouds

These images and procedures are necessary for deployment of the overcloud with the default CPU architecture, x86-64.

Procedure

  1. Source the stackrc file to enable the director’s command line tools:

    [stack@director ~]$ source ~/stackrc
  2. Install the rhosp-director-images and rhosp-director-images-ipa packages:

    (undercloud) [stack@director ~]$ sudo yum install rhosp-director-images rhosp-director-images-ipa
  3. Extract the images archives to the images directory in the stack user’s home (/home/stack/images):

    (undercloud) [stack@director ~]$ cd ~/images
    (undercloud) [stack@director images]$ for i in /usr/share/rhosp-director-images/overcloud-full-latest-15.0.tar /usr/share/rhosp-director-images/ironic-python-agent-latest-15.0.tar; do tar -xvf $i; done
  4. Import these images into the director:

    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path /home/stack/images/

    This script uploads the following images into the director:

    • bm-deploy-kernel
    • bm-deploy-ramdisk
    • overcloud-full
    • overcloud-full-initrd
    • overcloud-full-vmlinuz

    The script also installs the introspection images on the director’s PXE server.

  5. To check these images have uploaded successfully, run:

    (undercloud) [stack@director images]$ openstack image list
    +--------------------------------------+------------------------+
    | ID                                   | Name                   |
    +--------------------------------------+------------------------+
    | 765a46af-4417-4592-91e5-a300ead3faf6 | bm-deploy-ramdisk      |
    | 09b40e3d-0382-4925-a356-3a4b4f36b514 | bm-deploy-kernel       |
    | ef793cd0-e65c-456a-a675-63cd57610bd5 | overcloud-full         |
    | 9a51a6cb-4670-40de-b64b-b70f4dd44152 | overcloud-full-initrd  |
    | 4f7e33f4-d617-47c1-b36f-cbe90f132e5d | overcloud-full-vmlinuz |
    +--------------------------------------+------------------------+

    This list does not show the introspection PXE images. The director copies these files to /var/lib/ironic/httpboot.

    (undercloud) [stack@director images]$ ls -l /var/lib/ironic/httpboot
    total 417296
    -rwxr-xr-x. 1 root  root    6639920 Jan 29 14:48 agent.kernel
    -rw-r--r--. 1 root  root  420656424 Jan 29 14:48 agent.ramdisk
    -rw-r--r--. 1 42422 42422       758 Jan 29 14:29 boot.ipxe
    -rw-r--r--. 1 42422 42422       488 Jan 29 14:16 inspector.ipxe

4.6.2. Multiple CPU architecture overclouds

These are the images and procedures needed for deployment of the overcloud to enable support of additional CPU architectures.

The procedure that follows uses the ppc64le image in its examples.

Procedure

  1. Source the stackrc file to enable the director’s command line tools:

    [stack@director ~]$ source ~/stackrc
  2. Install the rhosp-director-images-all package:

    (undercloud) [stack@director ~]$ sudo yum install rhosp-director-images-all
  3. Extract the archives to an architecture specific directory under the images directory on the stack user’s home (/home/stack/images):

    (undercloud) [stack@director ~]$ cd ~/images
    (undercloud) [stack@director images]$ for arch in x86_64 ppc64le ; do mkdir $arch ; done
    (undercloud) [stack@director images]$ for arch in x86_64 ppc64le ; do for i in /usr/share/rhosp-director-images/overcloud-full-latest-15.0-${arch}.tar /usr/share/rhosp-director-images/ironic-python-agent-latest-15.0-${arch}.tar ; do tar -C $arch -xf $i ; done ; done
  4. Import these images into the director:

    (undercloud) [stack@director ~]$ cd ~/images
    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path ~/images/ppc64le --architecture ppc64le --whole-disk --http-boot /tftpboot/ppc64le
    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path ~/images/x86_64/ --http-boot /tftpboot

    This uploads the following images into the director:

    • bm-deploy-kernel
    • bm-deploy-ramdisk
    • overcloud-full
    • overcloud-full-initrd
    • overcloud-full-vmlinuz
    • ppc64le-bm-deploy-kernel
    • ppc64le-bm-deploy-ramdisk
    • ppc64le-overcloud-full

      The script also installs the introspection images on the director’s PXE server.

  5. To check these images have uploaded successfully, run:

    (undercloud) [stack@director images]$ openstack image list
    +--------------------------------------+---------------------------+--------+
    | ID                                   | Name                      | Status |
    +--------------------------------------+---------------------------+--------+
    | 6d1005ba-ec82-473b-8e33-88aadb5b6792 | bm-deploy-kernel          | active |
    | fb723b33-9f11-45f5-b25b-c008bf509290 | bm-deploy-ramdisk         | active |
    | 6a6096ba-8f79-4343-b77c-4349f7b94960 | overcloud-full            | active |
    | de2a1bde-9351-40d2-bbd7-7ce9d6eb50d8 | overcloud-full-initrd     | active |
    | 67073533-dd2a-4a95-8e8b-0f108f031092 | overcloud-full-vmlinuz    | active |
    | 69a9ffe5-06dc-4d81-a122-e5d56ed46c98 | ppc64le-bm-deploy-kernel  | active |
    | 464dd809-f130-4055-9a39-cf6b63c1944e | ppc64le-bm-deploy-ramdisk | active |
    | f0fedcd0-3f28-4b44-9c88-619419007a03 | ppc64le-overcloud-full    | active |
    +--------------------------------------+---------------------------+--------+

    This list does not show the introspection PXE images. The director copies these files to /tftpboot.

    (undercloud) [stack@director images]$ ls -l /tftpboot /tftpboot/ppc64le/
    /tftpboot:
    total 422624
    -rwxr-xr-x. 1 root   root     6385968 Aug  8 19:35 agent.kernel
    -rw-r--r--. 1 root   root   425530268 Aug  8 19:35 agent.ramdisk
    -rwxr--r--. 1 ironic ironic     20832 Aug  8 02:08 chain.c32
    -rwxr--r--. 1 ironic ironic    715584 Aug  8 02:06 ipxe.efi
    -rw-r--r--. 1 root   root          22 Aug  8 02:06 map-file
    drwxr-xr-x. 2 ironic ironic        62 Aug  8 19:34 ppc64le
    -rwxr--r--. 1 ironic ironic     26826 Aug  8 02:08 pxelinux.0
    drwxr-xr-x. 2 ironic ironic        21 Aug  8 02:06 pxelinux.cfg
    -rwxr--r--. 1 ironic ironic     69631 Aug  8 02:06 undionly.kpxe
    
    /tftpboot/ppc64le/:
    total 457204
    -rwxr-xr-x. 1 root             root              19858896 Aug  8 19:34 agent.kernel
    -rw-r--r--. 1 root             root             448311235 Aug  8 19:34 agent.ramdisk
    -rw-r--r--. 1 ironic-inspector ironic-inspector       336 Aug  8 02:06 default
Note

The default overcloud-full.qcow2 image is a flat partition image. However, you can also import and use whole disk images. See Chapter 20, Creating whole disk images for more information.

4.7. Setting a nameserver for the control plane

If you intend for the overcloud to resolve external hostnames, such as cdn.redhat.com, it is recommended to set a nameserver on the overcloud nodes. For a standard overcloud without network isolation, the nameserver is defined using the undercloud’s control plane subnet. Complete the following procedure to define nameservers for the environment.

Procedure

  1. Source the stackrc file to enable the director’s command line tools:

    [stack@director ~]$ source ~/stackrc
  2. Set the nameservers for the ctlplane-subnet subnet:

    (undercloud) [stack@director images]$ openstack subnet set --dns-nameserver [nameserver1-ip] --dns-nameserver [nameserver2-ip] ctlplane-subnet

    Use the --dns-nameserver option for each nameserver.

  3. View the subnet to verify the nameserver:

    (undercloud) [stack@director images]$ openstack subnet show ctlplane-subnet
    +-------------------+-----------------------------------------------+
    | Field             | Value                                         |
    +-------------------+-----------------------------------------------+
    | ...               |                                               |
    | dns_nameservers   | 8.8.8.8                                       |
    | ...               |                                               |
    +-------------------+-----------------------------------------------+
Important

If you aim to isolate service traffic onto separate networks, the overcloud nodes use the DnsServers parameter in your network environment files.

4.8. Updating the undercloud configuration

In the future, you might have to change the undercloud configuration to suit new requirements. To make changes to your undercloud configuration after installation, edit the relevant configuration files and re-run the openstack undercloud install command.

Procedure

  1. Modify the undercloud configuration files. For example, edit the undercloud.conf file and add the idrac hardware type to the list of enabled hardware types:

    enabled_hardware_types = ipmi,redfish,idrac
  2. Run the openstack undercloud install command to refresh your undercloud with the new changes:

    [stack@director ~]$ openstack undercloud install

    Wait until the command runs to completion.

  3. Initialize the stack user to use the command line tools,:

    [stack@director ~]$ source ~/stackrc

    The prompt now indicates OpenStack commands authenticate and execute against the undercloud:

    (undercloud) [stack@director ~]$
  4. Verify the director has applied the new configuration. For this example, check the list of enabled hardware types:

    (undercloud) [stack@director ~]$ openstack baremetal driver list
    +---------------------+----------------+
    | Supported driver(s) | Active host(s) |
    +---------------------+----------------+
    | idrac               | unused         |
    | ipmi                | unused         |
    | redfish             | unused         |
    +---------------------+----------------+

The undercloud re-configuration is complete.

4.9. Undercloud container registry

Red Hat Enterprise Linux 8 no longer includes the docker-distribution package, which installed a Docker Registry v2. To maintain the compatibility and the same level of feature, the director installation creates an Apache web server with a vhost called image-serve to provide a registry. This registry also uses port 8787/TCP with SSL disabled. The Apache-based registry is not containerized, which means you run the following command to restart the registry:

You can find the container registry logs in the following locations:

  • /var/log/httpd/image_serve_access.log
  • /var/log/httpd/image_serve_error.log.
$ sudo systemctl restart httpd

The image content is served from /var/lib/image-serve. This location uses a specific directory layout and apache configuration to implement the pull function of the registry REST API.

Note

The Apache-based registry is a read-only container registry and does not support podman push nor buildah push commands. This means the registry does not allow you to push non-director and non-OpenStack Platform containers. However, you can modify OpenStack Platform images with the director’s container preparation workflow, which uses the ContainerImagePrepare parameter.

4.10. Next Steps

This completes the director configuration and installation. The next chapter explores basic overcloud configuration, including registering nodes, inspecting them, and then tagging them into various node roles.