OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Updating a cluster in a disconnected environment using the OpenShift Update Service

Using the OpenShift Update Service in a disconnected environment

The OpenShift Update Service (OSUS) provides update recommendations to OpenShift Container Platform clusters. Red Hat publicly hosts the OpenShift Update Service, and clusters in a connected environment can connect to the service through public APIs to retrieve update recommendations.

However, clusters in a disconnected environment cannot access these public APIs to retrieve update information. To have a similar update experience in a disconnected environment, you can install and configure the OpenShift Update Service locally so that it is available within the disconnected environment.

A single OSUS instance is capable of serving recommendations to thousands of clusters. OSUS can be scaled horizontally to cater to more clusters by changing the replica value. So for most disconnected use cases, one OSUS instance is enough. For example, Red Hat hosts just one OSUS instance for the entire fleet of connected clusters.

If you want to keep update recommendations separate in different environments, you can run one OSUS instance for each environment. For example, in a case where you have separate test and stage environments, you might not want a cluster in a stage environment to receive update recommendations to version A if that version has not been tested in the test environment yet.

The following sections describe how to install a local OSUS instance and configure it to provide update recommendations to a cluster.

Additional resources

Prerequisites

Configuring access to a secured registry for the OpenShift Update Service

If the release images are contained in a registry whose HTTPS X.509 certificate is signed by a custom certificate authority, 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

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

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

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

  2. 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 disconnected environments, 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

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

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

  3. Verify that the OpenShift Update Service Operator is installed by switching to the Operators → Installed Operators page.

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

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

Additional resources

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

  1. 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://api.openshift.com/api/upgrades_info/graph-data

RUN mkdir -p /var/lib/cincinnati-graph-data && tar xvzf cincinnati-graph-data.tar.gz -C /var/lib/cincinnati-graph-data/ --no-overwrite-dir --no-same-owner

CMD ["/bin/bash", "-c" ,"exec cp -rp /var/lib/cincinnati-graph-data/* /var/lib/cincinnati/graph-data"]

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

  3. 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 disconnected environment, 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.

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

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

  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.

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

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

  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.10, use stable-4.10:

      $ 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

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

    $ NAMESPACE=openshift-update-service

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

    $ NAME=service

  3. 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}")"

  4. Set the patch for the pull graph data:

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

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

Next steps

Before updating your cluster, confirm that the following conditions are met:

  • The Cluster Version Operator (CVO) is configured to use your locally-installed OpenShift Update Service application.

  • The release image signature config map for the new release is applied to your cluster.

    The release image signature config map allows the Cluster Version Operator (CVO) to ensure the integrity of release images by verifying that the actual image signatures match the expected signatures.

  • The current release and update target release images are mirrored to a locally accessible registry.

  • A recent graph data container image has been mirrored to your local registry.

After you configure your cluster to use the locally-installed OpenShift Update Service and local mirror registry, you can use any of the following update methods: