Mirroring OpenShift Container Platform images¶

You must mirror container images onto a mirror registry to update a cluster in a disconnected environment. In connected environments, mirroring images ensures that your clusters run only approved container images that meet your organizational controls for external content.

Note

Your mirror registry must be running at all times while the cluster is running.

The following steps outline the high-level workflow about mirroring images to a mirror registry:

Install the OpenShift CLI (oc) on all devices that you use to retrieve and push release images.
Download the registry pull secret and add it to your cluster.
Choose the appropriate method to mirror your images:
1. Method 1: If you use the oc-mirror OpenShift CLI (oc) plugin:
  1. Install the oc-mirror plugin on all devices that you use to retrieve and push release images.
  2. Create an image set configuration file for the plugin to use when determining which release images to mirror. You can edit this configuration file later to change which release images that the plugin mirrors.
  3. Mirror your targeted release images directly to a mirror registry, or to removable media and then to a mirror registry.
  4. Configure your cluster to use the resources generated by the oc-mirror plugin.
  5. Repeat these steps as needed to update your mirror registry.
2. Method 2: If you use the oc adm release mirror command:
  1. Set environment variables that correspond to your environment and the release images you want to mirror.
  2. Mirror your targeted release images directly to a mirror registry, or to removable media and then to a mirror registry.
  3. Repeat these steps as needed to update your mirror registry.

Warning

The oc adm release mirror command is deprecated as of OpenShift Container Platform 4.22 and will be removed in a future release.

As an alternative, use the oc-mirror plugin v2.

The oc-mirror plugin offers the following advantages over the oc adm release mirror command:

Mirrors content other than container images.
Simplifies updating images in the registry after the initial mirror.
Automates mirroring the release payload from Quay and builds the latest graph data image for the OpenShift Update Service in disconnected environments.

Mirroring resources using the oc-mirror plugin¶

You can use the oc-mirror OpenShift CLI (oc) plugin to mirror images to a mirror registry in your fully or partially disconnected environments. You must run oc-mirror from a system with internet connectivity to download the required images from the official Red Hat registries.

For more information, see "Mirroring images for a disconnected installation by using the oc-mirror plugin v2".

Additional resources

Mirroring images for a disconnected installation by using the oc-mirror plugin v2

Mirroring images using the oc adm release mirror command¶

You can use the oc adm release mirror command to mirror images to your mirror registry.

Warning

The oc adm release mirror command is deprecated as of OpenShift Container Platform 4.22 and will be removed in a future release.

As an alternative, use the oc-mirror plugin v2.

The requirements for a mirror registry are:

You must have a container image registry that supports Docker v2-2 in the location that will host the OpenShift Container Platform cluster, such as Red Hat Quay.

Note

If you use Red Hat Quay, you must use version 3.6 or later with the oc-mirror plugin. If you have an entitlement to Red Hat Quay, see the documentation on "Deploying Red Hat Quay for proof-of-concept purposes" or "Deploying Red Hat Quay by using the Quay Operator". If you need additional information about selecting and installing a registry, contact your sales representative or Red Hat Support.
If you do not have an existing solution for a container image registry, see the "Mirror registry for Red Hat OpenShift" in OpenShift Container Platform subscriptions. The mirror registry for Red Hat OpenShift is a small-scale container registry that you can use to mirror OpenShift Container Platform container images in disconnected installations and updates.

Additional resources

Preparing your mirror host¶

Before you perform the mirror procedure, you must prepare the host to retrieve content and push it to the remote location.

Installing the OpenShift CLI on Linux¶

To manage your cluster and deploy applications from the command line on Linux, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

Warning

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform.

Download and install the new version of oc. If you are updating a cluster in a disconnected environment, install the oc version that you plan to update to.

Procedure

Navigate to the Download OpenShift Container Platform page on the Red Hat Customer Portal.
Select the architecture from the Product Variant list.
Select the appropriate version from the Version list.
Click Download Now next to the OpenShift v4.22 Linux Clients entry and save the file.
Unpack the archive:
```
$ tar xvf <file>
```
Place the oc binary in a directory that is on your PATH.

To check your PATH, run the following command:
```
$ echo $PATH
```

Verification

After you install the OpenShift CLI, it is available using the oc command:
```
$ oc <command>
```

Installing the OpenShift CLI on Windows¶

To manage your cluster and deploy applications from the command line on Windows, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

Warning

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform.

Download and install the new version of oc. If you are updating a cluster in a disconnected environment, install the oc version that you plan to update to.

Procedure

Navigate to the Download OpenShift Container Platform page on the Red Hat Customer Portal.
Select the appropriate version from the Version list.
Click Download Now next to the OpenShift v4.22 Windows Client entry and save the file.
Extract the archive with a ZIP program.
Move the oc binary to a directory that is on your PATH variable.

To check your PATH variable, open the Command Prompt and run the following command:
```
C:\> path
```

Verification

After you install the OpenShift CLI, it is available using the oc command:
```
C:\> oc <command>
```

Installing the OpenShift CLI on macOS¶

To manage your cluster and deploy applications from the command line on macOS, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

Warning

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform.

Download and install the new version of oc. If you are updating a cluster in a disconnected environment, install the oc version that you plan to update to.

Procedure

Navigate to the Download OpenShift Container Platform page on the Red Hat Customer Portal.
Select the architecture from the Product Variant list.
Select the appropriate version from the Version list.
Click Download Now next to the OpenShift v4.22 macOS Clients entry and save the file.

Note

For macOS arm64, choose the OpenShift v4.22 macOS arm64 Client entry.
Extract the archive.
Move the oc binary to a directory on your PATH variable.

To check your PATH variable, open a terminal and run the following command:
```
$ echo $PATH
```

Verification

Verify your installation by using an oc command:
```
$ oc <command>
```

Additional resources

Installing and using CLI plugins

Configuring credentials that allow images to be mirrored¶

Create a container image registry credentials file so that you can mirror images from Red Hat to your mirror. Complete the following steps on the installation host.

Warning

Do not use this image registry credentials file as the pull secret when you install a cluster. If you provide this file when you install cluster, all of the machines in the cluster will have write access to your mirror registry.

Prerequisites

You configured a mirror registry to use in your disconnected environment.
You identified an image repository location on your mirror registry to mirror images into.
You provisioned a mirror registry account that allows images to be uploaded to that image repository.
You have write access to the mirror registry.

Procedure

Download your registry.redhat.io pull secret from Red Hat OpenShift Cluster Manager.

Make a copy of your pull secret in JSON format by running the following command:

$ cat ./pull-secret | jq . > <path>/<pull_secret_file_in_json>

Specify the path to the directory to store the pull secret in and a name for the JSON file that you create.

Example pull secret

{
  "auths": {
    "cloud.openshift.com": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "quay.io": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "registry.connect.redhat.com": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    },
    "registry.redhat.io": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    }
  }
}

Optional: If using the oc-mirror plugin, save the file as either ~/.docker/config.json or $XDG_RUNTIME_DIR/containers/auth.json:
- If the .docker or $XDG_RUNTIME_DIR/containers directories do not exist, create one by entering the following command:
```
$ mkdir -p <directory_name>
```
  Where <directory_name> is either ~/.docker or $XDG_RUNTIME_DIR/containers.
- Copy the pull secret to the appropriate directory by entering the following command:
```
$ cp <path>/<pull_secret_file_in_json> <directory_name>/<auth_file>
```
  Where <directory_name> is either ~/.docker or $XDG_RUNTIME_DIR/containers, and <auth_file> is either config.json or auth.json.
Generate the base64-encoded user name and password or token for your mirror registry by running the following command:
```
$ echo -n '<user_name>:<password>' | base64 -w0
```
For <user_name> and <password>, specify the user name and password that you configured for your registry.
Example output
```
BGVtbYk3ZHAtqXs=
```

Edit the JSON file and add a section that describes your registry to it:

  "auths": {
    "<mirror_registry>": {
      "auth": "<credentials>",
      "email": "you@example.com"
    }
  },

For the <mirror_registry> value, specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, registry.example.com or registry.example.com:8443.

For the <credentials> value, specify the base64-encoded user name and password for the mirror registry.

Example modified pull secret

{
  "auths": {
    "registry.example.com": {
      "auth": "BGVtbYk3ZHAtqXs=",
      "email": "you@example.com"
    },
    "cloud.openshift.com": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "quay.io": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "registry.connect.redhat.com": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    },
    "registry.redhat.io": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    }
  }
}

Mirroring images to a mirror registry¶

Before you can update a cluster in a disconnected environment, you must mirror the required OpenShift Container Platform release images onto a local registry mirror.

Warning

To avoid excessive memory usage by the OpenShift Update Service application, you must mirror release images to a separate repository as described in the following procedure.

Prerequisites

You configured a mirror registry to use in your disconnected environment and can access the certificate and credentials that you configured.
You downloaded the pull secret from Red Hat OpenShift Cluster Manager and modified it to include authentication to your mirror repository.
If you use self-signed certificates, you have specified a Subject Alternative Name in the certificates.

Procedure

Use the Red Hat OpenShift Container Platform Update Graph visualizer and update planner to plan an update from one version to another. The OpenShift Update Graph provides channel graphs and a way to confirm that there is an update path between your current and intended cluster versions.
Set the required environment variables:
1. Export the release version:
```
$ export OCP_RELEASE=<release_version>
```
  For <release_version>, specify the tag that corresponds to the version of OpenShift Container Platform to which you want to update, such as 4.5.4.
2. Export the local registry name and host port:
```
$ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>'
```
  - For <local_registry_host_name>, specify the registry domain name for your mirror repository.
  - For <local_registry_host_port>, specify the port that it serves content on.
3. Export the local repository name:
```
$ LOCAL_REPOSITORY='<local_repository_name>'
```
  For <local_repository_name>, specify the name of the repository to create in your registry, such as ocp4/openshift4.
4. If you are using the OpenShift Update Service, export an additional local repository name to contain the release images:
```
$ LOCAL_RELEASE_IMAGES_REPOSITORY='<local_release_images_repository_name>'
```
  For <local_release_images_repository_name>, specify the name of the repository to create in your registry, such as ocp4/openshift4-release-images.
5. Export the name of the repository to mirror:
```
$ PRODUCT_REPO='openshift-release-dev'
```
  For a production release, you must specify openshift-release-dev.
6. Export the path to your registry pull secret:
```
$ LOCAL_SECRET_JSON='<path_to_pull_secret>'
```
  For <path_to_pull_secret>, specify the absolute path to and file name of the pull secret for your mirror registry that you created.
  
  Note
  
  If your cluster uses an ImageContentSourcePolicy object to configure repository mirroring, you can use only global pull secrets for mirrored registries. You cannot add a pull secret to a project.
7. Export the release mirror:
```
$ RELEASE_NAME="ocp-release"
```
  For a production release, you must specify ocp-release.
8. Export the type of architecture for your cluster:
```
$ ARCHITECTURE=<cluster_architecture>
```
  For <cluster_architecture>, specify the architecture of the cluster, such as x86_64, aarch64, s390x, or ppc64le.
9. Export the path to the directory to host the mirrored images:
```
$ REMOVABLE_MEDIA_PATH=<path>
```
  For <path>, specify the full path, including the initial forward slash (/) character.

Review the images and configuration manifests to mirror:

$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run

Mirror the version images to the mirror registry.
- If your mirror host does not have internet access, take the following actions:
  1. Connect the removable media to a system that is connected to the internet.
  2. Mirror the images and configuration manifests to a directory on the removable media:
```
$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
```
    Note
    
    This command also generates and saves the mirrored release image signature config map onto the removable media.
  3. Take the media to the disconnected environment and upload the images to the local container registry.
```
$ oc image mirror  -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
```
    For REMOVABLE_MEDIA_PATH, you must use the same path that you specified when you mirrored the images.
  4. Use oc command-line interface (CLI) to log in to the cluster that you are updating.
  5. Apply the mirrored release image signature config map to the connected cluster:
```
$ oc apply -f ${REMOVABLE_MEDIA_PATH}/mirror/config/<image_signature_file>
```
    For <image_signature_file>, specify the path and name of the file, for example, signature-sha256-81154f5c03294534.yaml.
  6. If you are using the OpenShift Update Service, mirror the release image to a separate repository:
```
$ oc image mirror -a ${LOCAL_SECRET_JSON} ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} ${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
```
- If the local container registry and the cluster are connected to the mirror host, take the following actions:
  1. Directly push the release images to the local registry and apply the config map to the cluster by using following command:
```
$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
  --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} --apply-release-image-signature
```
    Note
    
    If you include the --apply-release-image-signature option, do not create the config map for image signature verification.
  2. If you are using the OpenShift Update Service, mirror the release image to a separate repository:
```
$ oc image mirror -a ${LOCAL_SECRET_JSON} ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} ${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
```