Chapter 4. Installing the Undercloud
The first step to creating your Red Hat OpenStack Platform environment is to install the director on the Undercloud system. This involves a few prerequisite steps to enable the necessary subscriptions and repositories.
4.1. Creating a Director Installation User
The director installation process requires a non-root user to execute commands. Use the following commands to create the user named
stack and set a password:
[root@director ~]# useradd stack [root@director ~]# passwd stack # specify a password
Disable password requirements for this user when using
[root@director ~]# echo "stack ALL=(root) NOPASSWD:ALL" | tee -a /etc/sudoers.d/stack [root@director ~]# chmod 0440 /etc/sudoers.d/stack
Switch to the new
[root@director ~]# su - stack [stack@director ~]$
Continue the director installation as the
4.2. Creating Directories for Templates and Images
The director uses system images and Heat templates to create the Overcloud environment. To keep these files organized, we recommend creating directories for images and templates:
$ mkdir ~/images $ mkdir ~/templates
Other sections in this guide use these two directories to store certain files.
4.3. Setting the Hostname for the System
The director requires a fully qualified domain name for its installation and configuration process. This means you may need to set the hostname of your director’s host. Check the hostname of your host:
$ hostname # Checks the base hostname $ hostname -f # Checks the long hostname (FQDN)
If either commands do not report the correct hostname or report an error, use
hostnamectl to set a hostname:
$ sudo hostnamectl set-hostname manager.example.com $ sudo hostnamectl set-hostname --transient manager.example.com
The director also requires an entry for the system’s hostname and base name in
/etc/hosts. For example, if the system is named
/etc/hosts requires an entry like:
127.0.0.1 manager.example.com manager localhost localhost.localdomain localhost4 localhost4.localdomain4
4.4. Registering your System
To install the Red Hat OpenStack Platform director, first register the host system using Red Hat Subscription Manager, and subscribe to the required channels.
Register your system with the Content Delivery Network, entering your Customer Portal user name and password when prompted:
$ sudo subscription-manager register
Find the entitlement pool for the Red Hat OpenStack Platform director.
$ sudo subscription-manager list --available --all
Use the pool ID located in the previous step to attach the Red Hat OpenStack Platform 9 entitlements:
$ sudo subscription-manager attach --pool=pool_id
Disable all default repositories, and then enable the required Red Hat Enterprise Linux repositories:
$ sudo subscription-manager repos --disable=* $ sudo subscription-manager repos --enable=rhel-7-server-rpms --enable=rhel-7-server-extras-rpms --enable=rhel-7-server-openstack-9-rpms --enable=rhel-7-server-openstack-9-director-rpms --enable=rhel-7-server-rh-common-rpms
These repositories contain packages the director installation requires.
Only enable the repositories listed above. Additional repositories can cause package and software conflicts. Do not enable any additional repositories.
Perform an update on your system to make sure you have the latest base system packages:
$ sudo yum update -y $ sudo reboot
The system is now ready for the director installation.
4.5. Installing the Director Packages
Use the following command to install the required command line tools for director installation and configuration:
$ sudo yum install -y python-tripleoclient
This installs all packages required for the director installation.
4.6. Configuring the Director
The director installation process requires certain settings to determine your network configurations. The settings are stored in a template located in the
stack user’s home directory as
Red Hat provides a basic template to help determine the required settings for your installation. Copy this template to the
stack user’s home directory:
$ cp /usr/share/instack-undercloud/undercloud.conf.sample ~/undercloud.conf
The basic template contains the following parameters:
The IP address defined for the director’s Provisioning NIC. This is also the IP address the director uses for its DHCP and PXE boot services. Leave this value as the default
192.0.2.1/24unless you are using a different subnet for the Provisioning network, for example, if it conflicts with an existing IP address or subnet in your environment.
The gateway for the Overcloud instances. This is the Undercloud host, which forwards traffic to the External network. Leave this as the default
192.0.2.1unless you are either using a different IP address for the director or want to directly use an external gateway.Note
The director’s configuration script also automatically enables IP forwarding using the relevant
The IP address defined for the director’s Public API. Use an IP address on the Provisioning network that does not conflict with any other IP addresses or address ranges. For example,
192.0.2.2. The director configuration attaches this IP address to its software bridge as a routed IP address, which uses the
The IP address defined for the director’s Admin API. Use an IP address on the Provisioning network that does not conflict with any other IP addresses or address ranges. For example,
192.0.2.3. The director configuration attaches this IP address to its software bridge as a routed IP address, which uses the
- The location and filename of the certificate for OpenStack SSL communication. Ideally, you obtain this certificate from a trusted certificate authority. Otherwise generate your own self-signed certificate using the guidelines in Appendix A, SSL/TLS Certificate Configuration. These guidelines also contain instructions on setting the SELinux context for your certificate, whether self-signed or from an authority.
The chosen interface for the director’s Provisioning NIC. This is also the device the director uses for its 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: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 link/ether 52:54:00:75:24:09 brd ff:ff:ff:ff:ff:ff inet 192.168.122.178/24 brd 192.168.122.255 scope global dynamic eth0 valid_lft 3462sec preferred_lft 3462sec inet6 fe80::5054:ff:fe75:2409/64 scope link valid_lft forever preferred_lft forever 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noop state DOWN link/ether 42:0b:c2:a5:c1:26 brd ff:ff:ff:ff:ff:ff
In this example, the External NIC uses
eth0and the Provisioning NIC uses
eth1, which is currently not configured. In this case, set the
eth1. The configuration script attaches this interface to a custom bridge defined with the
The network that the director uses to manage Overcloud instances. This is the Provisioning network. Leave this as the default
192.0.2.0/24unless you are using a different subnet for the Provisioning network.
Defines the network that will masquerade for external access. This provides the Provisioning network with a degree of network address translation (NAT) so that it has external access through the director. Leave this as the default (
192.0.2.0/24) unless you are using a different subnet for the Provisioning network.
- 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.
The bridge the director uses for node introspection. This is custom bridge that the director configuration creates. The
LOCAL_INTERFACEattaches to this bridge. Leave this as the default
A range of IP address that the director’s introspection service uses during the PXE boot and provisioning process. Use comma-separated values to define the start and end of this range. For example,
192.0.2.100,192.0.2.120. Make sure this range contains enough IP addresses for your nodes and does not conflict with the range for
Defines whether to enable extra hardware collection during the inspection process. Requires
python-hardware-detectpackage on the introspection image.
Runs a set of benchmarks during node introspection. Set to
trueto enable. This option is necessary if you intend to perform benchmark analysis when inspecting the hardware of registered nodes. See Section 5.2, “Inspecting the Hardware of Nodes” for more details.
Sets the log level of Undercloud services to
DEBUG. Set this value to
Defines whether to install the validation tools. The default is set to
false, but you can can enable using
Defines whether to use iPXE or standard PXE. The default is
true, which enables iPXE. Set to
falseto set to standard PXE. For more information, see "Changing from iPXE to PXE in Red Hat OpenStack Platform director" on the Red Hat Customer Portal.
- Defines whether to store events in Ceilometer on the Undercloud.
- undercloud_db_password; undercloud_admin_token; undercloud_admin_password; undercloud_glance_password; etc
The remaining parameters are the access details for all of the director’s services. No change is required for the values. The director’s configuration script automatically generates these values if blank in
undercloud.conf. You can retrieve all values after the configuration script completes.Important
The configuration file examples for these parameters use
<None>as a placeholder value. Setting these values to
<None>leads to a deployment error.
Modify the values for these parameters to suit your network. When complete, save the file and run the following command:
$ openstack undercloud install
This launches the director’s configuration script. The director installs additional packages and configures its services to suit the settings in the
undercloud.conf. This script takes several minutes to complete.
The configuration 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.
To initialize the
stack user to use the command line tools, run the following command:
$ source ~/stackrc
You can now use the director’s command line tools.
4.7. Obtaining Images for Overcloud Nodes
The director requires several disk images for provisioning Overcloud nodes. This includes:
- An introspection kernel and ramdisk - Used for bare metal system introspection over PXE boot.
- A deployment kernel and ramdisk - Used for system provisioning and deployment.
- An Overcloud kernel, ramdisk, and full image - A base Overcloud system that is written to the node’s hard disk.
Obtain these images from the
$ sudo yum install rhosp-director-images rhosp-director-images-ipa
Extract the archives to the
images directory on the
stack user’s home (
$ cd ~/images $ for i in /usr/share/rhosp-director-images/overcloud-full-latest-9.0.tar /usr/share/rhosp-director-images/ironic-python-agent-latest-9.0.tar; do tar -xvf $i; done
Import these images into the director:
$ openstack overcloud image upload --image-path /home/stack/images/
This uploads the following images into the director:
overcloud-full-vmlinuz. These are the images for deployment and the Overcloud. The script also installs the introspection images on the director’s PXE server.
View a list of the images in the CLI:
$ 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 will not show the introspection PXE images. The director copies these files to
[stack@host1 ~]$ ls -l /httpboot total 341460 -rwxr-xr-x. 1 root root 5153184 Mar 31 06:58 agent.kernel -rw-r--r--. 1 root root 344491465 Mar 31 06:59 agent.ramdisk -rw-r--r--. 1 root root 337 Mar 31 06:23 inspector.ipxe
4.8. Setting a Nameserver on the Undercloud’s Neutron Subnet
Overcloud nodes require a nameserver so that they can resolve hostnames through DNS. For a standard Overcloud without network isolation, the nameserver is defined using the Undercloud’s
neutron subnet. Use the following commands to define the nameserver for the environment:
$ neutron subnet-list $ neutron subnet-update [subnet-uuid] --dns-nameserver [nameserver-ip]
View the subnet to verify the nameserver:
$ neutron subnet-show [subnet-uuid] +-------------------+-----------------------------------------------+ | Field | Value | +-------------------+-----------------------------------------------+ | ... | | | dns_nameservers | 188.8.131.52 | | ... | | +-------------------+-----------------------------------------------+
If you aim to isolate service traffic onto separate networks, the Overcloud nodes use the
DnsServer parameter in your network environment templates. This is covered in the advanced configuration scenario in Section 6.2, “Isolating Networks”.
4.9. Backing Up the Undercloud
Red Hat provides a process to back up important data from the Undercloud host and the Red Hat OpenStack Platform director. For more information about Undercloud backups, see the "Back Up and Restore the Director Undercloud" guide.
4.10. Completing the Undercloud Configuration
This completes the Undercloud configuration. The next chapter explores basic Overcloud configuration, including registering nodes, inspecting them, and then tagging them into various node roles.