Chapter 4. Installing director
4.1. Configuring the director Copy linkLink copied to clipboard!
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
Copy the default template to the
stackuser’s home directory:[stack@director ~]$ cp \ /usr/share/python-tripleoclient/undercloud.conf.sample \ ~/undercloud.conf-
Edit the
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.
4.2. Director configuration parameters Copy linkLink copied to clipboard!
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
ppc64learchitecture.NoteWhen enabling support for ppc64le, you must also set
ipxe_enabledtoFalse- certificate_generation_ca
-
The
certmongernickname of the CA that signs the requested certificate. Use this option only if you have set thegenerate_service_certificateparameter. If you select thelocalCA, certmonger extracts the local CA certificate to/etc/pki/ca-trust/source/anchors/cm-local-ca.pemand 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
Falseto 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_images_file
Heat environment file with container image information. This can either be:
- Parameters for all required container images
-
Or the
ContainerImagePrepareparameter to drive the required image preparation. Usually the file containing this parameter is namedcontainers-prepare-parameter.yaml.
- 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_discoveryenabled and you must include the driver in theenabled_hardware_typeslist. - docker_insecure_registries
-
A list of insecure registries for
dockerto use. Use this parameter if you want to pull images from another source, such as a private container registry. In most cases, docker 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. - docker_registry_mirror
-
An optional
registry-mirrorconfigured in/etc/docker/daemon.json - 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_ui
-
Defines whether to install the director web UI. Use this parameter to perform overcloud planning and deployments through a graphical web interface. Note that the UI is only available with SSL/TLS enabled using either the
undercloud_service_certificateorgenerate_service_certificate. - enable_node_discovery
-
Automatically enroll any unknown node that PXE-boots the introspection ramdisk. New nodes use the
fake_pxedriver as a default but you can setdiscovery_default_driverto override. You can also use introspection rules to specify driver information for newly enrolled nodes. - enable_novajoin
-
Defines whether to install the
novajoinmetadata 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_telemetryparameter totrueif you want to install and configure telemetry services automatically. The default value isfalse, 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_certificateparameter. The undercloud installation saves the resulting certificate/etc/pki/tls/certs/undercloud-[undercloud_public_vip].pem. The CA defined in thecertificate_generation_caparameter 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
hieradataoverride file that configures Puppet hieradata on the director, providing custom configuration to services beyond theundercloud.confparameters. If set, the undercloud installation copies this file to the/etc/puppet/hieradatadirectory and sets it as the first file in the hierarchy. See Configuring hieradata on the undercloud for details on using this feature. - inspection_extras
-
Defines whether to enable extra hardware collection during the inspection process. This parameter requires
python-hardwareorpython-hardware-detectpackage 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_INTERFACEattaches to this bridge. Leave this as the defaultbr-ctlplane. - inspection_runbench
-
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. - ipa_otp
-
Defines the one time password to register the Undercloud node to an IPA server. This is required when
enable_novajoinis enabled. - ipxe_enabled
-
Defines whether to use iPXE or standard PXE. The default is
true, which enables iPXE. Set tofalseto 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 addrcommand. For example, this is the result of anip addrcommand: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:ffIn this example, the External NIC uses
eth0and the Provisioning NIC useseth1, which is currently not configured. In this case, set thelocal_interfacetoeth1. The configuration script attaches this interface to a custom bridge defined with theinspection_interfaceparameter.- 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/24unless 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. Do not exceed 1500 for the undercloud. - local_subnet
-
The local subnet to use for PXE boot and DHCP interfaces. The
local_ipaddress should reside in this subnet. The default isctlplane-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 inundercloud.conf. See/usr/share/python-tripleoclient/undercloud.conf.samplefor an example. - 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.
NoteWhen configuring the overcloud, the
CloudDomainparameter 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-subnetsubnet. - templates
- Heat templates file to override.
- undercloud_admin_host
-
The IP address defined for the director Admin API when using SSL/TLS. This is an IP address for administration endpoint access over SSL/TLS. The director configuration attaches the director’s IP address to its software bridge as a routed IP address, which uses the
/32netmask. - undercloud_debug
-
Sets the log level of undercloud services to
DEBUG. Set this value totrueto enable. - undercloud_enable_selinux
-
Enable or disable SELinux during the deployment. It is highly recommended to leave this value set to
trueunless 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.logwithin 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 defined for the director Public API when using SSL/TLS. This is an IP address for accessing the director endpoints externally over SSL/TLS. The director configuration attaches this IP address to the director software bridge as a routed IP address, which uses the
/32netmask. - 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_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.1unless you use a different IP address for the director or want to use an external gateway directly.
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
neutronservice manages. Leave this as the default192.168.24.0/24unless you use a different subnet for the Provisioning network. - masquerade
-
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 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.
Modify the values of these parameters to suit your configuration. When complete, save the file.
4.3. Configuring the undercloud with environment files Copy linkLink copied to clipboard!
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
-
Create an environment file at
/home/stack/templates/custom-undercloud-params.yaml. Edit this file and include your Heat parameters. The following example shows how to enable debugging for certain OpenStack Platform services:
parameter_defaults: Debug: TrueSave this file when you have finished.
Edit your
undercloud.conffile and scroll to thecustom_env_filesparameter. Edit the parameter to point to your environment file:custom_env_files = /home/stack/templates/custom-undercloud-params.yamlNoteYou 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 Copy linkLink copied to clipboard!
The following table shows some common Heat parameters you might set in a custom environment file for your undercloud.
| Parameter | Description |
|---|---|
|
|
Sets the undercloud |
|
|
Sets the undercloud |
|
| Enables debug mode. |
|
|
The timezone to set on the undercloud. The default value is: |
Set these parameters in your custom environment file under the parameter_defaults section:
parameter_defaults:
Debug: True
AdminPassword: "myp@ssw0rd!"
AdminEmail: "admin@example.com"
TimeZone: "AEST"
4.5. Configuring hieradata on the undercloud Copy linkLink copied to clipboard!
You can provide custom configuration for services beyond the available undercloud.conf parameters by configuring Puppet hieradata on the director. Perform the following procedure to use this feature.
Procedure
-
Create a hieradata override file, for example,
/home/stack/hieradata.yaml. Add the customized hieradata to the file. For example, add the following to modify the Compute (nova) service parameter
force_raw_imagesfrom the default value of "True" to "False":nova::compute::force_raw_images: FalseIf 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: 15Set the
hieradata_overrideparameter to the path of the hieradata file in yourundercloud.conf:hieradata_override = /home/stack/hieradata.yaml
4.6. Installing the director Copy linkLink copied to clipboard!
Complete the following procedure to install the director and perform some basic post-installation tasks.
Procedure
Run the following command to install the director on the undercloud:
[stack@director ~]$ openstack undercloud installThis 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.
-
The script also starts all OpenStack Platform service containers automatically. Check the enabled containers using the following command:
[stack@director ~]$ sudo docker psThe script adds the
stackuser to thedockergroup to give thestackuser access to container management commands. Refresh thestackuser’s permissions with the following command:[stack@director ~]$ exec su -l stackThe command prompts you to log in again. Enter the stack user’s password.
To initialize the
stackuser to use the command line tools, run the following command:[stack@director ~]$ source ~/stackrcThe 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.7. Obtaining images for overcloud nodes Copy linkLink copied to clipboard!
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.7.1. Single CPU architecture overclouds Copy linkLink copied to clipboard!
These images and procedures are necessary for deployment of the overcloud with the default CPU architecture, x86-64.
Procedure
Source the
stackrcfile to enable the director’s command line tools:[stack@director ~]$ source ~/stackrcInstall the
rhosp-director-imagesandrhosp-director-images-ipapackages:(undercloud) [stack@director ~]$ sudo yum install rhosp-director-images rhosp-director-images-ipaExtract the images archives to the
imagesdirectory in thestackuser’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-14.0.tar /usr/share/rhosp-director-images/ironic-python-agent-latest-14.0.tar; do tar -xvf $i; doneImport 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.
-
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.7.2. Multiple CPU architecture overclouds Copy linkLink copied to clipboard!
First ensure additional_architectures is set to ppc64le in undercloud.conf, you must also set ipxe_enabled to False
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
Source the
stackrcfile to enable the director’s command line tools:[stack@director ~]$ source ~/stackrcInstall the
rhosp-director-images-allpackage:(undercloud) [stack@director ~]$ sudo yum install rhosp-director-images-allExtract the archives to an architecture specific directory under the
imagesdirectory on thestackuser’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-14.0-${arch}.tar /usr/share/rhosp-director-images/ironic-python-agent-latest-14.0-${arch}.tar ; do tar -C $arch -xf $i ; done ; doneImport 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 /tftpbootThis 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-fullThe script also installs the introspection images on the director’s PXE server.
-
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
The default overcloud-full.qcow2 image is a flat partition image. However, you can also import and use whole disk images. See Appendix C, Whole Disk Images for more information.
4.8. Setting a nameserver for the control plane Copy linkLink copied to clipboard!
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
Source the
stackrcfile to enable the director’s command line tools:[stack@director ~]$ source ~/stackrcSet the nameservers for the
ctlplane-subnetsubnet:(undercloud) [stack@director images]$ openstack subnet set --dns-nameserver [nameserver1-ip] --dns-nameserver [nameserver2-ip] ctlplane-subnetUse the
--dns-nameserveroption for each nameserver.View the subnet to verify the nameserver:
(undercloud) [stack@director images]$ openstack subnet show ctlplane-subnet +-------------------+-----------------------------------------------+ | Field | Value | +-------------------+-----------------------------------------------+ | ... | | | dns_nameservers | 8.8.8.8 | | ... | | +-------------------+-----------------------------------------------+
If you aim to isolate service traffic onto separate networks, the overcloud nodes use the DnsServers parameter in your network environment files.
4.9. Updating the undercloud configuration Copy linkLink copied to clipboard!
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
Modify the undercloud configuration files. For example, edit the
undercloud.conffile and add theidrachardware type to the list of enabled hardware types:enabled_hardware_types = ipmi,redfish,idracRun the
openstack undercloud installcommand to refresh your undercloud with the new changes:[stack@director ~]$ openstack undercloud installWait until the command runs to completion.
Initialize the
stackuser to use the command line tools,:[stack@director ~]$ source ~/stackrcThe prompt now indicates OpenStack commands authenticate and execute against the undercloud:
(undercloud) [stack@director ~]$
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.10. Next Steps Copy linkLink copied to clipboard!
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.