Mirroring the OpenShift Container Platform image repository

Prerequisites
Preparing your mirror host
- Installing the OpenShift CLI by downloading the binary
- Configuring credentials that allow images to be mirrored
Mirroring the OpenShift Container Platform image repository

You must mirror container images onto a mirror registry before you can update a cluster in a disconnected environment. You can also use this procedure in connected environments to ensure your clusters run only approved container images that have satisfied your organizational controls for external content.

Prerequisites

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.

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 by downloading the binary

You can install the OpenShift CLI (oc) to interact with OpenShift Container Platform from a command-line interface. You can install oc on Linux, Windows, or macOS.

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform 4.9. Download and install the new version of oc. If you are upgrading a cluster in a disconnected environment, install the oc version that you plan to upgrade to.

Installing the OpenShift CLI on Linux

You can install the OpenShift CLI (oc) binary on Linux by using the following procedure.

Procedure

Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
Select the appropriate version in the Version drop-down menu.
Click Download Now next to the OpenShift v4.9 Linux Client 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, execute the following command:
```
$ echo $PATH
```

After you install the OpenShift CLI, it is available using the oc command:

$ oc <command>

Installing the OpenShift CLI on Windows

You can install the OpenShift CLI (oc) binary on Windows by using the following procedure.

Procedure

Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
Select the appropriate version in the Version drop-down menu.
Click Download Now next to the OpenShift v4.9 Windows Client entry and save the file.
Unzip the archive with a ZIP program.
Move the oc binary to a directory that is on your PATH.

To check your PATH, open the command prompt and execute the following command:
```
C:\> path
```

After you install the OpenShift CLI, it is available using the oc command:

C:\> oc <command>

Installing the OpenShift CLI on macOS

You can install the OpenShift CLI (oc) binary on macOS by using the following procedure.

Procedure

Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
Select the appropriate version in the Version drop-down menu.
Click Download Now next to the OpenShift v4.9 MacOSX Client entry and save the file.
Unpack and unzip the archive.
Move the oc binary to a directory on your PATH.

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

After you install the OpenShift CLI, it is available using the oc command:

$ oc <command>

Configuring credentials that allow images to be mirrored

Create a container image registry credentials file that allows mirroring images from Red Hat to your mirror.

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.

This process requires that you have write access to a container image registry on the mirror registry and adds the credentials to a registry pull secret.

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.

Procedure

Complete the following steps on the installation host:

Download your registry.redhat.io pull secret from the Red Hat OpenShift Cluster Manager and save it to a .json file.
Generate the base64-encoded user name and password or token for your mirror registry:
```
$ echo -n '<user_name>:<password>' | base64 -w0 (1)
BGVtbYk3ZHAtqXs=
```
1 For <user_name> and <password>, specify the user name and password that you configured for your registry.
Make a copy of your pull secret in JSON format:
```
$ cat ./pull-secret.text | jq .  > <path>/<pull_secret_file_in_json>(1)
```
1 Specify the path to the folder to store the pull secret in and a name for the JSON file that you create.

Save the file either as ~/.docker/config.json or $XDG_RUNTIME_DIR/containers/auth.json.

The contents of the file resemble the following example:

{
  "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"
    }
  }
}

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

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

1	For `<mirror_registry>`, 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`
2	For `<credentials>`, specify the base64-encoded user name and password for the mirror registry.

The file resembles the following example:

{
  "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"
    }
  }
}

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 the 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 Upgrade Graph visualizer and update planner to plan an update from one version to another. The OpenShift Upgrade 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:

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.
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, and for <local_registry_host_port>, specify the port that it serves content on.
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.
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.
Export the name of the repository to mirror:
```
$ PRODUCT_REPO='openshift-release-dev'
```
For a production release, you must specify openshift-release-dev.

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.

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.

Export the release mirror:
```
$ RELEASE_NAME="ocp-release"
```
For a production release, you must specify ocp-release.
Export the type of architecture for your server, such as x86_64.:
```
$ ARCHITECTURE=<server_architecture>
```
Export the path to the directory to host the mirrored images:
```
$ REMOVABLE_MEDIA_PATH=<path> (1)
```
1 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}
  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} (1)
    
    1 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 upgrading.
  5. Apply the mirrored release image signature config map to the connected cluster:
    
    $ oc apply -f ${REMOVABLE_MEDIA_PATH}/mirror/config/<image_signature_file> (1)
    
    1 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
    
    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}