Updating a restricted network cluster | Updating clusters | OpenShift Container Platform Branch Build

Updating a restricted network cluster using the CLI
Additional resources
Updating a restricted network cluster using the OpenShift Update Service

You can update a restricted network OpenShift Container Platform cluster by using the oc command-line interface (CLI) or using the OpenShift Update Service.

Updating a restricted network cluster using the CLI

You can update a restricted network OpenShift Container Platform cluster by using the oc command-line interface (CLI).

A restricted network environment is the one in which your cluster nodes cannot access the internet. For this reason, you must populate a registry with the installation images. If your registry host cannot access both the internet and the cluster, you can mirror the images to a file system that disconnected from that environment and then bring that host or removable media across that gap. If the local container registry and the cluster are connected to the mirror registry’s host, you can directly push the release images to the local registry.

If multiple clusters are present within the restricted network, mirror the required release images to a single container image registry and use that registry to update all the clusters.

Prerequisites

Have access to the internet to obtain the necessary container images.
Have write access to a container registry in the restricted-network environment to push and pull images. The container registry must be compatible with Docker registry API v2.
You must have the oc command-line interface (CLI) tool installed.
Have access to the cluster as a user with admin privileges. See Using RBAC to define and apply permissions.
Have a recent etcd backup in case your update fails and you must restore your cluster to a previous state.
Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy.
If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see Upgrading clusters with manually maintained credentials for AWS, Azure, or GCP.
If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the upgrade process. If minAvailable is set to 1 in PodDisruptionBudget, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the PodDisruptionBudget field can prevent the node drain.

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 Branch Build. Download and install the new version of oc. If you are upgrading a cluster in a restricted network, 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 vBranch Build Linux Client entry and save the file.
Unpack the archive:
```
$ tar xvzf <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 vBranch Build 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 vBranch Build 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 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:

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

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

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.

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": "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 the OpenShift Container Platform image repository

Before you update a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. You can also use this procedure in unrestricted networks to ensure your clusters only use container images that have satisfied your organizational controls on external content.

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.
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 restricted network 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.
- If the local container registry and the cluster are connected to the mirror host, 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.

Pausing a MachineHealthCheck resource

During the upgrade process, nodes in the cluster might become temporarily unavailable. In the case of worker nodes, the machine health check might identify such nodes as unhealthy and reboot them. To avoid rebooting such nodes, pause all the MachineHealthCheck resources before updating the cluster.

Prerequisites

Install the OpenShift CLI (oc).

Procedure

To list all the available MachineHealthCheck resources that you want to pause, run the following command:
```
$ oc get machinehealthcheck -n openshift-machine-api
```

To pause the machine health checks, add the cluster.x-k8s.io/paused="" annotation to the MachineHealthCheck resource. Run the following command:

$ oc -n openshift-machine-api annotate mhc <mhc-name> cluster.x-k8s.io/paused=""

The annotated MachineHealthCheck resource resembles the following YAML file:

apiVersion: machine.openshift.io/v1beta1
kind: MachineHealthCheck
metadata:
  name: example
  namespace: openshift-machine-api
  annotations:
    cluster.x-k8s.io/paused: ""
spec:
  selector:
    matchLabels:
      role: worker
  unhealthyConditions:
  - type:    "Ready"
    status:  "Unknown"
    timeout: "300s"
  - type:    "Ready"
    status:  "False"
    timeout: "300s"
  maxUnhealthy: "40%"
status:
  currentHealthy: 5
  expectedMachines: 5

Resume the machine health checks after updating the cluster. To resume the check, remove the pause annotation from the MachineHealthCheck resource by running the following command:

$ oc -n openshift-machine-api annotate mhc <mhc-name> cluster.x-k8s.io/paused-

Upgrading the restricted network cluster

Update the restricted network cluster to the OpenShift Container Platform version that you downloaded the release images for.

If you have a local OpenShift Update Service, you can update by using the connected web console or CLI instructions instead of this procedure.

Prerequisites

You mirrored the images for the new release to your registry.
You applied the release image signature ConfigMap for the new release to your cluster.
You obtained the sha256 sum value for the release from the image signature ConfigMap.
Install the OpenShift CLI (oc).
Pause all MachineHealthCheck resources.

Procedure

Update the cluster:
```
$ oc adm upgrade --allow-explicit-upgrade --to-image ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}<sha256_sum_value> (1)
```
1 The <sha256_sum_value> value is the sha256 sum value for the release from the image signature ConfigMap, for example, @sha256:81154f5c03294534e1eaf0319bef7a601134f891689ccede5d705ef659aa8c92

If you use an ImageContentSourcePolicy for the mirror registry, you can use the canonical registry name instead of LOCAL_REGISTRY.

You can only configure global pull secrets for clusters that have an ImageContentSourcePolicy object. You cannot add a pull secret to a project.

Configuring image registry repository mirroring

Setting up container registry repository mirroring enables you to do the following:

Configure your OpenShift Container Platform cluster to redirect requests to pull images from a repository on a source image registry and have it resolved by a repository on a mirrored image registry.
Identify multiple mirrored repositories for each target repository, to make sure that if one mirror is down, another can be used.

The attributes of repository mirroring in OpenShift Container Platform include:

Image pulls are resilient to registry downtimes.
Clusters in restricted networks can pull images from critical locations, such as quay.io, and have registries behind a company firewall provide the requested images.
A particular order of registries is tried when an image pull request is made, with the permanent registry typically being the last one tried.
The mirror information you enter is added to the /etc/containers/registries.conf file on every node in the OpenShift Container Platform cluster.
When a node makes a request for an image from the source repository, it tries each mirrored repository in turn until it finds the requested content. If all mirrors fail, the cluster tries the source repository. If successful, the image is pulled to the node.

Setting up repository mirroring can be done in the following ways:

At OpenShift Container Platform installation:

By pulling container images needed by OpenShift Container Platform and then bringing those images behind your company’s firewall, you can install OpenShift Container Platform into a datacenter that is in a restricted network.
After OpenShift Container Platform installation:

Even if you don’t configure mirroring during OpenShift Container Platform installation, you can do so later using the ImageContentSourcePolicy object.

The following procedure provides a post-installation mirror configuration, where you create an ImageContentSourcePolicy object that identifies:

The source of the container image repository you want to mirror.
A separate entry for each mirror repository you want to offer the content requested from the source repository.

You can only configure global pull secrets for clusters that have an ImageContentSourcePolicy object. You cannot add a pull secret to a project.

Prerequisites

Access to the cluster as a user with the cluster-admin role.

Procedure

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 directory 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 \ docker://registry.access.redhat.com/ubi8/ubi-minimal@sha256:5cfbaf45ca96806917830c183e9f37df2e913b187adb32e89fd83fa455ebaa6 \ 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 ubi8/ubi-minimal image from registry.access.redhat.com. After you create the registry, you can configure your OpenShift Container Platform cluster to redirect requests made of the source repository to the mirrored repository.
Log in to your OpenShift Container Platform cluster.

Create an ImageContentSourcePolicy file (for example, registryrepomirror.yaml), replacing the source and mirrors with your own registry and repository pairs and images:

apiVersion: operator.openshift.io/v1alpha1
kind: ImageContentSourcePolicy
metadata:
  name: ubi8repo
spec:
  repositoryDigestMirrors:
  - mirrors:
    - example.io/example/ubi-minimal (1)
    - example.com/example/ubi-minimal (2)
    source: registry.access.redhat.com/ubi8/ubi-minimal (3)
  - mirrors:
    - mirror.example.com/redhat
    source: registry.redhat.io/openshift4 (4)
  - mirrors:
    - mirror.example.com
    source: registry.redhat.io (5)
  - mirrors:
    - mirror.example.net/image
    source: registry.example.com/example/myimage (6)
  - mirrors:
    - mirror.example.net
    source: registry.example.com/example (7)
  - mirrors:
    - mirror.example.net/registry-example-com
    source: registry.example.com (8)

1	Indicates the name of the image registry and repository.
2	Indicates multiple mirror repositories for each target repository. If one mirror is down, the target repository can use another mirror.
3	Indicates the registry and repository containing the content that is mirrored.
4	You can configure a namespace inside a registry to use any image in that namespace. If you use a registry domain as a source, the `ImageContentSourcePolicy` resource is applied to all repositories from the registry.
5	If you configure the registry name, the `ImageContentSourcePolicy` resource is applied to all repositories from a source registry to a mirror registry.
6	Pulls the image `mirror.example.net/image@sha256:…`.
7	Pulls the image `myimage` in the source registry namespace from the mirror `mirror.example.net/myimage@sha256:…`.
8	Pulls the image `registry.example.com/example/myimage` from the mirror registry `mirror.example.net/registry-example-com/example/myimage@sha256:…`. The `ImageContentSourcePolicy` resource is applied to all repositories from a source registry to a mirror registry `mirror.example.net/registry-example-com`.

Create the new ImageContentSourcePolicy object:
```
$ oc create -f registryrepomirror.yaml
```
After the ImageContentSourcePolicy object is created, the new settings are deployed to each node and the cluster starts using the mirrored repository for requests to the source repository.

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

List your nodes:

$ oc get node

Example output

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

The Imagecontentsourcepolicy resource does not restart the nodes.

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`

Change your root directory to /host:
```
sh-4.2# chroot /host
```

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

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

Example output

unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
short-name-mode = ""

[[registry]]
  prefix = ""
  location = "registry.access.redhat.com/ubi8/ubi-minimal"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "example.io/example/ubi-minimal"

  [[registry.mirror]]
    location = "example.com/example/ubi-minimal"

[[registry]]
  prefix = ""
  location = "registry.example.com"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "mirror.example.net/registry-example-com"

[[registry]]
  prefix = ""
  location = "registry.example.com/example"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "mirror.example.net"

[[registry]]
  prefix = ""
  location = "registry.example.com/example/myimage"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "mirror.example.net/image"

[[registry]]
  prefix = ""
  location = "registry.redhat.io"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "mirror.example.com"

[[registry]]
  prefix = ""
  location = "registry.redhat.io/openshift4"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "mirror.example.com/redhat"

Pull an image digest to the node from the source and check if it is resolved by the mirror. ImageContentSourcePolicy objects support image digests only, not image tags.
```
sh-4.2# podman pull --log-level=debug registry.access.redhat.com/ubi8/ubi-minimal@sha256:5cfbaf45ca96806917830c183e9f37df2e913b187adb32e89fd83fa455ebaa6
```

Troubleshooting repository mirroring

If the repository mirroring procedure does not work as described, use the following information about how repository mirroring works to help troubleshoot the problem.

The first working mirror is used to supply the pulled image.
The main registry is only used if no other mirror works.
From the system context, the Insecure flags are used as fallback.
The format of the /etc/containers/registries.conf file has changed recently. It is now version 2 and in TOML format.

Widening the scope of the mirror image catalog to reduce the frequency of cluster node reboots

You can scope the mirrored image catalog at the repository level or the wider registry level. A widely scoped ImageContentSourcePolicy resource reduces the number of times the nodes need to reboot in response to changes to the resource.

To widen the scope of the mirror image catalog in the ImageContentSourcePolicy resource, perform the following procedure.

Prerequisites

Install the OpenShift Container Platform CLI oc.
Log in as a user with cluster-admin privileges.
Configure a mirrored image catalog for use in your disconnected cluster.

Procedure

Run the following command, specifying values for <local_registry>, <pull_spec>, and <pull_secret_file>:
```
$ oc adm catalog mirror <local_registry>/<pull_spec> <local_registry> -a <pull_secret_file> --icsp-scope=registry
```
where:

<local_registry>

is the local registry you have configured for your disconnected cluster, for example, local.registry:5000.

<pull_spec>

is the pull specification as configured in your disconnected registry, for example, redhat/redhat-operator-index:vBranch Build

<pull_secret_file>

is the registry.redhat.io pull secret in .json file format. You can download the pull secret from the Red Hat OpenShift Cluster Manager.

The oc adm catalog mirror command creates a /redhat-operator-index-manifests directory and generates imageContentSourcePolicy.yaml, catalogSource.yaml, and mapping.txt files.
Apply the new ImageContentSourcePolicy resource to the cluster:
```
$ oc apply -f imageContentSourcePolicy.yaml
```

Verification

Verify that oc apply successfully applied the change to ImageContentSourcePolicy:

$ oc get ImageContentSourcePolicy -o yaml

Example output

apiVersion: v1
items:
- apiVersion: operator.openshift.io/v1alpha1
  kind: ImageContentSourcePolicy
  metadata:
    annotations:
      kubectl.kubernetes.io/last-applied-configuration: |
        {"apiVersion":"operator.openshift.io/v1alpha1","kind":"ImageContentSourcePolicy","metadata":{"annotations":{},"name":"redhat-operator-index"},"spec":{"repositoryDigestMirrors":[{"mirrors":["local.registry:5000"],"source":"registry.redhat.io"}]}}
...

After you update the ImageContentSourcePolicy resource, OpenShift Container Platform deploys the new settings to each node and the cluster starts using the mirrored repository for requests to the source repository.

Additional resources

Updating a restricted network cluster using the OpenShift Update Service

About the OpenShift Update Service

The OpenShift Update Service (OSUS) provides over-the-air updates to OpenShift Container Platform, including Red Hat Enterprise Linux CoreOS (RHCOS). It provides a graph, or diagram, that contains the vertices of component Operators and the edges that connect them. The edges in the graph show which versions you can safely update to. The vertices are update payloads that specify the intended state of the managed cluster components.

The Cluster Version Operator (CVO) in your cluster checks with the OpenShift Update Service to see the valid updates and update paths based on current component versions and information in the graph. When you request an update, the CVO uses the release image for that update to update your cluster. The release artifacts are hosted in Quay as container images.

To allow the OpenShift Update Service to provide only compatible updates, a release verification pipeline drives automation. Each release artifact is verified for compatibility with supported cloud platforms and system architectures, as well as other component packages. After the pipeline confirms the suitability of a release, the OpenShift Update Service notifies you that it is available.

The OpenShift Update Service displays all recommended updates for your current cluster. If an update path is not recommended by the OpenShift Update Service, it might be because of a known issue with the update or the target release.

Two controllers run during continuous update mode. The first controller continuously updates the payload manifests, applies the manifests to the cluster, and outputs the controlled rollout status of the Operators to indicate whether they are available, upgrading, or failed. The second controller polls the OpenShift Update Service to determine if updates are available.

Only upgrading to a newer version is supported. Reverting or rolling back your cluster to a previous version is not supported. If your update fails, contact Red Hat support.

During the update process, the Machine Config Operator (MCO) applies the new configuration to your cluster machines. The MCO cordons the number of nodes as specified by the maxUnavailable field on the machine configuration pool and marks them as unavailable. By default, this value is set to 1. The MCO then applies the new configuration and reboots the machine.

If you use Red Hat Enterprise Linux (RHEL) machines as workers, the MCO does not update the kubelet because you must update the OpenShift API on the machines first.

With the specification for the new version applied to the old kubelet, the RHEL machine cannot return to the Ready state. You cannot complete the update until the machines are available. However, the maximum number of unavailable nodes is set to ensure that normal cluster operations can continue with that number of machines out of service.

The OpenShift Update Service is composed of an Operator and one or more application instances.

Additional resources

Understanding upgrade channels and releases

For clusters with internet accessibility, Red Hat provides over-the-air updates through an OpenShift Container Platform update service as a hosted service located behind public APIs. However, clusters in a restricted network have no way to access public APIs for update information.

To provide a similar update experience in a restricted network, you can install and configure the OpenShift Update Service locally so that it is available within a disconnected environment.

The following sections describe how to provide over-the-air updates for your disconnected cluster and its underlying operating system.

Prerequisites

For more information on installing Operators, see Installing Operators in your namespace.

Configuring access to a secured registry for the OpenShift update service

If the release images are contained in a secure registry, complete the steps in Configuring additional trust stores for image registry access along with following changes for the update service.

The OpenShift Update Service Operator needs the config map key name updateservice-registry in the registry CA cert.

Image registry CA config map example for the update service

  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: my-registry-ca
  data:
    updateservice-registry: | (1)
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    registry-with-port.example.com..5000: | (2)
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----

1	The OpenShift Update Service Operator requires the config map key name updateservice-registry in the registry CA cert.
2	If the registry has the port, such as `registry-with-port.example.com:5000`, `:` should be replaced with `..`.

Updating the global cluster pull secret

You can update the global pull secret for your cluster by either replacing the current pull secret or appending a new pull secret.

The procedure is required when users use a separate registry to store images than the registry used during installation.

Prerequisites

You have access to the cluster as a user with the cluster-admin role.

Procedure

Optional: To append a new pull secret to the existing pull secret, complete the following steps:

Enter the following command to download the pull secret:

$ oc get secret/pull-secret -n openshift-config --template='{{index .data ".dockerconfigjson" | base64decode}}' ><pull_secret_location> (1)

1	Provide the path to the pull secret file.

Enter the following command to add the new pull secret:

$ oc registry login --registry="<registry>" \ (1)
--auth-basic="<username>:<password>" \ (2)
--to=<pull_secret_location> (3)

1	Provide the new registry. You can include multiple repositories within the same registry, for example: `--registry="<registry/my-namespace/my-repository>"`.
2	Provide the credentials of the new registry.
3	Provide the path to the pull secret file.

Alternatively, you can perform a manual update to the pull secret file.

Enter the following command to update the global pull secret for your cluster:
```
$ oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=<pull_secret_location> (1)
```
1 Provide the path to the new pull secret file.

This update is rolled out to all nodes, which can take some time depending on the size of your cluster.

As of OpenShift Container Platform 4.7.4, changes to the global pull secret no longer trigger a node drain or reboot.

Installing the OpenShift Update Service Operator

To install the OpenShift Update Service, you must first install the OpenShift Update Service Operator by using the OpenShift Container Platform web console or CLI.

For clusters that are installed on restricted networks, also known as disconnected clusters, Operator Lifecycle Manager by default cannot access the Red Hat-provided OperatorHub sources hosted on remote registries because those remote sources require full internet connectivity. For more information, see Using Operator Lifecycle Manager on restricted networks.

Installing the OpenShift Update Service Operator by using the web console

You can use the web console to install the OpenShift Update Service Operator.

Procedure

In the web console, click Operators → OperatorHub.

Enter Update Service into the Filter by keyword… field to find the Operator faster.
Choose OpenShift Update Service from the list of available Operators, and click Install.
1. Channel v1 is selected as the Update Channel since it is the only channel available in this release.
2. Select A specific namespace on the cluster under Installation Mode.
3. Select a namespace for Installed Namespace or accept the recommended namespace openshift-update-service.
4. Select an 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.
5. Click Install.
Verify that the OpenShift Update Service Operator is installed by switching to the Operators → Installed Operators page.
Ensure that OpenShift Update Service is listed in the selected namespace with a Status of Succeeded.

Installing the OpenShift Update Service Operator by using the CLI

You can use the OpenShift CLI (oc) to install the OpenShift Update Service Operator.

Procedure

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

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

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
spec:
  targetNamespaces:
  - openshift-update-service

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

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
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 on a restricted network, also known as a disconnected cluster, specify the name of the CatalogSource object created when you configured Operator Lifecycle Manager (OLM).

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.

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.

Creating the OpenShift Update Service graph data container image

The OpenShift Update Service requires a graph-data container image, from which the OpenShift Update Service retrieves information about channel membership and blocked update edges. Graph data is typically fetched directly from the upgrade graph data repository. In environments where an internet connection is unavailable, loading this information from an init container is another way to make the graph data available to the OpenShift Update Service. The role of the init container is to provide a local copy of the graph data, and during pod initialization, the init container copies the data to a volume that is accessible by the service.

Procedure

Create a Dockerfile, for example, ./Dockerfile, containing the following:

FROM registry.access.redhat.com/ubi8/ubi:8.1

RUN curl -L -o cincinnati-graph-data.tar.gz https://github.com/openshift/cincinnati-graph-data/archive/master.tar.gz

CMD exec /bin/bash -c "tar xvzf cincinnati-graph-data.tar.gz -C /var/lib/cincinnati/graph-data/ --strip-components=1"

Use the docker file created in the above step to build a graph-data container image, for example, registry.example.com/openshift/graph-data:latest:
```
$ podman build -f ./Dockerfile -t registry.example.com/openshift/graph-data:latest
```

Push the graph-data container image created in the previous step to a repository that is accessible to the OpenShift Update Service, for example, registry.example.com/openshift/graph-data:latest:

$ podman push registry.example.com/openshift/graph-data:latest

To push a graph data image to a local registry in a restricted network, copy the graph-data container image created in the previous step to a repository that is accessible to the OpenShift Update Service. Run oc image mirror --help for available options.

Mirroring the OpenShift Container Platform image repository

The OpenShift Update Service requires a locally accessible registry containing update release payloads.

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

Prerequisites

You reviewed and completed the steps from "Mirroring images for a disconnected installation" up to but not including the section entitled Mirroring the OpenShift Container Platform image repository.
You configured a mirror registry to use in your restricted network 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

Complete the following steps on the mirror host:

Review the OpenShift Container Platform downloads page to determine the version of OpenShift Container Platform to which you want to update and determine the corresponding tag on the Repository Tags page.
Set the required environment variables:
1. Export the release version:
  $ OCP_RELEASE=<release_version>
  For <release_version>, specify the tag that corresponds to the version of OpenShift Container Platform to install, such as 4.6.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. 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.
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 server, such as x86_64:
  $ ARCHITECTURE=<server_architecture>
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.

Mirror the version images to the mirror registry:

If your mirror host does not have internet access, take the following actions:

Connect the removable media to a system that is connected to the internet.

Review the images and configuration manifests to mirror:

$ oc adm release mirror -a ${LOCAL_SECRET_JSON}  \
     --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
     --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run

Mirror the images 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}

Take the media to the restricted network 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 path where you mounted the removable media.
Use oc command-line interface (CLI) to log in to the cluster that you are upgrading.
Apply the mirrored release image signature config map to the disconnected 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.

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 is connected to the mirror host, push the release images directly to the local registry:

$ oc adm release mirror -a ${LOCAL_SECRET_JSON}  \
     --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
     --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}

Creating an OpenShift Update Service application

You can create an OpenShift Update Service application by using the OpenShift Container Platform web console or CLI.

Creating an OpenShift Update Service application by using the web console

You can use the OpenShift Container Platform web console to create an OpenShift Update Service application by using the OpenShift Update Service Operator.

Prerequisites

The OpenShift Update Service Operator has been installed.
The OpenShift Update Service graph-data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
The current release and update target releases have been mirrored to a locally accessible registry.

Procedure

In the web console, click Operators → Installed Operators.
Choose OpenShift Update Service from the list of installed Operators.
Click the Update Service tab.
Click Create UpdateService.
Enter a name in the Name field, for example, service.
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.
In the Releases field, enter the local 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.
Enter 2 in the Replicas field.
Click Create to create the OpenShift Update Service application.
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.

Creating an OpenShift Update Service application by using the CLI

You can use the OpenShift CLI (oc) to create an OpenShift Update Service application.

Prerequisites

The OpenShift Update Service Operator has been installed.
The OpenShift Update Service graph-data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
The current release and update target releases have been mirrored to a locally accessible registry.

Procedure

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.
Configure the name of the OpenShift Update Service application, for example, service:
```
$ NAME=service
```
Configure the local 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
```
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
```

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

Verify the OpenShift Update Service application:

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.

Retrieve a graph from the policy engine. Be sure to specify a valid version for channel. For example, if running in OpenShift Container Platform Branch Build, use stable-Branch Build:
```
$ 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.

The policy engine route name must not be more than 63 characters based on RFC-1123. If you see ReconcileCompleted status as false with the reason CreateRouteFailed caused by host must conform to DNS 1123 naming convention and must be no more than 63 characters, try creating the Update Service with a shorter name.

Configuring the Cluster Version Operator (CVO)

After the OpenShift Update Service Operator has been installed and the OpenShift Update Service application has been created, the Cluster Version Operator (CVO) can be updated to pull graph data from the locally installed OpenShift Update Service.

Prerequisites

The OpenShift Update Service Operator has been installed.
The OpenShift Update Service graph-data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
The current release and update target releases have been mirrored to a locally accessible registry.
The OpenShift Update Service application has been created.

Procedure

Set the OpenShift Update Service target namespace, for example, openshift-update-service:
```
$ NAMESPACE=openshift-update-service
```
Set the name of the OpenShift Update Service application, for example, service:
```
$ NAME=service
```

Obtain the policy engine route:

$ POLICY_ENGINE_GRAPH_URI="$(oc -n "${NAMESPACE}" get -o jsonpath='{.status.policyEngineURI}/api/upgrades_info/v1/graph{"\n"}' updateservice "${NAME}")"

Set the patch for the pull graph data:

$ PATCH="{\"spec\":{\"upstream\":\"${POLICY_ENGINE_GRAPH_URI}\"}}"

Patch the CVO to use the local OpenShift Update Service:

$ oc patch clusterversion version -p $PATCH --type merge

See Enabling the cluster-wide proxy to configure the CA to trust the update server.

Deleting an OpenShift Update Service application

You can delete an OpenShift Update Service application by using the OpenShift Container Platform web console or CLI.

Deleting an OpenShift Update Service application by using the web console

You can use the OpenShift Container Platform web console to delete an OpenShift Update Service application by using the OpenShift Update Service Operator.

Prerequisites

The OpenShift Update Service Operator has been installed.

Procedure

In the web console, click Operators → Installed Operators.
Choose OpenShift Update Service from the list of installed Operators.
Click the Update Service tab.
From the list of installed OpenShift Update Service applications, select the application to be deleted and then click Delete UpdateService.
From the Delete UpdateService? confirmation dialog, click Delete to confirm the deletion.

Deleting an OpenShift Update Service application by using the CLI

You can use the OpenShift CLI (oc) to delete an OpenShift Update Service application.

Procedure

Get the OpenShift Update Service application name using the namespace the OpenShift Update Service application was created in, for example, openshift-update-service:
```
$ oc get updateservice -n openshift-update-service
```
Example output
```
NAME      AGE
service   6s
```
Delete the OpenShift Update Service application using the NAME value from the previous step and the namespace the OpenShift Update Service application was created in, for example, openshift-update-service:
```
$ oc delete updateservice service -n openshift-update-service
```
Example output
```
updateservice.updateservice.operator.openshift.io "service" deleted
```

Uninstalling the OpenShift Update Service Operator

To uninstall the OpenShift Update Service, you must first delete all OpenShift Update Service applications by using the OpenShift Container Platform web console or CLI.

Uninstalling the OpenShift Update Service Operator by using the web console

You can use the OpenShift Container Platform web console to uninstall the OpenShift Update Service Operator.

Prerequisites

All OpenShift Update Service applications have been deleted.

Procedure

In the web console, click Operators → Installed Operators.
Select OpenShift Update Service from the list of installed Operators and click Uninstall Operator.
From the Uninstall Operator? confirmation dialog, click Uninstall to confirm the uninstallation.

Uninstalling the OpenShift Update Service Operator by using the CLI

You can use the OpenShift CLI (oc) to uninstall the OpenShift Update Service Operator.

Prerequisites

All OpenShift Update Service applications have been deleted.

Procedure

Change to the project containing the OpenShift Update Service Operator, for example, openshift-update-service:
```
$ oc project openshift-update-service
```
Example output
```
Now using project "openshift-update-service" on server "https://example.com:6443".
```

Get the name of the OpenShift Update Service Operator operator group:

$ oc get operatorgroup

Example output

NAME                             AGE
openshift-update-service-fprx2   4m41s

Delete the operator group, for example, openshift-update-service-fprx2:

$ oc delete operatorgroup openshift-update-service-fprx2

Example output

operatorgroup.operators.coreos.com "openshift-update-service-fprx2" deleted

Get the name of the OpenShift Update Service Operator subscription:

$ oc get subscription

Example output

NAME                      PACKAGE                   SOURCE                        CHANNEL
update-service-operator   update-service-operator   updateservice-index-catalog   v1

Using the Name value from the previous step, check the current version of the subscribed OpenShift Update Service Operator in the currentCSV field:
```
$ oc get subscription update-service-operator -o yaml | grep " currentCSV"
```
Example output
```
  currentCSV: update-service-operator.v0.0.1
```

Delete the subscription, for example, update-service-operator:

$ oc delete subscription update-service-operator

Example output

subscription.operators.coreos.com "update-service-operator" deleted

Delete the CSV for the OpenShift Update Service Operator using the currentCSV value from the previous step:

$ oc delete clusterserviceversion update-service-operator.v0.0.1

Example output

clusterserviceversion.operators.coreos.com "update-service-operator.v0.0.1" deleted