Menu Close

Chapter 4. Installing director on the undercloud

To configure and install director, set the appropriate parameters in the undercloud.conf file and run the undercloud installation command. After you have installed director, import the overcloud images that director will use to write to bare metal nodes during node provisioning.

4.1. Configuring director

The director installation process requires certain settings in the undercloud.conf configuration file, which director reads from the home directory of the stack user. Complete the following steps to copy default template as a foundation for your configuration.

Procedure

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

    [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.

Important

At minimum, you must set the container_images_file parameter to the environment file that contains your container image configuration. Without this parameter properly set to the appropriate file, director cannot obtain your container image rule set from the ContainerImagePrepare parameter nor your container registry authentication details from the ContainerImageRegistryCredentials parameter.

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 in addition to the default x86_64 architecture.

Note

When you enable support for ppc64le, you must also set ipxe_enabled to False. For more information on configuring your undercloud with multiple CPU architectures, see Configuring a multiple CPU architecture overcloud.

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 you run the deployment command. 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. Red Hat Enterprise Linux 8.4 only supports podman.
container_healthcheck_disabled
Disables containerized service health checks. Red Hat recommends that you enable health checks and leave this option set to false.
container_images_file

Heat environment file with container image information. This file can contain the following entries:

  • Parameters for all required container images
  • The ContainerImagePrepare parameter to drive the required image preparation. Usually the file that contains 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 files that you want to add to the undercloud installation.
deployment_user
The user who installs 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 the enable_node_discovery parameter to be enabled and you must include the driver in the enabled_hardware_types list.
enable_ironic; enable_ironic_inspector; enable_mistral; enable_nova; enable_tempest; enable_validations; enable_zaqar
Defines the core services that you want 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 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 the 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 you use other products that consume metrics data, such as Red Hat CloudForms.
Warning

RBAC is not supported by every component. The Alarming service (aodh) and Gnocchi do not take secure RBAC rules into account.

enabled_hardware_types
A list of hardware types that you want 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
Run host-based undercloud configuration using heat-all. Leave as true.
hieradata_override
Path to hieradata override file that configures Puppet hieradata on the director, providing custom configuration to services beyond the undercloud.conf parameters. If set, the undercloud installation copies this file to the /etc/puppet/hieradata directory and sets it as the first file in the hierarchy. For more information about using this feature, see Configuring hieradata on the undercloud.
inspection_extras
Defines whether to enable extra hardware collection during the inspection process. This parameter requires the python-hardware or python-hardware-detect packages on the introspection image.
inspection_interface
The bridge that 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.
ipv6_address_mode

IPv6 address configuration mode for the undercloud provisioning network. The following list contains the possible values for this parameter:

  • dhcpv6-stateless - Address configuration using router advertisement (RA) and optional information using DHCPv6.
  • dhcpv6-stateful - Address configuration and optional information using DHCPv6.
ipxe_enabled
Defines whether to use iPXE or standard PXE. The default is true, which enables iPXE. Set this parameter to false to use standard PXE. For PowerPC deployments, or for hybrid PowerPC and x86 deployments, set this value to false.
local_interface

The chosen interface for the director Provisioning NIC. This is also the device that 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: em0: <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 em0
       valid_lft 3462sec preferred_lft 3462sec
    inet6 fe80::5054:ff:fe75:2409/64 scope link
       valid_lft forever preferred_lft forever
3: em1: <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 em0 and the Provisioning NIC uses em1, which is currently not configured. In this case, set the local_interface to em1. 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 Provisioning NIC. This is also the IP address that 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 this IP address conflicts with an existing IP address or subnet in your environment.

For IPv6, the local IP address prefix length must be /64 to support both stateful and stateless connections.

local_mtu
The maximum transmission unit (MTU) that you want to use for the local_interface. Do not exceed 1500 for the undercloud.
local_subnet
The local subnet that you want 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 or YAML format template to configure the networking with os-net-config and ignores the network parameters set in undercloud.conf. Use this parameter when you want to configure bonding or add an option to the interface. For more information about customizing undercloud network interfaces, see Configuring undercloud network interfaces.
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 that you want to use when you deploy the overcloud.

Note

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

roles_file
The roles file that you want to use to override the default roles file for undercloud installation. It is highly recommended to leave this parameter unset so that the director installation uses the default roles file.
scheduler_max_attempts
The maximum number of times that 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 avoid potential race conditions 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. The default value includes only the ctlplane-subnet subnet. For more information, see Subnets.
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.

If the undercloud_admin_host is not in the same IP network as the local_ip, you must set the ControlVirtualInterface parameter to the interface on which you want the admin APIs on the undercloud to listen. By default, the admin APIs listen on the br-ctlplane interface. Set the ControlVirtualInterface parameter in a custom environment file, and include the custom environment file in the undercloud.conf file by configuring the custom_env_files parameter.

For information about customizing undercloud network interfaces, see Configuring undercloud network interfaces.

undercloud_debug
Sets the log level of undercloud services to DEBUG. Set this value to true to enable DEBUG log level.
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 you must configure all system host name settings appropriately.
undercloud_log_file
The path to a log file to store the undercloud install and upgrade logs. By default, the log file is install-undercloud.log in 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.

If the undercloud_public_host is not in the same IP network as the local_ip, you must set the PublicVirtualInterface parameter to the public-facing interface on which you want the public APIs on the undercloud to listen. By default, the public APIs listen on the br-ctlplane interface. Set the PublicVirtualInterface parameter in a custom environment file, and include the custom environment file in the undercloud.conf file by configuring the custom_env_files parameter.

For information about customizing undercloud network interfaces, see Configuring undercloud network interfaces.

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 do not specify a 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.

Important

Director cannot change the IP addresses for a subnet after director creates the subnet.

cidr
The network that 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 director.

Note

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

dhcp_start; dhcp_end
The start and end of the DHCP allocation range for overcloud nodes. Ensure that this range contains enough IP addresses to allocate your nodes.
dhcp_exclude
IP addresses to exclude in the DHCP allocation range.
dns_nameservers
DNS nameservers specific to the subnet. If no nameservers are defined for the subnet, the subnet uses nameservers defined in the undercloud_nameservers parameter.
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 director or want to use an external gateway directly.
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.
inspection_iprange
Temporary IP range for nodes on this network to use during the inspection process. This range must not overlap with the range defined by dhcp_start and dhcp_end but must be in the same IP subnet.

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 perform additional undercloud configuration with an environment file that contains heat parameters.

Procedure

  1. Create an environment file named /home/stack/templates/custom-undercloud-params.yaml.
  2. Edit this file and include your heat parameters. For example, to enable debugging for certain OpenStack Platform services include the following snippet in the custom-undercloud-params.yaml file:

    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 custom-undercloud-params.yaml 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 contains some common heat parameters that 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. Configuring hieradata on the undercloud

You can provide custom configuration for services beyond the available undercloud.conf parameters by configuring Puppet hieradata on the director.

Procedure

  1. Create a hieradata override file, for example, /home/stack/hieradata.yaml.
  2. Add the customized hieradata to the file. For example, add the following snippet to modify the Compute (nova) service parameter force_raw_images from the default value of True to False:

    nova::compute::force_raw_images: False

    If there is no Puppet implementation for the parameter you want to set, then use the following method to configure the parameter:

    nova::config::nova_config:
      DEFAULT/<parameter_name>:
        value: <parameter_value>

    For example:

    nova::config::nova_config:
      DEFAULT/network_allocate_retries:
        value: 20
      ironic/serial_console_state_timeout:
        value: 15
  3. Set the hieradata_override parameter in the undercloud.conf file to the path of the new /home/stack/hieradata.yaml file:

    hieradata_override = /home/stack/hieradata.yaml

4.6. Configuring the undercloud for bare metal provisioning over IPv6

If you have IPv6 nodes and infrastructure, you can configure the undercloud and the provisioning network to use IPv6 instead of IPv4 so that director can provision and deploy Red Hat OpenStack Platform onto IPv6 nodes. However, there are some considerations:

  • Dual stack IPv4/6 is not available.
  • Tempest validations might not perform correctly.
  • IPv4 to IPv6 migration is not available during upgrades.

Modify the undercloud.conf file to enable IPv6 provisioning in Red Hat OpenStack Platform.

Prerequisites

Procedure

  1. Open your undercloud.conf file.
  2. Specify the IPv6 address mode as either stateless or stateful:

    [DEFAULT]
    ipv6_address_mode = <address_mode>
    ...

    Replace <address_mode> with dhcpv6-stateless or dhcpv6-stateful, based on the mode that your NIC supports.

    Note

    When you use the stateful address mode, the firmware, chain loaders, and operating systems might use different algorithms to generate an ID that the DHCP server tracks. DHCPv6 does not track addresses by MAC, and does not provide the same address back if the identifier value from the requester changes but the MAC address remains the same. Therefore, when you use stateful DHCPv6 you must also complete the next step to configure the network interface.

  3. If you configured your undercloud to use stateful DHCPv6, specify the network interface to use for bare metal nodes:

    [DEFAULT]
    ipv6_address_mode = dhcpv6-stateful
    ironic_enabled_network_interfaces = neutron,flat
    ...
  4. Optional: Set the default network interface for bare metal nodes:

    [DEFAULT]
    ...
    ironic_default_network_interface = neutron
    ...
  5. Specify whether or not the undercloud should create a router on the provisioning network:

    [DEFAULT]
    ...
    enable_routed_networks: <true/false>
    ...
    • Replace <true/false> with true to enable routed networks and prevent the undercloud creating a router on the provisioning network. When true, the data center router must provide router advertisements.
    • Replace <true/false> with false to disable routed networks and create a router on the provisioning network.
  6. Configure the local IP address, and the IP address for the director Admin API and Public API endpoints over SSL/TLS:

    [DEFAULT]
    ...
    local_ip = <ipv6_address>
    undercloud_admin_host = <ipv6_address>
    undercloud_public_host = <ipv6_address>
    ...

    Replace <ipv6_address> with the IPv6 address of the undercloud.

  7. Optional: Configure the provisioning network that director uses to manage instances:

    [ctlplane-subnet]
    cidr = <ipv6_address>/<ipv6_prefix>
    ...
    • Replace <ipv6_address> with the IPv6 address of the network to use for managing instances when not using the default provisioning network.
    • Replace <ipv6_prefix> with the IP address prefix of the network to use for managing instances when not using the default provisioning network.
  8. Configure the DHCP allocation range for provisioning nodes:

    [ctlplane-subnet]
    cidr = <ipv6_address>/<ipv6_prefix>
    dhcp_start = <ipv6_address_dhcp_start>
    dhcp_end = <ipv6_address_dhcp_end>
    ...
    • Replace <ipv6_address_dhcp_start> with the IPv6 address of the start of the network range to use for the overcloud nodes.
    • Replace <ipv6_address_dhcp_end> with the IPv6 address of the end of the network range to use for the overcloud nodes.
  9. Optional: Configure the gateway for forwarding traffic to the external network:

    [ctlplane-subnet]
    cidr = <ipv6_address>/<ipv6_prefix>
    dhcp_start = <ipv6_address_dhcp_start>
    dhcp_end = <ipv6_address_dhcp_end>
    gateway = <ipv6_gateway_address>
    ...

    Replace <ipv6_gateway_address> with the IPv6 address of the gateway when not using the default gateway.

  10. Configure the DHCP range to use during the inspection process:

    [ctlplane-subnet]
    cidr = <ipv6_address>/<ipv6_prefix>
    dhcp_start = <ipv6_address_dhcp_start>
    dhcp_end = <ipv6_address_dhcp_end>
    gateway = <ipv6_gateway_address>
    inspection_iprange = <ipv6_address_inspection_start>,<ipv6_address_inspection_end>
    ...
    • Replace <ipv6_address_inspection_start> with the IPv6 address of the start of the network range to use during the inspection process.
    • Replace <ipv6_address_inspection_end> with the IPv6 address of the end of the network range to use during the inspection process.
    Note

    This range must not overlap with the range defined by dhcp_start and dhcp_end, but must be in the same IP subnet.

  11. Configure an IPv6 nameserver for the subnet:

    [ctlplane-subnet]
    cidr = <ipv6_address>/<ipv6_prefix>
    dhcp_start = <ipv6_address_dhcp_start>
    dhcp_end = <ipv6_address_dhcp_end>
    gateway = <ipv6_gateway_address>
    inspection_iprange = <ipv6_address_inspection_start>,<ipv6_address_inspection_end>
    dns_nameservers = <ipv6_dns>

    Replace <ipv6_dns> with the DNS nameservers specific to the subnet.

4.7. Configuring undercloud network interfaces

Include custom network configuration in the undercloud.conf file to install the undercloud with specific networking functionality. For example, some interfaces might not have DHCP. In this case, you must disable DHCP for these interfaces in the undercloud.conf file so that os-net-config can apply the configuration during the undercloud installation process.

Procedure

  1. Log in to the undercloud host.
  2. Create a new file undercloud-os-net-config.yaml and include the network configuration that you require.

    For more information, see Network interface reference in the Advanced Overcloud Customization guide.

    Here is an example:

    network_config:
    - name: br-ctlplane
      type: ovs_bridge
      use_dhcp: false
      dns_servers: 192.168.122.1
      domain: lab.example.com
      ovs_extra:
      - "br-set-external-id br-ctlplane bridge-id br-ctlplane"
      addresses:
      - ip_netmask: 172.20.0.1/26
      members:
      - type: interface
        name: nic2

    To create a network bond for a specific interface, use the following sample:

    network_config:
    - name: br-ctlplane
      type: ovs_bridge
      use_dhcp: false
      dns_servers: 192.168.122.1
      domain: lab.example.com
      ovs_extra:
      - "br-set-external-id br-ctlplane bridge-id br-ctlplane"
      addresses:
      - ip_netmask: 172.20.0.1/26
      members:
      - name: bond-ctlplane
        type: linux_bond
        use_dhcp: false
        bonding_options: "mode=active-backup"
        mtu: 1500
        members:
        - type: interface
          name: nic2
        - type: interface
          name: nic3
  3. Include the path to the undercloud-os-net-config.yaml file in the net_config_override parameter in the undercloud.conf file:

    [DEFAULT]
    ...
    net_config_override=undercloud-os-net-config.yaml
    ...
    Note

    Director uses the file that you include in the net_config_override parameter as the template to generate the /etc/os-net-config/config.yaml file. os-net-config manages the interfaces that you define in the template, so you must perform all undercloud network interface customization in this file.

  4. Install the undercloud.

Verification

  • After the undercloud installation completes successfully, verify that the /etc/os-net-config/config.yaml file contains the relevant configuration:

    network_config:
    - name: br-ctlplane
      type: ovs_bridge
      use_dhcp: false
      dns_servers: 192.168.122.1
      domain: lab.example.com
      ovs_extra:
      - "br-set-external-id br-ctlplane bridge-id br-ctlplane"
      addresses:
      - ip_netmask: 172.20.0.1/26
      members:
      - type: interface
        name: nic2

4.8. Installing director

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

Procedure

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

    [stack@director ~]$ openstack undercloud install

    This command launches the director configuration script. 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:

    • undercloud-passwords.conf - A list of all passwords for the director services.
    • stackrc - A set of initialization variables to help you access the director command line tools.
  2. The script also starts all OpenStack Platform service containers automatically. You can check the enabled containers with 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 that OpenStack commands authenticate and execute against the undercloud;

    (undercloud) [stack@director ~]$

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

4.9. Configuring the CPU architecture for the overcloud

Red Hat OpenStack Platform (RHOSP) configures the CPU architecture of an overcloud as x86_64 by default. You can also deploy overcloud Compute nodes on POWER (ppc64le) hardware. For the Compute node cluster, you can use the same architecture, or use a combination of x86_64 and ppc64le systems.

Note

The undercloud, Controller nodes, Ceph Storage nodes, and all other systems are supported only on x86_64 hardware.

4.9.1. Configuring POWER (ppc64le) as the single CPU architecture for the overcloud

The default CPU architecture of the Compute nodes on an overcloud is x86_64. To deploy overcloud Compute nodes on POWER (ppc64le) hardware, you can change the architecture to ppc64le.

Procedure

  1. Disable iPXE in the undercloud.conf file:

    [DEFAULT]
    ipxe_enabled = False
    Note

    For RHOSP 16.2.1 and earlier, this configuration causes any x86_64 nodes in your deployment to also boot in PXE/legacy mode. To configure a multiple CPU architecture for your overcloud, see Configuring a multiple CPU architecture overcloud.

  2. Install the undercloud:

    [stack@director ~]$ openstack undercloud install

    For more information, see Installing director on the undercloud.

  3. Wait until the installation script completes.
  4. Obtain and upload the images for the overcloud nodes. For more information, see Obtaining images for overcloud nodes.

4.9.2. Configuring a multiple CPU architecture overcloud

For RHOSP 16.2.2 and later, you can configure your undercloud to support both PXE and iPXE boot modes when your architecture includes both POWER (ppc64le) and x86_64 UEFI nodes.

Note

When your architecture includes POWER (ppc64le) nodes, RHOSP 16.2.1 and earlier supports only PXE boot.

Procedure

  1. Enable iPXE in the undercloud.conf file:

    [DEFAULT]
    ipxe_enabled = True
  2. Create a custom environment file for the undercloud, undercloud_noIronicIPXEEnabled.yaml.
  3. To change the default Bare Metal Provisioning service (ironic) iPXE setting to PXE, add the following configuration to undercloud_noIronicIPXEEnabled.yaml:

    parameter_defaults:
      IronicIPXEEnabled: false
      IronicInspectorIPXEEnabled: true
  4. If your architecture includes ppc64le nodes, add the following configuration to undercloud_noIronicIPXEEnabled.yaml to disable the boot timeout:

    parameter_defaults:
      ExtraConfig:
        ironic::config::ironic_config:
          ipmi/disable_boot_timeout:
            value: 'false'
  5. Include the custom environment file in the undercloud.conf file:

    [DEFAULT]
    ...
    custom_env_files = undercloud_noIronicIPXEEnabled.yaml
  6. Install the undercloud:

    [stack@director ~]$ openstack undercloud install

    For more information, see Installing director on the undercloud.

  7. Wait until the installation script completes.
  8. Register your overcloud nodes:

    (undercloud)$ openstack overcloud node import ~/nodes.json

    For more information on registering overcloud nodes, see Registering nodes for the overcloud.

  9. Wait for the node registration and configuration to complete.
  10. Confirm that director has successfully registered the nodes:

    (undercloud)$ openstack baremetal node list
  11. Check the existing capabilities of each registered node:

    $ openstack baremetal node show <node> -f json -c properties | jq -r .properties.capabilities
  12. Set the boot mode to uefi for each registered node by adding boot_mode:uefi to the existing capabilities of the node:

    $ openstack baremetal node set --property capabilities="boot_mode:uefi,<capability_1>,...,<capability_n>" <node>
    • Replace <node> with the ID of the bare metal node.
    • Replace <capability_1>, and all capabilities up to <capability_n>, with each capability that you retrieved in step 6.
  13. Obtain and upload the images for the overcloud nodes. For more information, see Multiple CPU architecture overcloud images.
  14. Set the boot mode for each node:

    • For legacy/PXE:

      $ openstack baremetal node set --boot-interface pxe <node_name>
    • For iPXE:

      $ openstack baremetal node set --boot-interface ipxe <node_name>

4.9.3. Using Ceph Storage in a multi-architecture overcloud

When you configure access to external Ceph in a multi-architecture cloud, set the CephAnsiblePlaybook parameter to /usr/share/ceph-ansible/site.yml.sample and include your client key and other Ceph-specific parameters.

For example:

parameter_defaults:
  CephAnsiblePlaybook: /usr/share/ceph-ansible/site.yml.sample
  CephClientKey: AQDLOh1VgEp6FRAAFzT7Zw+Y9V6JJExQAsRnRQ==
  CephClusterFSID: 4b5c8c0a-ff60-454b-a1b4-9747aa737d19
  CephExternalMonHost: 172.16.1.7, 172.16.1.8

4.9.4. Using composable services in a multi-architecture overcloud

The following services typically form part of the Controller node and are available for use in custom roles as Technology Preview:

  • Block Storage service (cinder)
  • Image service (glance)
  • Identity service (keystone)
  • Networking service (neutron)
  • Object Storage service (swift)
Note

Red Hat does not support features in Technology Preview.

For more information about composable services, see composable services and custom roles in the Advanced Overcloud Customization guide. Use the following example to understand how to move the listed services from the Controller node to a dedicated ppc64le node:

(undercloud) [stack@director ~]$ rsync -a /usr/share/openstack-tripleo-heat-templates/. ~/templates
(undercloud) [stack@director ~]$ cd ~/templates/roles
(undercloud) [stack@director roles]$ cat <<EO_TEMPLATE >ControllerPPC64LE.yaml
###############################################################################
# Role: ControllerPPC64LE                                                     #
###############################################################################
- name: ControllerPPC64LE
  description: |
    Controller role that has all the controller services loaded and handles
    Database, Messaging and Network functions.
  CountDefault: 1
  tags:
    - primary
    - controller
  networks:
    - External
    - InternalApi
    - Storage
    - StorageMgmt
    - Tenant
  # For systems with both IPv4 and IPv6, you may specify a gateway network for
  # each, such as ['ControlPlane', 'External']
  default_route_networks: ['External']
  HostnameFormatDefault: '%stackname%-controllerppc64le-%index%'
  ImageDefault: ppc64le-overcloud-full
  ServicesDefault:
    - OS::TripleO::Services::Aide
    - OS::TripleO::Services::AuditD
    - OS::TripleO::Services::CACerts
    - OS::TripleO::Services::CephClient
    - OS::TripleO::Services::CephExternal
    - OS::TripleO::Services::CertmongerUser
    - OS::TripleO::Services::CinderApi
    - OS::TripleO::Services::CinderBackendDellPs
    - OS::TripleO::Services::CinderBackendDellSc
    - OS::TripleO::Services::CinderBackendDellEMCUnity
    - OS::TripleO::Services::CinderBackendDellEMCVMAXISCSI
    - OS::TripleO::Services::CinderBackendDellEMCVNX
    - OS::TripleO::Services::CinderBackendDellEMCXTREMIOISCSI
    - OS::TripleO::Services::CinderBackendNetApp
    - OS::TripleO::Services::CinderBackendScaleIO
    - OS::TripleO::Services::CinderBackendVRTSHyperScale
    - OS::TripleO::Services::CinderBackup
    - OS::TripleO::Services::CinderHPELeftHandISCSI
    - OS::TripleO::Services::CinderScheduler
    - OS::TripleO::Services::CinderVolume
    - OS::TripleO::Services::Collectd
    - OS::TripleO::Services::Docker
    - OS::TripleO::Services::Fluentd
    - OS::TripleO::Services::GlanceApi
    - OS::TripleO::Services::GlanceRegistry
    - OS::TripleO::Services::Ipsec
    - OS::TripleO::Services::Iscsid
    - OS::TripleO::Services::Kernel
    - OS::TripleO::Services::Keystone
    - OS::TripleO::Services::LoginDefs
    - OS::TripleO::Services::MySQLClient
    - OS::TripleO::Services::NeutronApi
    - OS::TripleO::Services::NeutronBgpVpnApi
    - OS::TripleO::Services::NeutronSfcApi
    - OS::TripleO::Services::NeutronCorePlugin
    - OS::TripleO::Services::NeutronDhcpAgent
    - OS::TripleO::Services::NeutronL2gwAgent
    - OS::TripleO::Services::NeutronL2gwApi
    - OS::TripleO::Services::NeutronL3Agent
    - OS::TripleO::Services::NeutronLbaasv2Agent
    - OS::TripleO::Services::NeutronLbaasv2Api
    - OS::TripleO::Services::NeutronLinuxbridgeAgent
    - OS::TripleO::Services::NeutronMetadataAgent
    - OS::TripleO::Services::NeutronML2FujitsuCfab
    - OS::TripleO::Services::NeutronML2FujitsuFossw
    - OS::TripleO::Services::NeutronOvsAgent
    - OS::TripleO::Services::NeutronVppAgent
    - OS::TripleO::Services::Ntp
    - OS::TripleO::Services::ContainersLogrotateCrond
    - OS::TripleO::Services::OpenDaylightOvs
    - OS::TripleO::Services::Rhsm
    - OS::TripleO::Services::RsyslogSidecar
    - OS::TripleO::Services::Securetty
    - OS::TripleO::Services::SensuClient
    - OS::TripleO::Services::SkydiveAgent
    - OS::TripleO::Services::Snmp
    - OS::TripleO::Services::Sshd
    - OS::TripleO::Services::SwiftProxy
    - OS::TripleO::Services::SwiftDispersion
    - OS::TripleO::Services::SwiftRingBuilder
    - OS::TripleO::Services::SwiftStorage
    - OS::TripleO::Services::Timezone
    - OS::TripleO::Services::TripleoFirewall
    - OS::TripleO::Services::TripleoPackages
    - OS::TripleO::Services::Tuned
    - OS::TripleO::Services::Vpp
    - OS::TripleO::Services::OVNController
    - OS::TripleO::Services::OVNMetadataAgent
    - OS::TripleO::Services::Ptp
EO_TEMPLATE
(undercloud) [stack@director roles]$ sed -i~ -e '/OS::TripleO::Services::\(Cinder\|Glance\|Swift\|Keystone\|Neutron\)/d' Controller.yaml
(undercloud) [stack@director roles]$ cd ../
(undercloud) [stack@director templates]$ openstack overcloud roles generate \
    --roles-path roles -o roles_data.yaml \
    Controller Compute ComputePPC64LE ControllerPPC64LE BlockStorage ObjectStorage CephStorage

4.10. Obtaining images for overcloud nodes

Director requires several disk images to provision overcloud nodes:

  • An introspection kernel and ramdisk for bare metal system introspection over PXE boot.
  • A deployment kernel and ramdisk for system provisioning and deployment.
  • An overcloud kernel, ramdisk, and full image, which form a base overcloud system that director writes to the hard disk of the node.

You can obtain and install the images you need based on your CPU architecture. You can also obtain and install a basic image to provision a bare OS when you do not want to run any other Red Hat OpenStack Platform (RHOSP) services or consume one of your subscription entitlements.

4.10.1. Single CPU architecture overcloud images

Your Red Hat OpenStack Platform (RHOSP) installation includes packages that provide you with the following overcloud images for director:

  • overcloud-full
  • overcloud-full-initrd
  • overcloud-full-vmlinuz

These images are necessary for deployment of the overcloud with the default CPU architecture, x86-64. Importing these images into director also installs introspection images on the director PXE server.

Procedure

  1. Log in to the undercloud as the stack user.
  2. Source the stackrc file:

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

    (undercloud) [stack@director ~]$ sudo dnf install rhosp-director-images rhosp-director-images-ipa-x86_64
  4. Create the images directory in the home directory of the stack user (/home/stack/images).

    (undercloud) [stack@director ~]$ mkdir /home/stack/images
  5. Extract the images archives to the images directory:

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

    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path /home/stack/images/
  7. Verify that the images are uploaded:

    (undercloud) [stack@director images]$ openstack image list
    +--------------------------------------+------------------------+
    | ID                                   | Name                   |
    +--------------------------------------+------------------------+
    | ef793cd0-e65c-456a-a675-63cd57610bd5 | overcloud-full         |
    | 9a51a6cb-4670-40de-b64b-b70f4dd44152 | overcloud-full-initrd  |
    | 4f7e33f4-d617-47c1-b36f-cbe90f132e5d | overcloud-full-vmlinuz |
    +--------------------------------------+------------------------+
  8. Verify that director has copied the introspection PXE images 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.10.2. Multiple CPU architecture overcloud images

Your Red Hat OpenStack Platform (RHOSP) installation includes packages that provide you with the following images that are necessary for deployment of the overcloud with the default CPU architecture, x86-64:

  • overcloud-full
  • overcloud-full-initrd
  • overcloud-full-vmlinuz

Your RHOSP installation also includes packages that provide you with the following images that are necessary for deployment of the overcloud with the POWER (ppc64le) CPU architecture:

  • ppc64le-overcloud-full

Importing these images into director also installs introspection images on the director PXE server.

Procedure

  1. Log in to the undercloud as the stack user.
  2. Source the stackrc file:

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

    (undercloud) [stack@director ~]$ sudo dnf install rhosp-director-images-all
  4. Extract the archives to an architecture specific directory in the images directory in the home directory of the stack user (/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-16.1-${arch}.tar /usr/share/rhosp-director-images/ironic-python-agent-latest-16.1-${arch}.tar ; do tar -C $arch -xf $i ; done ; done
  5. Import the images into director:

    (undercloud) [stack@director ~]$ cd ~/images
    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path ~/images/ppc64le --architecture ppc64le --whole-disk --http-boot /var/lib/ironic/tftpboot/ppc64le
    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path ~/images/ppc64le --architecture ppc64le --whole-disk --image-type ironic-python-agent --http-boot /var/lib/ironic/httpboot/ppc64le
    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path ~/images/x86_64/ --architecture x86_64 --http-boot /var/lib/ironic/tftpboot
    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path ~/images/x86_64 --architecture x86_64 --image-type ironic-python-agent --http-boot /var/lib/ironic/httpboot
  6. Verify that the images are uploaded:

    (undercloud) [stack@director images]$ openstack image list
    +--------------------------------------+---------------------------+--------+
    | ID                                   | Name                      | Status |
    +--------------------------------------+---------------------------+--------+
    | 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 |
    | f0fedcd0-3f28-4b44-9c88-619419007a03 | ppc64le-overcloud-full    | active |
    +--------------------------------------+---------------------------+--------+
  7. Verify that director has copied the introspection PXE images to /var/lib/ironic/tftpboot:

    (undercloud) [stack@director images]$ ls -l /var/lib/ironic/tftpboot /var/lib/ironic/tftpboot/ppc64le/
    /var/lib/ironic/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 42422 42422      20832 Aug  8 02:08 chain.c32
    -rwxr--r--. 1 42422 42422     715584 Aug  8 02:06 ipxe.efi
    -rw-r--r--. 1 root  root          22 Aug  8 02:06 map-file
    drwxr-xr-x. 2 42422 42422         62 Aug  8 19:34 ppc64le
    -rwxr--r--. 1 42422 42422      26826 Aug  8 02:08 pxelinux.0
    drwxr-xr-x. 2 42422 42422         21 Aug  8 02:06 pxelinux.cfg
    -rwxr--r--. 1 42422 42422      69631 Aug  8 02:06 undionly.kpxe
    
    /var/lib/ironic/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 42422 42422       336 Aug  8 02:06 default

4.10.3. Enabling multiple CPU architectures on container images

If your Red Hat OpenStack Platform (RHOSP) deployment has a multiple CPU architecture, and it uses container images, you must update the container images to enable multiple architectures.

Procedure

  1. Log in to the undercloud as the stack user.
  2. Source the stackrc file:

    [stack@director ~]$ source ~/stackrc
  3. Add the additional architectures to the containers-prepare-parameter.yaml file to enable multiple architectures:

    parameter_defaults:
      ContainerImageRegistryLogin: true
      AdditionalArchitectures: [<list_of_architectures>]
      ContainerImagePrepare:
      - push_destination: true
        ...

    Replace <list_of_architectures> with a comma-separated list of the architectures supported by your overcloud environment, for example, [ppc64le].

  4. Prepare and upload the containers:

    $ openstack tripleo container image prepare \
      -e ~/containers-prepare-parameter.yaml

4.10.4. Minimal overcloud image

You can use the overcloud-minimal image to provision a bare OS where you do not want to run any other Red Hat OpenStack Platform (RHOSP) services or consume one of your subscription entitlements.

Your RHOSP installation includes the overcloud-minimal package that provides you with the following overcloud images for director:

  • overcloud-minimal
  • overcloud-minimal-initrd
  • overcloud-minimal-vmlinuz
Note

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

Procedure

  1. Log in to the undercloud as the stack user.
  2. Source the stackrc file:

    [stack@director ~]$ source ~/stackrc
  3. Install the overcloud-minimal package:

    (undercloud) [stack@director ~]$ sudo dnf install rhosp-director-images-minimal
  4. Extract the images archives to the images directory in the home directory of the stack user (/home/stack/images):

    (undercloud) [stack@director ~]$ cd ~/images
    (undercloud) [stack@director images]$ tar xf /usr/share/rhosp-director-images/overcloud-minimal-latest-16.2.tar
  5. Import the images into director:

    (undercloud) [stack@director images]$ openstack overcloud image upload --image-path /home/stack/images/ --os-image-name overcloud-minimal.qcow2
  6. Verify that the images are uploaded:

    (undercloud) [stack@director images]$ openstack image list
    +--------------------------------------+---------------------------+
    | ID                                   | Name                      |
    +--------------------------------------+---------------------------+
    | ef793cd0-e65c-456a-a675-63cd57610bd5 | overcloud-full            |
    | 9a51a6cb-4670-40de-b64b-b70f4dd44152 | overcloud-full-initrd     |
    | 4f7e33f4-d617-47c1-b36f-cbe90f132e5d | overcloud-full-vmlinuz    |
    | 32cf6771-b5df-4498-8f02-c3bd8bb93fdd | overcloud-minimal         |
    | 600035af-dbbb-4985-8b24-a4e9da149ae5 | overcloud-minimal-initrd  |
    | d45b0071-8006-472b-bbcc-458899e0d801 | overcloud-minimal-vmlinuz |
    +--------------------------------------+---------------------------+

4.11. Setting a nameserver for the control plane

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

Procedure

  1. Source the stackrc file to enable the director 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 must use the DnsServers parameter in your network environment files. You must also set the control plane nameserver and the DnsServers parameter to the same DNS server.

4.12. Updating the undercloud configuration

If you need to change the undercloud configuration to suit new requirements, you can 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 that OpenStack commands authenticate and execute against the undercloud:

    (undercloud) [stack@director ~]$
  4. Verify that 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               | director.example.com |
    | ipmi                | director.example.com |
    | redfish             | director.example.com |
    +---------------------+----------------------+

The undercloud re-configuration is complete.

4.13. Undercloud container registry

Red Hat Enterprise Linux 8.4 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 that you must run the following command to restart the registry:

$ sudo systemctl restart httpd

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.

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.

The Apache-based registry does not support podman push nor buildah push commands, which means that you cannot push container images using traditional methods. To modify images during deployment, use the container preparation workflow, such as the ContainerImagePrepare parameter. To manage container images, use the container management commands:

openstack tripleo container image list
Lists all images stored on the registry.
openstack tripleo container image show
Show metadata for a specific image on the registry.
openstack tripleo container image push
Push an image from a remote registry to the undercloud registry.
openstack tripleo container image delete
Delete an image from the registry.