×

Running your cluster in a restricted network without direct internet connectivity is possible by installing the cluster from a mirrored set of OpenShift Container Platform container images in a private registry. This registry must be running at all times as long as the cluster is running. See the Prerequisites section for more information.

You can use the oc-mirror OpenShift CLI (oc) plug-in 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 in order to download the required images from the official Red Hat registries.

The following steps outline the high-level workflow on how to use the oc-mirror plug-in to mirror images to a mirror registry:

  1. Create an image set configuration file.

  2. Mirror the image set to the mirror registry by using one of the following methods:

    • Mirror an image set directly to the mirror registry.

    • Mirror an image set to disk, transfer the image set to the target environment, then upload the image set to the target mirror registry.

  3. Install the ImageContentSourcePolicy and CatalogSource resources that were generated by oc-mirror into the cluster.

  4. Repeat these steps to update your mirror registry as necessary.

About the oc-mirror plug-in

You can use the oc-mirror OpenShift CLI (oc) plug-in to mirror all required OpenShift Container Platform content and other images to your mirror registry by using a single tool. It provides the following features:

  • Provides a centralized method to mirror OpenShift Container Platform releases, Operators, helm charts, and other images.

  • Maintains update paths for OpenShift Container Platform and Operators.

  • Uses a declarative image set configuration file to include only the OpenShift Container Platform releases, Operators, and images that your cluster needs.

  • Performs incremental mirroring, which reduces the size of future image sets.

  • Prunes images from the target mirror registry that were excluded from the image set configuration since the previous execution.

  • Optionally generates supporting artifacts for OpenShift Update Service (OSUS) usage.

When using the oc-mirror plug-in, you specify which content to mirror in an image set configuration file. In this YAML file, you can fine-tune the configuration to only include the OpenShift Container Platform releases and Operators that your cluster needs. This reduces the amount of data that you need to download and transfer. The oc-mirror plug-in can also mirror arbitrary helm charts and additional container images to assist users in seamlessly synchronizing their workloads onto mirror registries.

The first time you run the oc-mirror plug-in, it populates your mirror registry with the required content to perform your disconnected cluster installation. In order for your disconnected cluster to continue receiving updates, you must keep your mirror registry updated. To update your mirror registry, you run the oc-mirror plug-in using the same configuration as the first time you ran it. The oc-mirror plug-in references the metadata from the storage backend and only downloads what has been released since the last time you ran the tool. This provides update paths for OpenShift Container Platform and Operators and performs dependency resolution as required.

When using the oc-mirror CLI plug-in to populate a mirror registry, any further updates to the mirror registry must be made using the oc-mirror tool.

oc-mirror compatibility and support

The oc-mirror plug-in supports mirroring OpenShift Container Platform payload images and Operator catalogs for OpenShift Container Platform versions 4.9 and later.

Use the latest available version of the oc-mirror plug-in regardless of which versions of OpenShift Container Platform you need to mirror.

If you used the Technology Preview version of the oc-mirror plug-in for OpenShift Container Platform 4.10, it is not possible to migrate your mirror registry to OpenShift Container Platform 4.11. You must download the new oc-mirror plug-in, use a new storage back end, and use a new top-level namespace on the target mirror registry.

About the mirror registry

You can mirror the images that are required for OpenShift Container Platform installation and subsequent product updates to a container mirror registry that supports Docker v2-2, such as Red Hat Quay. If you do not have access to a large-scale container registry, you can use the mirror registry for Red Hat OpenShift, which is a small-scale container registry included with OpenShift Container Platform subscriptions.

Regardless of your chosen registry, the procedure to mirror content from Red Hat hosted sites on the internet to an isolated image registry is the same. After you mirror the content, you configure each cluster to retrieve this content from your mirror registry.

The internal registry of the OpenShift Container Platform cluster cannot be used as the target registry because it does not support pushing without a tag, which is required during the mirroring process.

If choosing a container registry that is not the mirror registry for Red Hat OpenShift, it must be reachable by every machine in the clusters that you provision. If the registry is unreachable, installation, updating, or normal operations such as workload relocation might fail. For that reason, you must run mirror registries in a highly available way, and the mirror registries must at least match the production availability of your OpenShift Container Platform clusters.

When you populate your mirror registry with OpenShift Container Platform images, you can follow two scenarios. If you have a host that can access both the internet and your mirror registry, but not your cluster nodes, you can directly mirror the content from that machine. This process is referred to as connected mirroring. If you have no such host, you must mirror the images to a file system and then bring that host or removable media into your restricted environment. This process is referred to as disconnected mirroring.

For mirrored registries, to view the source of pulled images, you must review the Trying to access log entry in the CRI-O logs. Other methods to view the image pull source, such as using the crictl images command on a node, show the non-mirrored image name, even though the image is pulled from the mirrored location.

Red Hat does not test third party registries with OpenShift Container Platform.

Additional resources

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.

    If you use Red Hat Quay, you must use version 3.6 or later with the oc-mirror plug-in. If you have an entitlement to Red Hat Quay, see the documentation on deploying Red Hat Quay for proof-of-concept purposes or by using the Quay Operator. If you need additional assistance selecting and installing a registry, contact your sales representative or Red Hat Support.

    If you do not already have an existing solution for a container image registry, subscribers of OpenShift Container Platform are provided a mirror registry for Red Hat OpenShift. The mirror registry for Red Hat OpenShift is included with your subscription and is a small-scale container registry that can be used to mirror the required container images of OpenShift Container Platform in disconnected installations.

Preparing your mirror hosts

Before you can use the oc-mirror plug-in to mirror images, you must install the plug-in and create a container image registry credentials file to allow the mirroring from Red Hat to your mirror.

Installing the oc-mirror OpenShift CLI plug-in

To use the oc-mirror OpenShift CLI plug-in to mirror registry images, you must install the plug-in. If you are mirroring image sets in a fully disconnected environment, ensure that you install the oc-mirror plug-in on the host with internet access and the host in the disconnected environment with access to the mirror registry.

Prerequisites
  • You have installed the OpenShift CLI (oc).

Procedure
  1. Download the oc-mirror CLI plug-in.

    1. Navigate to the Downloads page of the OpenShift Cluster Manager Hybrid Cloud Console.

    2. Under the OpenShift disconnected installation tools section, click Download for OpenShift Client (oc) mirror plugin and save the file.

  2. Extract the archive:

    $ tar xvzf oc-mirror.tar.gz
  3. If necessary, update the plug-in file to be executable:

    $ chmod +x oc-mirror

    Do not rename the oc-mirror file.

  4. Install the oc-mirror CLI plug-in by placing the file in your PATH, for example, /usr/local/bin:

    $ sudo mv oc-mirror /usr/local/bin/.
Verification
  • Run oc mirror help to verify that the plug-in was successfully installed:

    $ oc mirror help
Additional resources

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 restricted network.

  • 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:

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

  2. Make a copy of your pull secret in JSON format:

    $ cat ./pull-secret | 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.
  3. 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"
        }
      }
    }
  4. 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.
  5. Edit the JSON 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":