Disconnected environments

Procedure

1. Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
2. Select the architecture from the Product Variant drop-down list.
3. Select the appropriate version from the Version drop-down list.
4. Click Download Now next to the OpenShift v4.17 Linux Client entry and save the file.

5. Unpack the archive:

   $ tar xvf <file>

6. Place the oc binary in a directory that is on your PATH.

   To check your PATH, execute the following command:

   $ echo $PATH

Procedure

1. Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
2. Select the appropriate version from the Version drop-down list.
3. Click Download Now next to the OpenShift v4.17 Windows Client entry and save the file.
4. Unzip the archive with a ZIP program.

5. 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

Procedure

1. Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
2. Select the appropriate version from the Version drop-down list.

3. Click Download Now next to the OpenShift v4.17 macOS Client entry and save the file.

   Note

   For macOS arm64, choose the OpenShift v4.17 macOS arm64 Client entry.

4. Unpack and unzip the archive.

5. Move the oc binary to a directory on your PATH.

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

   $ echo $PATH

1. Create an image set configuration file.

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

   • Mirror an image set directly to the target 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. Configure your cluster to use the resources generated by the oc-mirror plugin.
4. Repeat these steps to update your target mirror registry as necessary.

Procedure

1. Download the oc-mirror CLI plugin.

   1. Navigate to the Downloads page of the OpenShift Cluster Manager.
   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 plugin file to be executable:

   $ chmod +x oc-mirror

   Note

   Do not rename the oc-mirror file.

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

   $ sudo mv oc-mirror /usr/local/bin/.

1. Download your registry.redhat.io pull secret from 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.

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

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

1. 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.

2. 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

   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

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

Procedure

1. Download the oc-mirror CLI plugin.

   1. Navigate to the Downloads page of the OpenShift Cluster Manager.
   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 plugin file to be executable:

   $ chmod +x oc-mirror

   Note

   Do not rename the oc-mirror file.

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

   $ sudo mv oc-mirror /usr/local/bin/.

1. Download your registry.redhat.io pull secret from 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.

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

3. Save the file as $XDG_RUNTIME_DIR/containers/auth.json.

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

   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

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

Verification

1. Navigate to the cluster-resources directory within the working-dir directory that was generated in the <file_path> directory.
2. Verify that the YAML files are present for the ImageDigestMirrorSet, ImageTagMirrorSet and CatalogSource resources.

1. Mirror to disk: Prepare an archive containing the image set for mirroring. Internet access is required.
2. Manual step: Transfer the archive to the network of the disconnected mirror registry.
3. Disk to mirror: To mirror the image set from the archive to the target disconnected registry, run oc-mirror plugin v2 from the environment that has access to the mirror registry.

Verification

1. Verify that the ImageDigestMirrorSet resources are successfully installed by running the following command:

   $ oc get imagedigestmirrorset

2. Verify that the ImageTagMirrorSet resources are successfully installed by running the following command:

   $ oc get imagetagmirrorset

3. Verify that the CatalogSource resources are successfully installed by running the following command:

   $ oc get catalogsource -n openshift-marketplace

Procedure

1. Create a YAML file that deletes previous images:

   $ oc mirror delete --config delete-image-set-config.yaml --workspace file://<previously_mirrored_work_folder> --v2 --generate docker://<remote_registry>

   Where:

   • <previously_mirrored_work_folder>: Use the directory where images were previously mirrored or stored during the mirroring process.
   • <remote_registry>: Insert the URL or address of the remote container registry from which images will be deleted.
2. Go to the <previously_mirrored_work_folder>/delete directory that was created.
3. Verify that the delete-images.yaml file has been generated.
4. Manually ensure that each image listed in the file is no longer needed by the cluster and can be safely removed from the registry.

5. After you generate the delete YAML file, delete the images from the remote registry:

   $ oc mirror delete --v2 --delete-yaml-file <previously_mirrored_work_folder>/delete/delete-images.yaml docker:/ <remote_registry>

   Where:

   • <previously_mirrored_work_folder>: Specify your previously mirrored work folder.

     Important

     When using the mirror-to-mirror procedure, images are not cached locally, so you cannot delete images from a local cache.

Verification

1. Navigate to the workspace directory that was generated:

   $ cd <oc_mirror_workspace_path>

2. Review the mapping.txt and missing.txt files that were generated. These files contain a list of all images that would be mirrored.

Procedure

1. Check for server-related issues:

   Example error

   [ERROR]  : [Worker] error mirroring image localhost:55000/openshift/graph-image:latest error: copying image 1/4 from manifest list: trying to reuse blob sha256:edab65b863aead24e3ed77cea194b6562143049a9307cd48f86b542db9eecb6e at destination: pinging container registry localhost:5000: Get "https://localhost:5000/v2/": http: server gave HTTP response to HTTPS client

   1. Open the mirroring_error_date_time.log file in the working-dir/logs folder located in the oc-mirror plugin v2 output directory.
   2. Look for error messages that typically indicate server-side issues, such as HTTP 500 errors, expired tokens, or timeouts.
   3. Retry the mirroring process or contact support if the issue persists.

2. Check for incomplete mirroring of Operators:

   Example error

   error mirroring image docker://registry.redhat.io/3scale-amp2/zync-rhel9@sha256:8bb6b31e108d67476cc62622f20ff8db34efae5d58014de9502336fcc479d86d (Operator bundles: [3scale-operator.v0.11.12] - Operators: [3scale-operator]) error: initializing source docker://localhost:55000/3scale-amp2/zync-rhel9:8bb6b31e108d67476cc62622f20ff8db34efae5d58014de9502336fcc479d86d: reading manifest 8bb6b31e108d67476cc62622f20ff8db34efae5d58014de9502336fcc479d86d in localhost:55000/3scale-amp2/zync-rhel9: manifest unknown
   error mirroring image docker://registry.redhat.io/3scale-amp2/3scale-rhel7-operator-metadata@sha256:de0a70d1263a6a596d28bf376158056631afd0b6159865008a7263a8e9bf0c7d error: skipping operator bundle docker://registry.redhat.io/3scale-amp2/3scale-rhel7-operator-metadata@sha256:de0a70d1263a6a596d28bf376158056631afd0b6159865008a7263a8e9bf0c7d because one of its related images failed to mirror
   error mirroring image docker://registry.redhat.io/3scale-amp2/system-rhel7@sha256:fe77272021867cc6b6d5d0c9bd06c99d4024ad53f1ab94ec0ab69d0fda74588e (Operator bundles: [3scale-operator.v0.11.12] - Operators: [3scale-operator]) error: initializing source docker://localhost:55000/3scale-amp2/system-rhel7:fe77272021867cc6b6d5d0c9bd06c99d4024ad53f1ab94ec0ab69d0fda74588e: reading manifest fe77272021867cc6b6d5d0c9bd06c99d4024ad53f1ab94ec0ab69d0fda74588e in localhost:55000/3scale-amp2/system-rhel7: manifest unknown

   1. Check for warnings in the console or log file indicating which Operators are incomplete.

      If an Operator is flagged as incomplete, the image related to that Operator likely failed to mirror.

   2. Manually mirror the missing image or retry the mirroring process.

3. Check for errors related to generated cluster resources. Even if some images fail to mirror, oc-mirror v2 will still generate cluster resources such as IDMS.yaml and ITMS.yaml files for the successfully mirrored images.

   1. Check the output directory for the generated files.
   2. If these files are missing for specific images, ensure that no critical errors occurred for those images during the mirroring process.

1. The user executes oc-mirror plugin v2 to mirror content from an online registry to a local disk directory.
2. The mirrored content is saved to the disk for transfer to offline environments.

Procedure

1. Before running oc-mirror plugin v2 in the disconnected environment, create a registries.conf file. The TOML format of the file is described in this specification:

   Note

   It is recommended to store the file under $HOME/.config/containers/registries.conf or /etc/containers/registries.conf.

   Example registries.conf

   [[registry]]
   location="registry.redhat.io"
   [[registry.mirror]]
   location="<enterprise-registry.in>"
   
   [[registry]]
   location="quay.io"
   [[registry.mirror]]
   location="<enterprise-registry.in>"

2. Generate a mirror archive.

   1. To collect all the OpenShift Container Platform content into an archive on the disk under <file_path>/enterprise-content, run the following command:

      $ oc mirror --v2 -c isc.yaml file://<file_path>/enterprise-content

      Example of isc.yaml

      apiVersion: mirror.openshift.io/v2alpha1
      kind: ImageSetConfiguration
      mirror:
        platform:
          architectures:
            - "amd64"
          channels:
            - name: stable-4.15
              minVersion: 4.15.0
              maxVersion: 4.15.3

      After the archive is generated, it is transferred to the disconnected environment. The transport mechanism is not part of oc-mirror plugin v2. The enterprise network administrators determine the transfer strategy.

      In some cases, the transfer is done manually, in that the disk is physically unplugged from one location, and plugged to another computer in the disconnected environment. In other cases, the Secure File Transfer Protocol (SFTP) or other protocols are used.

3. After the transfer of the archive is done, you can execute oc-mirror plugin v2 again in order to mirror the relevant archive contents to the registry (entrerpise_registry.in in the example) as demonstrated in the following example:

   $ oc mirror --v2 -c isc.yaml --from file://<disconnected_environment_file_path>/enterprise-content docker://<enterprise_registry.in>/

   Where:

   • --from points to the folder containing the archive. It starts with the file://.
   • docker:// is the destination of the mirroring is the final argument. Because it is a docker registry.
   • -c (--config) is a mandatory argument. It enables oc-mirror plugin v2 to eventually mirror only sub-parts of the archive to the registry. One archive might contain several OpenShift Container Platform releases, but the disconnected environment or an enclave might mirror only a few.

4. Prepare the imageSetConfig YAML file, which describes the content to mirror to the enclave:

   Example isc-enclave.yaml

   apiVersion: mirror.openshift.io/v2alpha1
   kind: ImageSetConfiguration
   mirror:
     platform:
       architectures:
         - "amd64"
       channels:
         - name: stable-4.15
           minVersion: 4.15.2
           maxVersion: 4.15.2

   You must run oc-mirror plugin v2 on a machine with access to the disconnected registry. In the previous example, the disconnected environment, enterprise-registry.in, is accessible.

5. Update the graph URL

   If you are using graph:true, oc-mirror plugin v2 attempts to reach the cincinnati API endpoint. Because this environment is disconnected, be sure to export the environment variable UPDATE_URL_OVERRIDE to refer to the URL for the OpenShift Update Service (OSUS):

   $ export UPDATE_URL_OVERRIDE=https://<osus.enterprise.in>/graph

   For more information on setting up OSUS on an OpenShift cluster, see "Updating a cluster in a disconnected environment using the OpenShift Update Service".

1. Generate a mirror archive from the enterprise registry for the enclave.

   To prepare an archive for the enclave1, the user executes oc-mirror plugin v2 in the enterprise disconnected environment by using the imageSetConfiguration specific for that enclave. This ensures that only images needed by that enclave are mirrored:

   $ oc mirror --v2 -c isc-enclave.yaml
   file:///disk-enc1/

   This action collects all the OpenShift Container Platform content into an archive and generates an archive on disk.

2. After the archive is generated, it will be transferred to the enclave1 network. The transport mechanism is not the responsibility of oc-mirror plugin v2.

3. Mirror contents to the enclave registry

   After the transfer of the archive is done, the user can execute oc-mirror plugin v2 again in order to mirror the relevant archive contents to the registry.

   $ oc mirror --v2 -c isc-enclave.yaml --from file://local-disk docker://registry.enc1.in

   The administrators of the OpenShift Container Platform cluster in enclave1 are now ready to install or upgrade that cluster.

Procedure

1. 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.

2. 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, and 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> 1

      1

      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> 1

      1

      Specify the full path, including the initial forward slash (/) character.

3. 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

4. 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} 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 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> 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

        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}

Procedure

1. In the web console, click Operators → OperatorHub.

   Note

   Enter Update Service into the Filter by keyword…​ field to find the Operator faster.

2. Choose OpenShift Update Service from the list of available Operators, and click Install.

   1. Select an Update channel.
   2. Select a Version.
   3. Select A specific namespace on the cluster under Installation Mode.
   4. Select a namespace for Installed Namespace or accept the recommended namespace openshift-update-service.

   5. Select an Update approval strategy:

      • The Automatic strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available.
      • The Manual strategy requires a cluster administrator to approve the Operator update.
   6. Click Install.
3. Go to Operators → Installed Operators and verify that the OpenShift Update Service Operator is installed.
4. Ensure that OpenShift Update Service is listed in the correct namespace with a Status of Succeeded.

Procedure

1. Create a namespace for the OpenShift Update Service Operator:

   1. Create a Namespace object YAML file, for example, update-service-namespace.yaml, for the OpenShift Update Service Operator:

      apiVersion: v1
      kind: Namespace
      metadata:
        name: openshift-update-service
        annotations:
          openshift.io/node-selector: ""
        labels:
          openshift.io/cluster-monitoring: "true" 1

      1

      Set the openshift.io/cluster-monitoring label to enable Operator-recommended cluster monitoring on this namespace.

   2. Create the namespace:

      $ oc create -f <filename>.yaml

      For example:

      $ oc create -f update-service-namespace.yaml

2. Install the OpenShift Update Service Operator by creating the following objects:

   1. Create an OperatorGroup object YAML file, for example, update-service-operator-group.yaml:

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: update-service-operator-group
        namespace: openshift-update-service
      spec:
        targetNamespaces:
        - openshift-update-service

   2. Create an OperatorGroup object:

      $ oc -n openshift-update-service create -f <filename>.yaml

      For example:

      $ oc -n openshift-update-service create -f update-service-operator-group.yaml

   3. Create a Subscription object YAML file, for example, update-service-subscription.yaml:

      Example Subscription

      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: update-service-subscription
        namespace: openshift-update-service
      spec:
        channel: v1
        installPlanApproval: "Automatic"
        source: "redhat-operators" 1
        sourceNamespace: "openshift-marketplace"
        name: "cincinnati-operator"

      1

      Specify the name of the catalog source that provides the Operator. For clusters that do not use a custom Operator Lifecycle Manager (OLM), specify redhat-operators. If your OpenShift Container Platform cluster is installed in a disconnected environment, specify the name of the CatalogSource object created when you configured Operator Lifecycle Manager (OLM).

   4. Create the Subscription object:

      $ oc create -f <filename>.yaml

      For example:

      $ oc -n openshift-update-service create -f update-service-subscription.yaml

      The OpenShift Update Service Operator is installed to the openshift-update-service namespace and targets the openshift-update-service namespace.

3. Verify the Operator installation:

   $ oc -n openshift-update-service get clusterserviceversions

   Example output

   NAME                             DISPLAY                    VERSION   REPLACES   PHASE
   update-service-operator.v4.6.0   OpenShift Update Service   4.6.0                Succeeded
   ...

   If the OpenShift Update Service Operator is listed, the installation was successful. The version number might be different than shown.

Procedure

1. In the web console, click Operators → Installed Operators.
2. Choose OpenShift Update Service from the list of installed Operators.
3. Click the Update Service tab.
4. Click Create UpdateService.
5. Enter a name in the Name field, for example, service.
6. Enter the local pullspec in the Graph Data Image field to the graph data container image created in "Creating the OpenShift Update Service graph data container image", for example, registry.example.com/openshift/graph-data:latest.
7. In the Releases field, enter the registry and repository created to contain the release images in "Mirroring the OpenShift Container Platform image repository", for example, registry.example.com/ocp4/openshift4-release-images.
8. Enter 2 in the Replicas field.
9. Click Create to create the OpenShift Update Service application.

10. Verify the OpenShift Update Service application:

    • From the UpdateServices list in the Update Service tab, click the Update Service application just created.
    • Click the Resources tab.
    • Verify each application resource has a status of Created.

Procedure

1. Configure the OpenShift Update Service target namespace, for example, openshift-update-service:

   $ NAMESPACE=openshift-update-service

   The namespace must match the targetNamespaces value from the operator group.

2. Configure the name of the OpenShift Update Service application, for example, service:

   $ NAME=service

3. Configure the registry and repository for the release images as configured in "Mirroring the OpenShift Container Platform image repository", for example, registry.example.com/ocp4/openshift4-release-images:

   $ RELEASE_IMAGES=registry.example.com/ocp4/openshift4-release-images

4. Set the local pullspec for the graph data image to the graph data container image created in "Creating the OpenShift Update Service graph data container image", for example, registry.example.com/openshift/graph-data:latest:

   $ GRAPH_DATA_IMAGE=registry.example.com/openshift/graph-data:latest

5. Create an OpenShift Update Service application object:

   $ oc -n "${NAMESPACE}" create -f - <<EOF
   apiVersion: updateservice.operator.openshift.io/v1
   kind: UpdateService
   metadata:
     name: ${NAME}
   spec:
     replicas: 2
     releases: ${RELEASE_IMAGES}
     graphDataImage: ${GRAPH_DATA_IMAGE}
   EOF

6. Verify the OpenShift Update Service application:

   1. Use the following command to obtain a policy engine route:

      $ while sleep 1; do POLICY_ENGINE_GRAPH_URI="$(oc -n "${NAMESPACE}" get -o jsonpath='{.status.policyEngineURI}/api/upgrades_info/v1/graph{"\n"}' updateservice "${NAME}")"; SCHEME="${POLICY_ENGINE_GRAPH_URI%%:*}"; if test "${SCHEME}" = http -o "${SCHEME}" = https; then break; fi; done

      You might need to poll until the command succeeds.

   2. Retrieve a graph from the policy engine. Be sure to specify a valid version for channel. For example, if running in OpenShift Container Platform 4.17, use stable-4.17:

      $ while sleep 10; do HTTP_CODE="$(curl --header Accept:application/json --output /dev/stderr --write-out "%{http_code}" "${POLICY_ENGINE_GRAPH_URI}?channel=stable-4.6")"; if test "${HTTP_CODE}" -eq 200; then break; fi; echo "${HTTP_CODE}"; done

      This polls until the graph request succeeds; however, the resulting graph might be empty depending on which release images you have mirrored.

Procedure

1. Configure mirrored repositories, by either:

   • Setting up a mirrored repository with Red Hat Quay, as described in Red Hat Quay Repository Mirroring. Using Red Hat Quay allows you to copy images from one repository to another and also automatically sync those repositories repeatedly over time.

   • Using a tool such as skopeo to copy images manually from the source repository to the mirrored repository.

     For example, after installing the skopeo RPM package on a Red Hat Enterprise Linux (RHEL) 7 or RHEL 8 system, use the skopeo command as shown in this example:

     $ skopeo copy --all \
     docker://registry.access.redhat.com/ubi9/ubi-minimal:latest@sha256:5cf... \
     docker://example.io/example/ubi-minimal

     In this example, you have a container image registry that is named example.io with an image repository named example to which you want to copy the ubi9/ubi-minimal image from registry.access.redhat.com. After you create the mirrored registry, you can configure your OpenShift Container Platform cluster to redirect requests made of the source repository to the mirrored repository.

2. Create a postinstallation mirror configuration CR, by using one of the following examples:

   • Create an ImageDigestMirrorSet or ImageTagMirrorSet CR, as needed, replacing the source and mirrors with your own registry and repository pairs and images:

     apiVersion: config.openshift.io/v1 1
     kind: ImageDigestMirrorSet 2
     metadata:
       name: ubi9repo
     spec:
       imageDigestMirrors: 3
       - mirrors:
         - example.io/example/ubi-minimal 4
         - example.com/example/ubi-minimal 5
         source: registry.access.redhat.com/ubi9/ubi-minimal 6
         mirrorSourcePolicy: AllowContactingSource 7
       - mirrors:
         - mirror.example.com/redhat
         source: registry.example.com/redhat 8
         mirrorSourcePolicy: AllowContactingSource
       - mirrors:
         - mirror.example.com
         source: registry.example.com 9
         mirrorSourcePolicy: AllowContactingSource
       - mirrors:
         - mirror.example.net/image
         source: registry.example.com/example/myimage 10
         mirrorSourcePolicy: AllowContactingSource
       - mirrors:
         - mirror.example.net
         source: registry.example.com/example 11
         mirrorSourcePolicy: AllowContactingSource
       - mirrors:
         - mirror.example.net/registry-example-com
         source: registry.example.com 12
         mirrorSourcePolicy: AllowContactingSource

     1

     Indicates the API to use with this CR. This must be config.openshift.io/v1.

     2

     Indicates the kind of object according to the pull type:

     • ImageDigestMirrorSet: Pulls a digest reference image.
     • ImageTagMirrorSet: Pulls a tag reference image.

     3

     Indicates the type of image pull method, either:

     • imageDigestMirrors: Use for an ImageDigestMirrorSet CR.
     • imageTagMirrors: Use for an ImageTagMirrorSet CR.

     4

     Indicates the name of the mirrored image registry and repository.

     5

     Optional: Indicates a secondary mirror repository for each target repository. If one mirror is down, the target repository can use the secondary mirror.

     6

     Indicates the registry and repository source, which is the repository that is referred to in an image pull specification.

     7

     Optional: Indicates the fallback policy if the image pull fails:

     • AllowContactingSource: Allows continued attempts to pull the image from the source repository. This is the default.
     • NeverContactSource: Prevents continued attempts to pull the image from the source repository.

     8

     Optional: Indicates a namespace inside a registry, which allows you to use any image in that namespace. If you use a registry domain as a source, the object is applied to all repositories from the registry.

     9

     Optional: Indicates a registry, which allows you to use any image in that registry. If you specify a registry name, the object is applied to all repositories from a source registry to a mirror registry.

     10

     Pulls the image registry.example.com/example/myimage@sha256:…​ from the mirror mirror.example.net/image@sha256:...

     11

     Pulls the image registry.example.com/example/image@sha256:…​ in the source registry namespace from the mirror mirror.example.net/image@sha256:…​.

     12

     Pulls the image registry.example.com/myimage@sha256 from the mirror registry example.net/registry-example-com/myimage@sha256:…​.

   • Create an ImageContentSourcePolicy custom resource, replacing the source and mirrors with your own registry and repository pairs and images:

     apiVersion: operator.openshift.io/v1alpha1
     kind: ImageContentSourcePolicy
     metadata:
       name: mirror-ocp
     spec:
       repositoryDigestMirrors:
       - mirrors:
         - mirror.registry.com:443/ocp/release 1
         source: quay.io/openshift-release-dev/ocp-release 2
       - mirrors:
         - mirror.registry.com:443/ocp/release
         source: quay.io/openshift-release-dev/ocp-v4.0-art-dev

     1

     Specifies the name of the mirror image registry and repository.

     2

     Specifies the online registry and repository containing the content that is mirrored.

3. Create the new object:

   $ oc create -f registryrepomirror.yaml

   After the object is created, the Machine Config Operator (MCO) drains the nodes for ImageTagMirrorSet objects only. The MCO does not drain the nodes for ImageDigestMirrorSet and ImageContentSourcePolicy objects.

4. To check that the mirrored configuration settings are applied, do the following on one of the nodes.

   1. List your nodes:

      $ oc get node

      Example output

      NAME                           STATUS                     ROLES    AGE  VERSION
      ip-10-0-137-44.ec2.internal    Ready                      worker   7m   v1.30.3
      ip-10-0-138-148.ec2.internal   Ready                      master   11m  v1.30.3
      ip-10-0-139-122.ec2.internal   Ready                      master   11m  v1.30.3
      ip-10-0-147-35.ec2.internal    Ready                      worker   7m   v1.30.3
      ip-10-0-153-12.ec2.internal    Ready                      worker   7m   v1.30.3
      ip-10-0-154-10.ec2.internal    Ready                      master   11m  v1.30.3

   2. Start the debugging process to access the node:

      $ oc debug node/ip-10-0-147-35.ec2.internal

      Example output

      Starting pod/ip-10-0-147-35ec2internal-debug ...
      To use host binaries, run `chroot /host`

   3. Change your root directory to /host:

      sh-4.2# chroot /host

   4. Check the /etc/containers/registries.conf file to make sure the changes were made:

      sh-4.2# cat /etc/containers/registries.conf

      The following output represents a registries.conf file where postinstallation mirror configuration CRs were applied. The final two entries are marked digest-only and tag-only respectively.

      Example output

      unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
      short-name-mode = ""
      
      [[registry]]
        prefix = ""
        location = "registry.access.redhat.com/ubi9/ubi-minimal" 1
      
        [[registry.mirror]]
          location = "example.io/example/ubi-minimal" 2
          pull-from-mirror = "digest-only" 3
      
        [[registry.mirror]]
          location = "example.com/example/ubi-minimal"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com"
      
        [[registry.mirror]]
          location = "mirror.example.net/registry-example-com"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com/example"
      
        [[registry.mirror]]
          location = "mirror.example.net"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com/example/myimage"
      
        [[registry.mirror]]
          location = "mirror.example.net/image"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com"
      
        [[registry.mirror]]
          location = "mirror.example.com"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com/redhat"
      
        [[registry.mirror]]
          location = "mirror.example.com/redhat"
          pull-from-mirror = "digest-only"
      [[registry]]
        prefix = ""
        location = "registry.access.redhat.com/ubi9/ubi-minimal"
        blocked = true 4
      
        [[registry.mirror]]
          location = "example.io/example/ubi-minimal-tag"
          pull-from-mirror = "tag-only" 5

      1

      Indicates the repository that is referred to in a pull spec.

      2

      Indicates the mirror for that repository.

      3

      Indicates that the image pull from the mirror is a digest reference image.

      4

      Indicates that the NeverContactSource parameter is set for this repository.

      5

      Indicates that the image pull from the mirror is a tag reference image.

   5. Pull an image to the node from the source and check if it is resolved by the mirror.

      sh-4.2# podman pull --log-level=debug registry.access.redhat.com/ubi9/ubi-minimal@sha256:5cf...

Procedure

1. Use the following command to convert one or more ImageContentSourcePolicy YAML files to an ImageDigestMirrorSet YAML file:

   $ oc adm migrate icsp <file_name>.yaml <file_name>.yaml <file_name>.yaml --dest-dir <path_to_the_directory>

   where:

   <file_name>

   Specifies the name of the source ImageContentSourcePolicy YAML. You can list multiple file names.

   --dest-dir

   Optional: Specifies a directory for the output ImageDigestMirrorSet YAML. If unset, the file is written to the current directory.

   For example, the following command converts the icsp.yaml and icsp-2.yaml file and saves the new YAML files to the idms-files directory.

   $ oc adm migrate icsp icsp.yaml icsp-2.yaml --dest-dir idms-files

   Example output

   wrote ImageDigestMirrorSet to idms-files/imagedigestmirrorset_ubi8repo.5911620242173376087.yaml
   wrote ImageDigestMirrorSet to idms-files/imagedigestmirrorset_ubi9repo.6456931852378115011.yaml

2. Create the CR object by running the following command:

   $ oc create -f <path_to_the_directory>/<file-name>.yaml

   where:

   <path_to_the_directory>

   Specifies the path to the directory, if you used the --dest-dir flag.

   <file_name>

   Specifies the name of the ImageDigestMirrorSet YAML.

3. Remove the ICSP objects after the IDMS objects are rolled out.