Undercloud Installation¶

This section contains instructions on how to install the undercloud and how to update components after installation.

Installing the Undercloud¶

Note

Instack-undercloud is deprecated in Rocky cycle. Containerized undercloud should be installed instead. See Containers based Undercloud Deployment for backward compatibility related information.

Note

Please ensure all your nodes (undercloud, compute, controllers, etc) have their internal clock set to UTC in order to prevent any issue with possible file future-dated timestamp if hwclock is synced before any timezone offset is applied.

Log in to your machine (baremetal or VM) where you want to install the undercloud as a non-root user (such as the stack user):
```
ssh <non-root-user>@<undercloud-machine>
```
Note

If you don’t have a non-root user created yet, log in as root and create one with following commands:
```
sudo useradd stack
sudo passwd stack  # specify a password

echo "stack ALL=(root) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/stack
sudo chmod 0440 /etc/sudoers.d/stack

su - stack
```
Note

The undercloud is intended to work correctly with SELinux enforcing. Installatoins with the permissive/disabled SELinux are not recommended. The undercloud_enable_selinux config option controls that setting.

Note

vlan tagged interfaces must follow the if_name.vlan_id convention, like for example: eth0.vlan100 or bond0.vlan120.
Baremetal

Ensure that there is a FQDN hostname set and that the $HOSTNAME environment variable matches that value. The easiest way to do this is to set the undercloud_hostname option in undercloud.conf before running the install. This will allow the installer to configure all of the hostname- related settings appropriately.

Alternatively the hostname settings can be configured manually, but this is strongly discouraged. The manual steps are as follows:
```
sudo hostnamectl set-hostname myhost.mydomain
sudo hostnamectl set-hostname --transient myhost.mydomain
```
An entry for the system’s FQDN hostname is also needed in /etc/hosts. For example, if the system is named myhost.mydomain, /etc/hosts should have an entry like:
```
127.0.0.1   myhost.mydomain myhost
```
Enable needed repositories:
RHEL

Enable optional repo:
```
sudo yum install -y yum-utils
sudo yum-config-manager --enable rhelosp-rhel-7-server-opt
```
Download and install the python2-tripleo-repos RPM from the current RDO repository. For example
```
sudo yum install -y https://trunk.rdoproject.org/centos7/current/python2-tripleo-repos-<version>.el7.centos.noarch.rpm
```
Note

tripleo-repos removes any repositories that it manages before each run. This means all repositories must be specified in a single tripleo-repos call. As an example, the correct way to install the current and ceph repos is to run tripleo-repos current ceph, not two separate calls.
Stable Branch

Enable the appropriate repos for the desired release, as indicated below. Do not enable any other repos not explicitly marked for that release.
Newton

Enable the current Newton repositories
sudo -E tripleo-repos -b newton current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b newton current ceph
Ocata

Enable the current Ocata repositories
sudo -E tripleo-repos -b ocata current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b ocata current ceph
Pike

Enable the current Pike repositories
sudo -E tripleo-repos -b pike current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b pike current ceph
Queens

Enable the current Queens repositories
sudo -E tripleo-repos -b queens current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b queens current ceph
Warning

The remaining repositories configuration steps below should not be done for stable releases!

Run tripleo-repos to install the appropriate repositories. The option below will enable the latest master TripleO packages and the latest promoted packages for all other OpenStack services and dependencies. There are other repository configurations available in tripleo-repos, see its --help output for details.
```
sudo -E tripleo-repos current-tripleo-dev
```
Ceph

Include the Ceph repository in the tripleo-repos command
```
sudo -E tripleo-repos current-tripleo-dev ceph
```

Install the TripleO CLI, which will pull in all other necessary packages as dependencies:
```
sudo yum install -y python-tripleoclient
```
Ceph

If you intend to deploy Ceph in the overcloud, or configure the overcloud to use an external Ceph cluster, and are running Pike or newer, then install ceph-ansible on the undercloud:
```
sudo yum install -y ceph-ansible
```
Prepare the configuration file:
```
cp /usr/share/python-tripleoclient/undercloud.conf.sample ~/undercloud.conf
```
It is backwards compatible with non-containerized instack underclouds.
Stable Branch

For a non-containerized undercloud, copy in the sample configuration file and edit it to reflect your environment:
```
cp /usr/share/instack-undercloud/undercloud.conf.sample ~/undercloud.conf
```
Note

There is a tool available that can help with writing a basic undercloud.conf: Undercloud Configuration Wizard It takes some basic information about the intended overcloud environment and generates sane values for a number of the important options.
(OPTIONAL) Generate configuration for preparing container images

As part of the undercloud install, an image registry is configured on port 8787. This is used to increase reliability of overcloud image pulls, and minimise overall network transfers. The undercloud registry will be populated with images required by the undercloud by generating the following containers-prepare-parameter.yaml file and including it in undercloud.conf: container_images_file=$HOME/containers-prepare-parameter.yaml:
```
openstack tripleo container image prepare default \
  --local-push-destination \
  --output-env-file ~/containers-prepare-parameter.yaml
```
See Container Image Preparation for details on using containers-prepare-parameter.yaml to control what can be done during the container images prepare phase of an undercloud install.

Additionally, docker_insecure_registries and docker_registry_mirror parameters allow to customize container registries via the undercloud.conf file.
(OPTIONAL) Override heat parameters and environment files used for undercloud deployment.

Similarly to overcloud deployments, see Overriding specific templates with local versions and Using a custom location for all templates, the undercloud.conf: custom_env_files and undercloud.conf: templates configuration parameters allow to use a custom heat templates location and override or specify additional information for Heat resources used for undercloud deployment.

Additionally, the undercloud.conf: roles_file parameter brings in the ultimate flexibility of Deploying with Custom Roles and Deploying with Composable Services. This allows you to deploy an undercloud composed of highly customized containerized services, with the same workflow that TripleO uses for overcloud deployments.

Note

The CLI and configuration interface used to deploy a containerized undercloud is the same as that used by ‘legacy’ non-containerized underclouds. As noted above however mechanism by which the undercloud is actually deployed is completely changed and what is more, for the first time aligns with the overcloud deployment. See the command openstack tripleo deploy --standalone help for details. That interface extention for standalone clouds is experimental for Rocky. It is normally should not be used directly for undercloud installations.
Run the command to install the undercloud:

SSL

To deploy an undercloud with SSL, see Deploying with SSL.

Validations

Validations will be installed and configured during undercloud installation. You can set enable_validations = false in undercloud.conf to prevent that.

To deploy an undercloud:
```
openstack undercloud install
```

Note

The undercloud is containerized by default as of Rocky.

Note

It’s possible to enable verbose logging with --verbose option.

Note

To install a deprecated instack undercloud, you’ll need to deploy with --use-heat=False option.

In Rocky, we will run all the OpenStack services in a moby container runtime unless the default settings are overwritten. This command requires 2 services to be running at all times. The first one is a basic keystone service, which is currently executed by tripleoclient itself, the second one is heat-all which executes the templates and installs the services. The latter can be run on baremetal or in a container (tripleoclient will run it in a container by default).

Once the install has completed, you should take note of the files stackrc and undercloud-passwords.conf. You can source stackrc to interact with the undercloud via the OpenStack command-line client. The undercloud-passwords.conf file contains the passwords used for each service in the undercloud. These passwords will be automatically reused if the undercloud is reinstalled on the same system, so it is not necessary to copy them to undercloud.conf.

Note

Heat installer configuration, logs and state is ephemeral for undercloud deployments. Generated artifacts for consequent deployments get overwritten or removed (when undercloud.conf: cleanup = true). Although, you can still find them stored in compressed files.

Miscellaneous undercloud deployment artifacts, like processed heat templates and compressed files, can be found in undercloud.conf: output_dir locations like ~/tripleo-heat-installer-templates.

There is also a compressed file created and placed into the output dir, named as undercloud-install-<TS>.tar.bzip2, where TS represents a timestamp.

Downloaded ansible playbooks and inventory files (see TripleO config-download User’s Guide: Deploying with Ansible) used for undercloud deployment are stored in the tempdir ~/undercloud-ansible-<XXXX> by default.

Note

Any passwords set in undercloud.conf will take precedence over the ones in undercloud-passwords.conf.

Note

The used undercloud installation command can be rerun to reapply changes from undercloud.conf to the undercloud. Note that this should not be done if an overcloud has already been deployed or is in progress.

Note

If running docker commands as a stack user after an undercloud install fail with a permission error, log out and log in again. The stack user does get added to the docker group during install, but that change gets reflected only after a new login.

Updating Undercloud Components¶

Note

Instack-undercloud is deprecated in Rocky cycle. Instack undercloud can only be upgraded to containerized undercloud. See Containers based Undercloud Deployment for backward compatibility related information.

Note

When updating the existing containerized undercloud installation, keep in mind the special cases described in Understanding undercloud/standalone stack updates.

Before upgrading the undercloud, it is highly suggested to perform a backup of the undercloud and validate that a restore works fine.

Remove all Delorean repositories:

Note

You may wish to backup your current repos before disabling them

mkdir -p /home/stack/REPOBACKUP
sudo mv /etc/yum.repos.d/delorean* /home/stack/REPOBACKUP

sudo rm /etc/yum.repos.d/delorean*

Enable new Delorean repositories:

Download and install the python2-tripleo-repos RPM from the current RDO repository. For example
```
sudo yum install -y https://trunk.rdoproject.org/centos7/current/python2-tripleo-repos-<version>.el7.centos.noarch.rpm
```
Note

tripleo-repos removes any repositories that it manages before each run. This means all repositories must be specified in a single tripleo-repos call. As an example, the correct way to install the current and ceph repos is to run tripleo-repos current ceph, not two separate calls.
Stable Branch

Enable the appropriate repos for the desired release, as indicated below. Do not enable any other repos not explicitly marked for that release.
Newton

Enable the current Newton repositories
sudo -E tripleo-repos -b newton current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b newton current ceph
Ocata

Enable the current Ocata repositories
sudo -E tripleo-repos -b ocata current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b ocata current ceph
Pike

Enable the current Pike repositories
sudo -E tripleo-repos -b pike current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b pike current ceph
Queens

Enable the current Queens repositories
sudo -E tripleo-repos -b queens current
Ceph

Include the Ceph repo in the tripleo-repos call
sudo -E tripleo-repos -b queens current ceph
Warning

The remaining repositories configuration steps below should not be done for stable releases!

Run tripleo-repos to install the appropriate repositories. The option below will enable the latest master TripleO packages and the latest promoted packages for all other OpenStack services and dependencies. There are other repository configurations available in tripleo-repos, see its --help output for details.
```
sudo -E tripleo-repos current-tripleo-dev
```
Ceph

Include the Ceph repository in the tripleo-repos command
```
sudo -E tripleo-repos current-tripleo-dev ceph
```

Clean the yum cache to ensure only the new repos are used
```
sudo yum clean all
sudo rm -rf /var/cache/yum
```
Update required package:
Validations

It is strongly recommended that you validate the state of your undercloud before starting any upgrade operations. The tripleo-validations repo has some ‘pre-upgrade’ validations that you can execute by following the instructions at validations to execute the “pre-upgrade” group
```
mistral execution-get-output $(openstack workflow execution create -f value -c ID tripleo.validations.v1.run_groups '{"group_names": ["pre-upgrade"]}')
```
Newton to Ocata

The following commands need to be run before the undercloud upgrade:
```
sudo systemctl stop openstack-*
sudo systemctl stop neutron-*
sudo systemctl stop openvswitch
sudo systemctl stop httpd
sudo yum update instack-undercloud openstack-puppet-modules openstack-tripleo-common
```
Ocata to Pike
Ceph

Prior to Pike, TripleO deployed Ceph with puppet-ceph. With the Pike release it is possible to use TripleO to deploy Ceph with either ceph-ansible or puppet-ceph, though puppet-ceph is deprecated. To use ceph-ansible, the CentOS Storage SIG Ceph repository must be enabled on the undercloud and the ceph-ansible package must then be installed:
sudo yum install --enablerepo=extras centos-release-ceph-jewel sudo yum install ceph-ansible
Ceph clusters deployed with Ocata via puppet-ceph will be migrated so that all of the existing Ceph services are run inside of containers. This migration will be managed not by puppet-ceph, but by ceph-ansible, which TripleO will use to control updates to the same ceph cluster after the Ocata to Pike upgrade.
Update TripleO CLI and dependencies
```
sudo yum update python-tripleoclient* openstack-tripleo-common openstack-tripleo-heat-templates
```
Run the undercloud upgrade command. This command will upgrade all packages and use puppet to apply new configuration and restart all OpenStack services
```
openstack undercloud upgrade
```
Note

The undercloud is containerized by default as of Rocky. Therefore, an undercloud deployed on Queens (non-containerized) will be upgraded to a containerized undercloud on Rocky, by default. To upgrade with instack undercloud, you’ll need to upgrade with --use-heat=False option. Note this isn’t tested and not supported.

Note

It’s possible to enable verbose logging with --verbose option. To cleanup an undercloud after its upgrade, you’ll need to set upgrade_cleanup to True in undercloud.conf. It’ll remove the rpms that were deployed by instack-undercloud, after the upgrade to a containerized undercloud.

Note

If you added custom OVS ports to the undercloud (e.g. in a virtual testing environment) you may need to re-add them at this point.
Proceed with Updating Content on Overcloud Nodes