Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 27. Performing advanced container image management

The default container image configuration suits most environments. In some situations, your container image configuration might require some customization, such as version pinning.

27.1. Pinning container images for the undercloud
Copy link

In certain circumstances, you might require a set of specific container image versions for your undercloud. In this situation, you must pin the images to a specific version. To pin your images, you must generate and modify a container configuration file, and then combine the undercloud roles data with the container configuration file to generate an environment file that contains a mapping of services to container images. Then include this environment file in the custom_env_files parameter in the undercloud.conf file.

Procedure

  1. Log in to the undercloud host as the stack user.

  2. Run the openstack tripleo container image prepare default command with the --output-env-file option to generate a file that contains the default image configuration: 

    $ sudo openstack tripleo container image prepare default \
--output-env-file undercloud-container-image-prepare.yaml
    Copy to Clipboard Toggle word wrap

  3. Modify the undercloud-container-image-prepare.yaml file according to the requirements of your environment.

    1. Remove the tag: parameter so that director can use the tag_from_label: parameter. Director uses this parameter to identify the latest version of each container image, pull each image, and tag each image on the container registry in director.
    2. Remove the Ceph labels for the undercloud.
    3. Ensure that the neutron_driver: parameter is empty. Do not set this parameter to OVN because OVN is not supported on the undercloud.

    4. Include your container image registry credentials: 

      ContainerImageRegistryCredentials:
  registry.redhat.io:
    myser: 'p@55w0rd!'
      Copy to Clipboard Toggle word wrap
      Note

      You cannot push container images to the undercloud registry on new underclouds because the image-serve registry is not installed yet. You must set the push_destination value to false, or use a custom value, to pull images directly from source. For more information, see Container image preparation parameters.

  4. Generate a new container image configuration file that uses the undercloud roles file combined with your custom undercloud-container-image-prepare.yaml file: 

    $ sudo openstack tripleo container image prepare \
-r /usr/share/openstack-tripleo-heat-templates/roles_data_undercloud.yaml \
-e undercloud-container-image-prepare.yaml \
--output-env-file undercloud-container-images.yaml
    Copy to Clipboard Toggle word wrap

    The undercloud-container-images.yaml file is an environment file that contains a mapping of service parameters to container images. For example, OpenStack Identity (keystone) uses the ContainerKeystoneImage parameter to define its container image: 

    ContainerKeystoneImage: undercloud.ctlplane.localdomain:8787/rhosp-rhel9/openstack-keystone:17.0
    Copy to Clipboard Toggle word wrap

    Note that the container image tag matches the {version}-{release} format.

  5. Include the undercloud-container-images.yaml file in the custom_env_files parameter in the undercloud.conf file. When you run the undercloud installation, the undercloud services use the pinned container image mapping from this file.

27.2. Pinning container images for the overcloud
Copy link

In certain circumstances, you might require a set of specific container image versions for your overcloud. In this situation, you must pin the images to a specific version. To pin your images, you must create the containers-prepare-parameter.yaml file, use this file to pull your container images to the undercloud registry, and generate an environment file that contains a pinned image list.

For example, your containers-prepare-parameter.yaml file might contain the following content: 

parameter_defaults:
  ContainerImagePrepare:
    - push_destination: true
      set:
        name_prefix: openstack-
        name_suffix: ''
        namespace: registry.redhat.io/rhosp-rhel9
        neutron_driver: ovn
      tag_from_label: '{version}-{release}'

  ContainerImageRegistryCredentials:
    registry.redhat.io:
      myuser: 'p@55w0rd!'
Copy to Clipboard Toggle word wrap

The ContainerImagePrepare parameter contains a single rule set. This rule set must not include the tag parameter and must rely on the tag_from_label parameter to identify the latest version and release of each container image. Director uses this rule set to identify the latest version of each container image, pull each image, and tag each image on the container registry in director.

Procedure

  1. Run the openstack tripleo container image prepare command, which pulls all images from the source defined in the containers-prepare-parameter.yaml file. Include the --output-env-file to specify the output file that will contain the list of pinned container images: 

    $ sudo openstack tripleo container image prepare -e /home/stack/templates/containers-prepare-parameter.yaml --output-env-file overcloud-images.yaml
    Copy to Clipboard Toggle word wrap

    The overcloud-images.yaml file is an environment file that contains a mapping of service parameters to container images. For example, OpenStack Identity (keystone) uses the ContainerKeystoneImage parameter to define its container image: 

    ContainerKeystoneImage: undercloud.ctlplane.localdomain:8787/rhosp-rhel9/openstack-keystone:17.0
    Copy to Clipboard Toggle word wrap

    Note that the container image tag matches the {version}-{release} format.

  2. Include the containers-prepare-parameter.yaml and overcloud-images.yaml files in that specific order with your environment file collection when you run the openstack overcloud deploy command: 

    $ openstack overcloud deploy --templates \
    ...
    -e /home/stack/containers-prepare-parameter.yaml \
    -e /home/stack/overcloud-images.yaml \
    ...
    Copy to Clipboard Toggle word wrap

The overcloud services use the pinned images listed in the overcloud-images.yaml file.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top