Chapter 4. Installing the Undercloud

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 sudo:

[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 stack user:

[root@director ~]# su - stack
[stack@director ~]$

Continue the director installation as the stack user.

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:

[stack@director ~]$ mkdir ~/images
[stack@director ~]$ mkdir ~/templates

Other sections in this guide use these two directories to store certain files.

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:

[stack@director ~]$ hostname    # Checks the base hostname
[stack@director ~]$ 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:

[stack@director ~]$ sudo hostnamectl set-hostname manager.example.com
[stack@director ~]$ 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 manager.example.com, then /etc/hosts requires an entry like:

127.0.0.1   manager.example.com manager localhost localhost.localdomain localhost4 localhost4.localdomain4

To install the Red Hat OpenStack Platform director, first register the host system using Red Hat Subscription Manager, and subscribe to the required channels.

These repositories contain packages the director installation requires.

Perform an update on your system to make sure you have the latest base system packages:

[stack@director ~]$ sudo yum update -y
[stack@director ~]$ sudo reboot

The system is now ready for the director installation.

Use the following command to install the required command line tools for director installation and configuration:

[stack@director ~]$ sudo yum install -y python-tripleoclient

This installs all packages required for the director installation.

If you aim to create an overcloud with Ceph Storage nodes, install the additional ceph-ansible package:

[stack@director ~]$ sudo yum install -y ceph-ansible

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 undercloud.conf.

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:

[stack@director ~]$ cp /usr/share/instack-undercloud/undercloud.conf.sample ~/undercloud.conf

The undercloud.conf file contains settings to configure your undercloud. If you omit or comment out a parameter, the undercloud installation uses the default value.

The template contains two sections: [DEFAULT] and [auth]. The [DEFAULT] section contains the following parameters:

The [auth] section contains the following parameters:

Modify the values for these parameters to suit your network. When complete, save the file and run the following command:

[stack@director ~]$ 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:

The configuration also starts all OpenStack Platform services automatically. Check the enabled services using the following command:

[stack@director ~]$ sudo systemctl list-units openstack-*

The installation also adds the stack user to the docker group so the stack user has access to container management commands. Refresh the stack user’s permissions with the following command:

[stack@director ~]$ exec su -l stack

The command prompts you to log in again. Enter the stack user’s password.

To initialize the stack user to use the command line tools, run the following command:

[stack@director ~]$ source ~/stackrc

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

(undercloud) [stack@director ~]$

You can now use the director’s command line tools.

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

Obtain these images from the rhosp-director-images and rhosp-director-images-ipa packages:

(undercloud) [stack@director ~]$ sudo yum install rhosp-director-images rhosp-director-images-ipa

Extract the archives to the images directory on the stack user’s home (/home/stack/images):

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

Import these images into the director:

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

This uploads the following images into the director: bm-deploy-kernel, bm-deploy-ramdisk, overcloud-full, overcloud-full-initrd, 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:

(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 will not show the introspection PXE images. The director copies these files to /httpboot.

(undercloud) [stack@director images]$ 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 ironic-inspector  ironic-inspector        337 Mar 31 06:23 inspector.ipxe

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 neutron subnet. Use the following commands to define nameservers for the environment:

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

View the subnet to verify the nameserver:

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

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.

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.