Chapter 3. Installing the undercloud with containers
This chapter provides info on how to create a container-based undercloud and keep it updated.
3.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.
Copy the default template to the home directory of the
[stack@director ~]$ cp \ /usr/share/python-tripleoclient/undercloud.conf.sample \ ~/undercloud.conf
undercloud.conffile. This file contains settings to configure your undercloud. If you omit or comment out a parameter, the undercloud installation uses the default value.
3.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.
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
The following parameters are defined in the
[DEFAULT] section of the
A list of additional (kernel) architectures that an overcloud supports. Currently the overcloud supports
When you enable support for ppc64le, you must also set
certmongernickname of the CA that signs the requested certificate. Use this option only if you have set the
generate_service_certificateparameter. If you select the
localCA, certmonger extracts the local CA certificate to
/etc/pki/ca-trust/source/anchors/cm-local-ca.pemand adds the certificate to the trust chain.
- Defines whether to wipe the hard drive between deployments and after introspection.
Cleanup temporary files. Set this to
Falseto 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.
The CLI tool for container management. Leave this parameter set to
podman. Red Hat Enterprise Linux 8.2 only supports
Disables containerized service health checks. Red Hat recommends that you enable health checks and leave this option set to
Heat environment file with container image information. This file can contain the following entries:
- Parameters for all required container images
ContainerImagePrepareparameter to drive the required image preparation. Usually the file that contains this parameter is named
A list of insecure registries for
podmanto use. Use this parameter if you want to pull images from another source, such as a private container registry. In most cases,
podmanhas 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.
- Additional environment files that you want to add to the undercloud installation.
The user who installs the undercloud. Leave this parameter unset to use the current default user
Sets the default driver for automatically enrolled nodes. Requires the
enable_node_discoveryparameter to be enabled and you must include the driver in the
- 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
Automatically enroll any unknown node that PXE-boots the introspection ramdisk. New nodes use the
fakedriver as a default but you can set
discovery_default_driverto override. You can also use introspection rules to specify driver information for newly enrolled nodes.
Defines whether to install the
novajoinmetadata service in the undercloud.
- Defines whether to enable support for routed control plane networks.
- Defines whether to enable Swift encryption at-rest.
Defines whether to install OpenStack Telemetry services (gnocchi, aodh, panko) in the undercloud. Set the
trueif 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.
- A list of hardware types that you want to enable for the undercloud.
Defines whether to generate an SSL/TLS certificate during the undercloud installation, which is used for the
undercloud_service_certificateparameter. The undercloud installation saves the resulting certificate
/etc/pki/tls/certs/undercloud-[undercloud_public_vip].pem. The CA defined in the
certificate_generation_caparameter signs this certificate.
- URL for the heat container image to use. Leave unset.
Run host-based undercloud configuration using
heat-all. Leave as
hieradataoverride file that configures Puppet hieradata on the director, providing custom configuration to services beyond the
undercloud.confparameters. If set, the undercloud installation copies this file to the
/etc/puppet/hieradatadirectory and sets it as the first file in the hierarchy. For more information about using this feature, see Configuring hieradata on the undercloud.
Defines whether to enable extra hardware collection during the inspection process. This parameter requires the
python-hardware-detectpackages on the introspection image.
The bridge that director uses for node introspection. This is a custom bridge that the director configuration creates. The
LOCAL_INTERFACEattaches to this bridge. Leave this as the default
Runs a set of benchmarks during node introspection. Set this parameter to
trueto enable the benchmarks. This option is necessary if you intend to perform benchmark analysis when inspecting the hardware of registered nodes.
Defines the one-time password to register the undercloud node to an IPA server. This is required when
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.
Defines whether to use iPXE or standard PXE. The default is
true, which enables iPXE. Set this parameter to
falseto use standard PXE.
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 addrcommand. For example, this is the result of an
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
em0and the Provisioning NIC uses
em1, which is currently not configured. In this case, set the
em1. The configuration script attaches this interface to a custom bridge defined with the
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/24unless 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.
The maximum transmission unit (MTU) that you want to use for the
local_interface. Do not exceed 1500 for the undercloud.
The local subnet that you want to use for PXE boot and DHCP interfaces. The
local_ipaddress should reside in this subnet. The default is
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-configand ignores the network parameters set in
undercloud.conf. Use this parameter when you want to configure bonding or add an option to the interface. See
/usr/share/instack-undercloud/templates/net-config.json.templatefor an example. For more information about customizing undercloud network interfaces, see Configuring undercloud network interfaces.
Networks file to override for
- Directory to output state, processed heat templates, and Ansible deployment files.
The DNS domain name that you want to use when you deploy the overcloud.Note
When you configure the overcloud, you must set the
CloudDomainparameter to a matching value. Set this parameter in an environment file when you configure your overcloud.
- 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.
- 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.
- The Kerberos principal for the service using the certificate. Use this parameter only if your CA requires a Kerberos principal, such as in FreeIPA.
List of routed network subnets for provisioning and introspection. The default value includes only the
ctlplane-subnetsubnet. For more information, see Subnets.
- Heat templates file to override.
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
Sets the log level of undercloud services to
DEBUG. Set this value to
Enable or disable SELinux during the deployment. It is highly recommended to leave this value set to
trueunless you are debugging an issue.
- 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.
The path to a log file to store the undercloud install and upgrade logs. By default, the log file is
install-undercloud.login the home directory. For example,
- A list of DNS nameservers to use for the undercloud hostname resolution.
- A list of network time protocol servers to help synchronize the undercloud date and time.
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
- 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.
- Host timezone for the undercloud. If you do not specify a timezone, director uses the existing timezone configuration.
- Defines whether to update packages during the undercloud installation.
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
[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.
Director cannot change the IP addresses for a subnet after director creates the subnet.
The network that director uses to manage overcloud instances. This is the Provisioning network, which the undercloud
neutronservice manages. Leave this as the default
192.168.24.0/24unless you use a different subnet for the Provisioning network.
Defines whether to masquerade the network defined in the
cidrfor 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
- 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.
- IP addresses to exclude in the DHCP allocation range.
DNS nameservers specific to the subnet. If no nameservers are defined for the subnet, the subnet uses nameservers defined in the
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.1unless you use a different IP address for director or want to use an external gateway directly.
Host routes for the Neutron-managed subnet for the overcloud instances on this network. This also configures the host routes for the
local_subneton the undercloud.
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_endbut must be in the same IP subnet.
Modify the values for these parameters to suit your configuration. When complete, save the file.
3.3. Installing director
Complete the following steps to install director and perform some basic post-installation tasks.
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.
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
To initialize the
stackuser 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.
3.4. Performing a minor update of a containerized undercloud
Director provides commands to update the main packages on the undercloud node. This allows you to perform a minor update within the current version of your OpenStack Platform environment.
Log in to the director as the
dnfto upgrade the director main packages:
$ sudo dnf update -y python3-tripleoclient* openstack-tripleo-common openstack-tripleo-heat-templates tripleo-ansible ansible
The director uses the
openstack undercloud upgradecommand to update the undercloud environment. Run the command:
$ openstack undercloud upgrade
- Wait until the undercloud upgrade process completes.
Reboot the undercloud to update the operating system’s kernel and other system packages:
$ sudo reboot
- Wait until the node boots.