Chapter 5. Configuring Container Registry Details

A containerized overcloud requires access to a registry with the required container images. This chapter provides information on how to prepare the registry and your overcloud configuration to use container images for Red Hat OpenStack Platform.

This guide provides several use cases to configure your overcloud to use a registry. Before attempting one of these use cases, it is recommended to familiarize yourself with how to use the image preparation command. See Section 5.1, “Using the Container Image Preparation Command” for more information.

Selecting a Registry Method

Red Hat OpenStack Platform supports the following registry types:

Remote Registry
The overcloud pulls container images directly from registry.access.redhat.com. This method is the easiest for generating the initial configuration. However, each overcloud node pulls each image directly from the Red Hat Container Catalog, which can cause network congestion and slower deployment. In addition, all overcloud nodes require internet access to the Red Hat Container Catalog.
Local Registry
You create a local registry on the undercloud, synchronize the images from registry.access.redhat.com, and the overcloud pulls the container images from the undercloud. This method allows you to store a registry internally, which can speed up the deployment and decrease network congestion. However, the undercloud only acts as a basic registry and provides limited life cycle management for container images.
Satellite Server
Manage the complete application life cycle of your container images and publish them through a Red Hat Satellite 6 server. The overcloud pulls the images from the Satellite server. This method provides an enterprise grade solution to store, manage, and deploy Red Hat OpenStack Platform containers.

Select a method from the list and continue configuring your registry details.

5.1. Using the Container Image Preparation Command

This section provides an overview on how to use the openstack overcloud container image prepare command, including conceptual information on the command’s various options. You can find proper use cases and end-to-end procedures for using this command in Selecting a Registry Method.

Generating a Container Image Environment File for the Overcloud

One of the main uses of the openstack overcloud container image prepare command is to create an environment file that contains a list of images the overcloud uses. You include this file with your overcloud deployment commands, such as openstack overcloud deploy. The openstack overcloud container image prepare command uses the following options for this function:

--output-env-file
Defines the resulting environment file name.

The following snippet is an example of this file’s contents:

parameter_defaults:
  DockerAodhApiImage: registry.access.redhat.com/rhosp12/openstack-aodh-api:latest
  DockerAodhConfigImage: registry.access.redhat.com/rhosp12/openstack-aodh-api:latest
...

Generating a Container Image List for Import Methods

If you aim to import the OpenStack Platform container images to a different registry source, you can generate a list of images. The syntax of list is primarily used to import container images to the container registry on the undercloud, but you can modify the format of this list to suit other import methods, such as Red Hat Satellite 6.

The openstack overcloud container image prepare command uses the following options for this function:

--output-images-file
Defines the resulting file name for the import list.

The following is an example of this file’s contents:

container_images:
- imagename: registry.access.redhat.com/rhosp12/openstack-aodh-api:latest
- imagename: registry.access.redhat.com/rhosp12/openstack-aodh-evaluator:latest
...

Setting the Namespace for Container Images

Both the --output-env-file and --output-images-file options require a namespace to generate the resulting image locations. The openstack overcloud container image prepare command uses the following options to set the source location of the container images to pull:

--namespace
Defines the namespace for the container images. This is usually a hostname or IP address with a directory.
--prefix
Defines the prefix to add before the image names.

As a result, the director generates the image names using the following format:

  • [NAMESPACE]/[PREFIX][IMAGE NAME]

Setting Container Image Tags

The openstack overcloud container image prepare command uses the latest tag for each container image by default. However, you can select a specific tag for an image version using the following option:

--tag
Sets the tag for all images. All OpenStack Platform container images use the same tag to provide version synchronicity.

You can also discover the latest versioned tag for an image using the openstack overcloud container image tag discover command. For example:

$ sudo openstack overcloud container image tag discover \
  --image registry.access.redhat.com/rhosp12/openstack-base:latest \
  --tag-from-label version-release

This checks the tags available for the openstack-base image using the image’s version-release label as a basis and outputs the latest versioned tag.

Important

You must run the tag discovery command with sudo access. This command uses docker as a sub-process, which requires sudo privileges.

5.2. Adding Container Images for Additional Services

The director only prepares container images for core OpenStack Platform Services [1]. Some additional features use services that require additional container images. You enable these services with environment files. The openstack overcloud container image prepare command uses the following option to include environment files and their respective container images:

-e
Include environment files to enable additional container images.
Note

For more information on how to include environment files in a deployment, see Section 6.8, “Including Environment Files in Overcloud Creation”.

The following table provides a sample list of additional services that use container images and their respective environment file locations within the /usr/share/openstack-tripleo-heat-templates directory.

ServiceEnvironment File

Ceph Storage

environments/ceph-ansible/ceph-ansible.yaml

Collectd

environments/services-docker/collectd.yaml

Congress

environments/services-docker/congress.yaml

Fluentd

environments/services-docker/fluentd-client.yaml

OpenStack Bare Metal (ironic)

environments/services-docker/ironic.yaml

OpenStack Data Processing (sahara)

environments/services-docker/sahara.yaml

OpenStack EC2-API

environments/services-docker/ec2-api.yaml

Sensu

environments/services-docker/sensu-client.yaml

The next few sections provide examples of including additional services.

Ceph Storage

If deploying a Red Hat Ceph Storage cluster with your overcloud, you need to include the /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml environment file. This file enables the composable containerized services in your overcloud and the director needs to know these services are enabled to prepare their images.

In addition to this environment file, you also need to define the Ceph Storage container location, which is different from the OpenStack Platform services. Use the --set option to set the following parameters specific to Ceph Storage:

--set ceph_namespace
Defines the namespace for the Ceph Storage container image. This functions similar to the --namespace option.
--set ceph_image
Defines the name of the Ceph Storage container image. Usually,this is rhceph-2-rhel7.
--set ceph_tag
Defines the tag to use for the Ceph Storage container image. This functions similar to the --tag option.

The following snippet is an example that includes Ceph Storage in your container image files:

$ openstack overcloud container image prepare \
  ...
  -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml \
  --set ceph_namespace=registry.access.redhat.com/rhceph \
  --set ceph_image=rhceph-2-rhel7 \
  --set ceph_tag=<CEPH_TAG>
  ...

OpenStack Bare Metal (ironic)

If deploying OpenStack Bare Metal (ironic) in your overcloud, you need to include the /usr/share/openstack-tripleo-heat-templates/environments/services-docker/ironic.yaml environment file so the director can prepare the images. The following snippet is an example on how to include this environment file:

$ openstack overcloud container image prepare \
  ...
  -e /usr/share/openstack-tripleo-heat-templates/environments/services-docker/ironic.yaml \
  ...

OpenStack Data Processing (sahara)

If deploying OpenStack Data Processing (sahara) in your overcloud, you need to include the /usr/share/openstack-tripleo-heat-templates/environments/services-docker/sahara.yaml environment file so the director can prepare the images. The following snippet is an example on how to include this environment file:

$ openstack overcloud container image prepare \
  ...
  -e /usr/share/openstack-tripleo-heat-templates/environments/services-docker/sahara.yaml \
  ...

5.3. Configuring the Overcloud to Use a Remote Registry

Red Hat hosts the overcloud container images on registry.access.redhat.com. Pulling the images from a remote registry is the simplest method because the registry is already setup and all you require is the URL and namespace of the image you aim to pull. However, during overcloud creation, the overcloud nodes all pull images from the remote repository, which can congest your external connection. If that is a problem, you can either:

To pull the images directly from registry.access.redhat.com in your overcloud deployment, an environment file is required to specify the image parameters. The following commands automatically create this environment file:

  1. Discover the tag for the latest images:

    $ source ~/stackrc
    (undercloud) $ sudo openstack overcloud container image tag discover \
      --image registry.access.redhat.com/rhosp12/openstack-base:latest \
      --tag-from-label version-release

    The result from this command is used below for the value of <TAG>

  2. Create the environment file:

    (undercloud) $ openstack overcloud container image prepare \
      --namespace=registry.access.redhat.com/rhosp12 \
      --prefix=openstack- \
      --tag=<TAG> \
      --output-env-file=/home/stack/templates/overcloud_images.yaml

    Use the -e option to include any environment files for optional services. See Section 5.2, “Adding Container Images for Additional Services” in Section 5.1, “Using the Container Image Preparation Command”.

    If using Ceph Storage, include the additional parameters from Ceph Storage in Section 5.1, “Using the Container Image Preparation Command”.

  3. This creates an overcloud_images.yaml environment file, which contains image locations, on the undercloud. You include this file with your deployment.

The registry configuration is ready. Continue with the instructions in Chapter 6, Configuring a Basic Overcloud with the CLI Tools.

5.4. Configuring the Overcloud to Use the Undercloud as a Local Registry

You can configure a local registry on the undercloud to store overcloud container images. This method involves the following:

  • The director pulls each image from the registry.access.redhat.com.
  • The director creates the overcloud.
  • During the overcloud creation, the nodes pull the relevant images from the undercloud.

This keeps network traffic for container images within your internal network, which does not congest your external network connection and can speed the deployment process.

To pull the images from registry.access.redhat.com to our local registry, use the following process:

  1. Discover the tag for the latest images:

    $ source ~/stackrc
    (undercloud) $ sudo openstack overcloud container image tag discover \
      --image registry.access.redhat.com/rhosp12/openstack-base:latest \
      --tag-from-label version-release

    The result from this command is used below for the value of <TAG>.

  2. Create a template to pull the images to the local registry:

    (undercloud) $ openstack overcloud container image prepare \
      --namespace=registry.access.redhat.com/rhosp12 \
      --prefix=openstack- \
      --tag=<TAG> \
      --output-images-file /home/stack/local_registry_images.yaml

    Use the -e option to include any environment files for optional services. See Section 5.2, “Adding Container Images for Additional Services” in Section 5.1, “Using the Container Image Preparation Command”.

    If using Ceph Storage, include the additional parameters from Ceph Storage in Section 5.1, “Using the Container Image Preparation Command”.

    Note

    This version of the openstack overcloud container image prepare command targets the registry on the registry.access.redhat.com to generate an image list to import into the undercloud. It uses different values than the openstack overcloud container image prepare command used in a later step.

  3. This creates a file called local_registry_images.yaml with your container image information. Pull the images using the local_registry_images.yaml file:

    (undercloud) $ sudo openstack overcloud container image upload \
      --config-file  /home/stack/local_registry_images.yaml \
      --verbose

    Pulling the required images might take some time depending on the speed of your network and your undercloud disk.

    Note

    The container images consume approximately 10 GB of disk space.

  4. Find the namespace of the local images. The namespace uses the following pattern:

    <REGISTRY IP ADDRESS>:8787/rhosp12

    Use the IP address of your undercloud, which you previously set with the local_ip parameter in your undercloud.conf file. Alternatively, you can also obtain the full namespace with the following command:

    (undercloud) $ docker images | grep -v redhat.com | grep -o '^.*rhosp12' | sort -u
  5. Create a template for using the images in our local registry on the undercloud. For example:

    (undercloud) $ openstack overcloud container image prepare \
      --namespace=192.168.24.1:8787/rhosp12 \
      --prefix=openstack- \
      --tag=<TAG> \
      --output-env-file=/home/stack/templates/overcloud_images.yaml

    Use the -e option to include any environment files for optional services. See Section 5.2, “Adding Container Images for Additional Services” in Section 5.1, “Using the Container Image Preparation Command”.

    If using Ceph Storage, include the additional parameters from Ceph Storage in Section 5.1, “Using the Container Image Preparation Command”.

    Note

    This version of the openstack overcloud container image prepare command targets the registry on the undercloud and generates a list of images to use for the overcloud. It uses different values than the openstack overcloud container image prepare command used in a previous step.

  6. This creates an overcloud_images.yaml environment file, which contains image locations on the undercloud. You include this file with your deployment.

The registry configuration is ready. Continue with the instructions in Chapter 6, Configuring a Basic Overcloud with the CLI Tools.

5.5. Configuring a Satellite Server as an Image Registry

Warning

A known issue exists in Red Hat Satellite 6 that prevents synchronizing container images with names longer than 30 characters. A fix for the issue will be available in an upcoming minor release of Satellite 6.2. A hotfix for this issue is currently available (see BZ#1424689 for more information).

Red Hat Satellite 6 offers registry synchronization capabilities. This provides a method to pull multiple images into a Satellite server and manage them as part of an application life cycle. The Satellite also acts as a registry for other container-enabled systems to use. For more details information on managing container images, see "Managing Container Images" in the Red Hat Satellite 6 Content Management Guide.

The examples in this procedure use the hammer command line tool for Red Hat Satellite 6 and an example organization called ACME. Substitute this organization for your own Satellite 6 organization.

To pull the images from registry.access.redhat.com to our local registry, use the following process:

  1. Create a template to pull images to the local registry:

    $ source ~/stackrc
    (undercloud) $ openstack overcloud container image prepare \
      --namespace=rhosp12 \
      --prefix=openstack- \
      --output-images-file /home/stack/satellite_images \

    Use the -e option to include any environment files for optional services. See Section 5.2, “Adding Container Images for Additional Services” in Section 5.1, “Using the Container Image Preparation Command”.

    If using Ceph Storage, include the additional parameters from Ceph Storage in Section 5.1, “Using the Container Image Preparation Command”.

    Note

    This version of the openstack overcloud container image prepare command targets the registry on the registry.access.redhat.com to generate an image list. It uses different values than the openstack overcloud container image prepare command used in a later step.

  2. This creates a file called satellite_images with your container image information. You will use this file to synchronize container images to your Satellite 6 server.
  3. Remove the YAML-specific information from the satellite_images file and convert it into a flat file containing only the list of images. The following sed commands accomplish this:

    (undercloud) $ sed -i "s/- imagename: //g" ~/satellite_images
    (undercloud) $ sed -i "s/:.*//g" ~/satellite_images
    (undercloud) $ sed -i "1d" ~/satellite_images

    This provides a list of images that you pull into the Satellite server.

  4. Copy the satellite_images file to a system that contains the Satellite 6 hammer tool. Alternatively, use the instructions in the Hammer CLI Guide to install the hammer tool to the undercloud.
  5. Run the following hammer command to create a new product (OSP12 Containers) to your Satellite organization:

    $ hammer product create \
      --organization "ACME" \
      --name "OSP12 Containers"

    This custom product will contain our images.

  6. Add the base container image to the product:

    $ hammer repository create \
      --organization "ACME" \
      --product "OSP12 Containers" \
      --content-type docker \
      --url https://registry.access.redhat.com \
      --docker-upstream-name rhosp12/openstack-base \
      --name base
  7. Add the overcloud container images from the satellite_images file.

    $ while read IMAGE; do \
      IMAGENAME=$(echo $IMAGE | cut -d"/" -f2 | sed "s/openstack-//g" | sed "s/:.*//g") ; \
      hammer repository create \
      --organization "ACME" \
      --product "OSP12 Containers" \
      --content-type docker \
      --url https://registry.access.redhat.com \
      --docker-upstream-name $IMAGE \
      --name $IMAGENAME ; done < satellite_images
  8. synchronize the container images:

    $ hammer product synchronize \
      --organization "ACME" \
      --name "OSP12 Containers"

    Wait for the Satellite server to complete synchronization.

    Note

    Depending on your configuration, hammer might ask for your Satellite server username and password. You can configure hammer to automatically login using a configuration file. See the "Authentication" section in the Hammer CLI Guide.

  9. Check the tags available for the base image:

    $ hammer docker tag list --repository "base" \
      --organization "ACME" \
      --product "OSP12 Containers"

    This displays tags for the OpenStack Platform container images. Select a tag and note it for a later step.

  10. Return to the undercloud and generate an environment file for the images on your Satellite server. This uses the following data:

    • --namespace - The URL and port of the registry on the Satellite server. The default registry port on Red Hat Satellite is 5000. For example, --namespace=satellite6.example.com:5000.
    • --prefix= - The prefix is based on the Satellite 6 organization and product name that hosts the containers. For example, if your organization name is ACME, the prefix would be acme-osp12_containers-.
    • --tag=<TAG> - The OpenStack Platform container image tag you noted earlier.
    • -e - Use this option to include each environment file for additional services for your overcloud. See Section 5.2, “Adding Container Images for Additional Services” in Section 5.1, “Using the Container Image Preparation Command” for more information.

      The following is an example command for generating the environment file:

      (undercloud) $ openstack overcloud container image prepare \
        --namespace=satellite6.example.com:5000 \
        --prefix=acme-osp12_containers- \
        --tag=<TAG> \
        --output-env-file=/home/stack/templates/overcloud_images.yaml

      Use the following additional parameters if using Ceph Storage:

    • --set ceph_namespace - The URL and port of the registry on the Satellite server for the Ceph Storage image. This should be the same as --namespace.
    • --set ceph_image - The name of the Ceph Storage image on the Satellite server. This follows the same convention as the OpenStack Platform images. For example: acme-osp12_containers-rhceph-2-rhel7.
    • --set ceph_tag - The Ceph Storage container image tag. Set to latest.

      See Ceph Storage in Section 5.1, “Using the Container Image Preparation Command” for more information.

      Note

      This version of the openstack overcloud container image prepare command targets the Satellite server. It uses different values than the openstack overcloud container image prepare command used in a previous step.

  11. This creates an overcloud_images.yaml environment file, which contains the image locations on the Satellite server. You include this file with your deployment.

The registry configuration is ready. Continue with the instructions in Chapter 6, Configuring a Basic Overcloud with the CLI Tools.



[1] Except for Openstack Networking (neutron), OpenStack Block Storage (cinder), and OpenStack Shared File System (manila). These services are not deployed in containers for Red Hat OpenStack Platform 12 by default. Containers are available for these services as a technology preview.