Chapter 2. Upgrading the undercloud Upgrade the undercloud to Red Hat OpenStack Platform 17.1. The undercloud upgrade uses the running Red Hat OpenStack Platform 16.2 undercloud. The upgrade process exports heat stacks to files, and converts heat to ephemeral heat while upgrading the rest of the services on your nodes. For information about the duration and impact of this upgrade procedure, see Upgrade duration and impact . 2.1. Enabling repositories for the undercloud Enable the repositories that are required for the undercloud, and update the system packages to the latest versions. Procedure Log in to your undercloud as the stack user. Disable all default repositories, and enable the required Red Hat Enterprise Linux (RHEL) repositories: Switch the container-tools module version to RHEL 8 on all nodes: Install the command line tools for director installation and configuration: 2.2. Validating RHOSP before the upgrade Before you upgrade to Red Hat OpenStack Platform (RHOSP) 17.1, validate your undercloud and overcloud with the tripleo-validations playbooks. In RHOSP 16.2, you run these playbooks through the OpenStack Workflow Service (mistral). For more information about the validation framework, see Using the validation framework in Customizing your Red Hat OpenStack Platform deployment . Prerequisites Confirm that you can ping the overcloud nodes: Replace <stack> with the name of the stack. Procedure Log in to the undercloud host as the stack user. Source the stackrc undercloud credentials file: Adjust the permissions of the /var/lib/mistral/.ssh directory: Install the packages for validation: Copy the inventory from mistral: Run the validation: Review the script output to determine which validations succeed and fail: 2.3. Preparing container images The undercloud installation requires an environment file to determine where to obtain container images and how to store them. Generate and customize the environment file that you can use to prepare your container images. Note If you need to configure specific container image versions for your undercloud, you must pin the images to a specific version. For more information, see Pinning container images for the undercloud . Procedure Log in to the undercloud host as the stack user. Optional: Back up the 16.2 containers-prepare-parameter.yaml file: Generate the default container image preparation file: This command includes the following additional options: --local-push-destination sets the registry on the undercloud as the location for container images. This means that director pulls the necessary images from the Red Hat Container Catalog and pushes them to the registry on the undercloud. Director uses this registry as the container image source. To pull directly from the Red Hat Container Catalog, omit this option. --output-env-file is an environment file name. The contents of this file include the parameters for preparing your container images. In this case, the name of the file is containers-prepare-parameter.yaml . Note You can use the same containers-prepare-parameter.yaml file to define a container image source for both the undercloud and the overcloud. Modify the containers-prepare-parameter.yaml to suit your requirements. For more information about container image parameters, see Container image preparation parameters . If your deployment includes Red Hat Ceph Storage, update the Red Hat Ceph Storage container image parameters in the containers-prepare-parameter.yaml file for the version of Red Hat Ceph Storage that your deployment uses: Replace <ceph_image_file> with the name of the image file for the version of Red Hat Ceph Storage that your deployment uses: If you use director-deployed Red Hat Ceph Storage, replace <ceph_image_file> with rhceph-5-rhel8 . If you use external Red Hat Ceph Storage, replace <ceph_image_file> with the same Ceph image that your Red Hat Ceph Storage environment uses. For example, for a Red Hat Ceph Storage 6 image, use rhceph-6-rhel9 . Replace <grafana_image_file> with the name of the image file for the version of Red Hat Ceph Storage that your deployment uses: If you use director-deployed Red Hat Ceph Storage, replace <grafana_image_file> with rhceph-5-dashboard-rhel8 . If you use external Red Hat Ceph Storage, replace <grafana_image_file> with the same Ceph image that your Red Hat Ceph Storage environment uses. For example, for a Red Hat Ceph Storage 6 image, use rhceph-6-dashboard-rhel9 . 2.4. Guidelines for container image tagging The Red Hat Container Registry uses a specific version format to tag all Red Hat OpenStack Platform container images. This format follows the label metadata for each container, which is version-release . version Corresponds to a major and minor version of Red Hat OpenStack Platform. These versions act as streams that contain one or more releases. release Corresponds to a release of a specific container image version within a version stream. For example, if the latest version of Red Hat OpenStack Platform is 17.1.0 and the release for the container image is 5.161 , then the resulting tag for the container image is 17.1.0-5.161. The Red Hat Container Registry also uses a set of major and minor version tags that link to the latest release for that container image version. For example, both 17.1 and 17.1.0 link to the latest release in the 17.1.0 container stream. If a new minor release of 17.1 occurs, the 17.1 tag links to the latest release for the new minor release stream while the 17.1.0 tag continues to link to the latest release within the 17.1.0 stream. The ContainerImagePrepare parameter contains two sub-parameters that you can use to determine which container image to download. These sub-parameters are the tag parameter within the set dictionary, and the tag_from_label parameter. Use the following guidelines to determine whether to use tag or tag_from_label . The default value for tag is the major version for your OpenStack Platform version. For this version it is 17.1. This always corresponds to the latest minor version and release. To change to a specific minor version for OpenStack Platform container images, set the tag to a minor version. For example, to change to 17.1.2, set tag to 17.1.2. When you set tag , director always downloads the latest container image release for the version set in tag during installation and updates. If you do not set tag , director uses the value of tag_from_label in conjunction with the latest major version. The tag_from_label parameter generates the tag from the label metadata of the latest container image release it inspects from the Red Hat Container Registry. For example, the labels for a certain container might use the following version and release metadata: The default value for tag_from_label is {version}-{release} , which corresponds to the version and release metadata labels for each container image. For example, if a container image has 17.1.0 set for version and 5.161 set for release , the resulting tag for the container image is 17.1.0-5.161. The tag parameter always takes precedence over the tag_from_label parameter. To use tag_from_label , omit the tag parameter from your container preparation configuration. A key difference between tag and tag_from_label is that director uses tag to pull an image only based on major or minor version tags, which the Red Hat Container Registry links to the latest image release within a version stream, while director uses tag_from_label to perform a metadata inspection of each container image so that director generates a tag and pulls the corresponding image. 2.5. Obtaining container images from private registries The registry.redhat.io registry requires authentication to access and pull images. To authenticate with registry.redhat.io and other private registries, include the ContainerImageRegistryCredentials and ContainerImageRegistryLogin parameters in your containers-prepare-parameter.yaml file. ContainerImageRegistryCredentials Some container image registries require authentication to access images. In this situation, use the ContainerImageRegistryCredentials parameter in your containers-prepare-parameter.yaml environment file. The ContainerImageRegistryCredentials parameter uses a set of keys based on the private registry URL. Each private registry URL uses its own key and value pair to define the username (key) and password (value). This provides a method to specify credentials for multiple private registries. In the example, replace my_username and my_password with your authentication credentials. Instead of using your individual user credentials, Red Hat recommends creating a registry service account and using those credentials to access registry.redhat.io content. To specify authentication details for multiple registries, set multiple key-pair values for each registry in ContainerImageRegistryCredentials : Important The default ContainerImagePrepare parameter pulls container images from registry.redhat.io , which requires authentication. For more information, see Red Hat Container Registry Authentication . ContainerImageRegistryLogin The ContainerImageRegistryLogin parameter is used to control whether an overcloud node system needs to log in to the remote registry to fetch the container images. This situation occurs when you want the overcloud nodes to pull images directly, rather than use the undercloud to host images. You must set ContainerImageRegistryLogin to true if push_destination is set to false or not used for a given strategy. However, if the overcloud nodes do not have network connectivity to the registry hosts defined in ContainerImageRegistryCredentials and you set ContainerImageRegistryLogin to true , the deployment might fail when trying to perform a login. If the overcloud nodes do not have network connectivity to the registry hosts defined in the ContainerImageRegistryCredentials , set push_destination to true and ContainerImageRegistryLogin to false so that the overcloud nodes pull images from the undercloud. 2.6. Updating the undercloud.conf file You can continue using the original undercloud.conf file from your Red Hat OpenStack Platform 16.2 environment, but you must modify the file to retain compatibility with Red Hat OpenStack Platform 17.1. For more information about parameters for configuring the undercloud.conf file, see Undercloud configuration parameters in Installing and managing Red Hat OpenStack Platform with director . Note If your original undercloud.conf file includes the CertmongerKerberosRealm parameter in the /home/stack/custom-kerberos-params.yaml file, you must replace the CertmongerKerberosRealm parameter with the HAProxyCertificatePrincipal parameter. The CertmongerKerberosRealm parameter causes the undercloud upgrade to fail. Procedure Log in to your undercloud host as the stack user. Create a file called skip_rhel_release.yaml and set the SkipRhelEnforcement parameter to true : Open the undercloud.conf file, and add the container_images_file parameter to the DEFAULT section in the file: The container_images_file parameter defines the location of the containers-prepare-parameter.yaml environment file so that director pulls container images for the undercloud from the correct location. Add the custom_env_files parameter to the DEFAULT section in the undercloud.conf file. The custom_env_files parameter defines the location of the skip_rhel_release.yaml file that is required for the upgrade: Add any additional custom environment files to the custom_env_files parameter, separated by a comma. Ensure that any existing files in the parameter are included in the list. For example: Check all other parameters in the file for any changes. Save the file. 2.7. Network configuration file conversion If your network configuration templates include the following functions, you must manually convert your NIC templates to Jinja2 Ansible format before you upgrade the undercloud. The following functions are not supported with automatic conversion: 'get_file' 'get_resource' 'digest' 'repeat' 'resource_facade' 'str_replace' 'str_replace_strict' 'str_split' 'map_merge' 'map_replace' 'yaql' 'equals' 'if' 'not' 'and' 'or' 'filter' 'make_url' 'contains' For more information about manually converting your NIC templates, see Manually converting NIC templates to Jinja2 Ansible format in Customizing your Red Hat OpenStack Platform deployment . 2.8. Running the director upgrade Upgrade director on the undercloud. Prerequisites Confirm that the tripleo_mysql.service is running: If the service is not running, start the service: If your network configuration templates include certain functions, ensure that you manually convert your NIC templates to Jinja2 Ansible format. For a list of those functions and a link to the manual procedure, see Network configuration file conversion . Important Before you run the undercloud upgrade, extract the following files and check that there are no issues. If there are issues, the files might not generate during the undercloud upgrade. For more information about extracting the files, see Files are not generated after undercloud upgrade during RHOSP upgrade from 16.2 to 17.1 . tripleo-<stack>-passwords.yaml tripleo-<stack>-network-data.yaml tripleo-<stack>-virtual-ips.yaml tripleo-<stack>-baremetal-deployment.yaml Procedure Launch the director configuration script to upgrade director: The director configuration script upgrades director packages and configures director services to match the settings in the undercloud.conf file. This script takes several minutes to complete. Note The director configuration script prompts for confirmation before proceeding. Bypass this confirmation by using the -y option:

Commands:
[stack@director ~]USD sudo subscription-manager repos --disable=* [stack@director ~]USD sudo subscription-manager repos --enable=rhel-8-for-x86_64-baseos-tus-rpms --enable=rhel-8-for-x86_64-appstream-tus-rpms --enable=rhel-8-for-x86_64-highavailability-tus-rpms --enable=openstack-17.1-for-rhel-8-x86_64-rpms --enable=fast-datapath-for-rhel-8-x86_64-rpms
[stack@director ~]USD sudo dnf -y module switch-to container-tools:rhel8
[stack@director ~]USD sudo dnf install -y python3-tripleoclient
source ~/stackrc tripleo-ansible-inventory --static-yaml-inventory ~/inventory.yaml --stack <stack> --ansible_ssh_user heat-admin ansible -i ~/inventory.yaml all -m ping
source ~/stackrc
sudo chmod +x /var/lib/mistral/.ssh/
sudo dnf -y update openstack-tripleo-validations python3-validations-libs validations-common
sudo chown stack:stack /var/lib/mistral/.ssh/tripleo-admin-rsa sudo cat /var/lib/mistral/<stack>/tripleo-ansible-inventory.yaml > inventory.yaml
validation run -i inventory.yaml --group pre-upgrade
=== Running validation: "check-ftype" === Success! The validation passed for all hosts: * undercloud
cp containers-prepare-parameter.yaml containers-prepare-parameter.yaml.orig
openstack tripleo container image prepare default --local-push-destination --output-env-file containers-prepare-parameter.yaml
ceph_namespace: registry.redhat.io/rhceph ceph_image: <ceph_image_file> ceph_tag: latest ceph_grafana_image: <grafana_image_file> ceph_grafana_namespace: registry.redhat.io/rhceph ceph_grafana_tag: latest
parameter_defaults: ContainerImagePrepare: - set: tag: 17.1
parameter_defaults: ContainerImagePrepare: - set: tag: 17.1.2
parameter_defaults: ContainerImagePrepare: - set: # tag: 17.1 tag_from_label: '{version}-{release}'
"Labels": { "release": "5.161", "version": "17.1.0", }
parameter_defaults: ContainerImagePrepare: - push_destination: true set: namespace: registry.redhat.io/ ContainerImageRegistryCredentials: registry.redhat.io: my_username: my_password
parameter_defaults: ContainerImagePrepare: - push_destination: true set: namespace: registry.redhat.io/ - push_destination: true set: namespace: registry.internalsite.com/ ContainerImageRegistryCredentials: registry.redhat.io: myuser: 'p@55w0rd!' registry.internalsite.com: myuser2: '0th3rp@55w0rd!' '192.0.2.1:8787': myuser3: '@n0th3rp@55w0rd!'
parameter_defaults: ContainerImagePrepare: - push_destination: false set: namespace: registry.redhat.io/ ContainerImageRegistryCredentials: registry.redhat.io: myuser: 'p@55w0rd!' ContainerImageRegistryLogin: true
parameter_defaults: ContainerImagePrepare: - push_destination: true set: namespace: registry.redhat.io/ ContainerImageRegistryCredentials: registry.redhat.io: myuser: 'p@55w0rd!' ContainerImageRegistryLogin: false
parameter_defaults: SkipRhelEnforcement: true
container_images_file = /home/stack/containers-prepare-parameter.yaml
custom_env_files = /home/stack/skip_rhel_release.yaml
custom_env_files = /home/stack/custom-undercloud-params.yaml,/home/stack/skip_rhel_release.yaml
systemctl status tripleo_mysql
sudo systemctl start tripleo_mysql
openstack undercloud upgrade
openstack undercloud upgrade -y