Updating clusters

Procedure

1. Obtain the OpenShift Container Platform release image by running the following command:

   $ RELEASE_IMAGE=$(./openshift-install version | awk '/release image/ {print $3}')

2. Obtain the CCO container image from the OpenShift Container Platform release image by running the following command:

   $ CCO_IMAGE=$(oc adm release info --image-for='cloud-credential-operator' $RELEASE_IMAGE -a ~/.pull-secret)

   Note

   Ensure that the architecture of the $RELEASE_IMAGE matches the architecture of the environment in which you will use the ccoctl tool.

3. Extract the ccoctl binary from the CCO container image within the OpenShift Container Platform release image by running the following command:

   $ oc image extract $CCO_IMAGE --file="/usr/bin/ccoctl" -a ~/.pull-secret

4. Change the permissions to make ccoctl executable by running the following command:

   $ chmod 775 ccoctl

Procedure

1. Extract the list of CredentialsRequest custom resources (CRs) from the OpenShift Container Platform release image by running the following command:

   $ oc adm release extract --credentials-requests \
     --cloud=<provider_type> \
     --to=<path_to_directory_with_list_of_credentials_requests>/credrequests \
     quay.io/<path_to>/ocp-release:<version>

   where:

   • <provider_type> is the value for your cloud provider. Valid values are alibabacloud, aws, gcp, ibmcloud, and nutanix.
   • credrequests is the directory where the list of CredentialsRequest objects is stored. This command creates the directory if it does not exist.

2. For each CredentialsRequest CR in the release image, ensure that a namespace that matches the text in the spec.secretRef.namespace field exists in the cluster. This field is where the generated secrets that hold the credentials configuration are stored.

   Sample AWS CredentialsRequest object

   apiVersion: cloudcredential.openshift.io/v1
   kind: CredentialsRequest
   metadata:
     name: cloud-credential-operator-iam-ro
     namespace: openshift-cloud-credential-operator
   spec:
     providerSpec:
       apiVersion: cloudcredential.openshift.io/v1
       kind: AWSProviderSpec
       statementEntries:
       - effect: Allow
         action:
         - iam:GetUser
         - iam:GetUserPolicy
         - iam:ListAccessKeys
         resource: "*"
     secretRef:
       name: cloud-credential-operator-iam-ro-creds
       namespace: openshift-cloud-credential-operator 1

   1

   This field indicates the namespace which needs to exist to hold the generated secret.

   The CredentialsRequest CRs for other platforms have a similar format with different platform-specific values.

3. For any CredentialsRequest CR for which the cluster does not already have a namespace with the name specified in spec.secretRef.namespace, create the namespace by running the following command:

   $ oc create namespace <component_namespace>

4. Use the ccoctl tool to process all CredentialsRequest objects in the credrequests directory by running the command for your cloud provider. The following commands process CredentialsRequest objects:

   • Alibaba Cloud: ccoctl alibabacloud create-ram-users
   • Amazon Web Services (AWS): ccoctl aws create-iam-roles
   • Google Cloud Platform (GCP): ccoctl gcp create-all
   • IBM Cloud: ccoctl ibmcloud create-service-id
   • Nutanix: ccoctl nutanix create-shared-secrets
   Important

   Refer to the ccoctl utility instructions in the installation content for your cloud provider for important platform-specific details about the required arguments and special considerations.

   For each CredentialsRequest object, ccoctl creates the required provider resources and a permissions policy as defined in each CredentialsRequest object from the OpenShift Container Platform release image.

5. Apply the secrets to your cluster by running the following command:

   $ ls <path_to_ccoctl_output_dir>/manifests/*-credentials.yaml | xargs -I{} oc apply -f {}

Procedure

1. Extract and examine the CredentialsRequest custom resource for the new release.

   The "Manually creating IAM" section of the installation content for your cloud provider explains how to obtain and use the credentials required for your cloud.

2. Update the manually maintained credentials on your cluster:

   • Create new secrets for any CredentialsRequest custom resources that are added by the new release image.
   • If the CredentialsRequest custom resources for any existing credentials that are stored in secrets have changed permissions requirements, update the permissions as required.

3. If your cluster uses cluster capabilities to disable one or more optional components, delete the CredentialsRequest custom resources for any disabled components.

   Example credrequests directory contents for OpenShift Container Platform 4.12 on AWS

   0000_30_machine-api-operator_00_credentials-request.yaml 1
   0000_50_cloud-credential-operator_05-iam-ro-credentialsrequest.yaml 2
   0000_50_cluster-image-registry-operator_01-registry-credentials-request.yaml 3
   0000_50_cluster-ingress-operator_00-ingress-credentials-request.yaml 4
   0000_50_cluster-network-operator_02-cncc-credentials.yaml 5
   0000_50_cluster-storage-operator_03_credentials_request_aws.yaml 6

   1

   The Machine API Operator CR is required.

   2

   The Cloud Credential Operator CR is required.

   3

   The Image Registry Operator CR is required.

   4

   The Ingress Operator CR is required.

   5

   The Network Operator CR is required.

   6

   The Storage Operator CR is an optional component and might be disabled in your cluster.

   Example credrequests directory contents for OpenShift Container Platform 4.12 on GCP

   0000_26_cloud-controller-manager-operator_16_credentialsrequest-gcp.yaml 1
   0000_30_machine-api-operator_00_credentials-request.yaml 2
   0000_50_cloud-credential-operator_05-gcp-ro-credentialsrequest.yaml 3
   0000_50_cluster-image-registry-operator_01-registry-credentials-request-gcs.yaml 4
   0000_50_cluster-ingress-operator_00-ingress-credentials-request.yaml 5
   0000_50_cluster-network-operator_02-cncc-credentials.yaml 6
   0000_50_cluster-storage-operator_03_credentials_request_gcp.yaml 7

   1

   The Cloud Controller Manager Operator CR is required.

   2

   The Machine API Operator CR is required.

   3

   The Cloud Credential Operator CR is required.

   4

   The Image Registry Operator CR is required.

   5

   The Ingress Operator CR is required.

   6

   The Network Operator CR is required.

   7

   The Storage Operator CR is an optional component and might be disabled in your cluster.

Procedure

1. Log in to oc on the cluster as a user with the cluster-admin role.

2. Edit the CloudCredential resource to add an upgradeable-to annotation within the metadata field by running the following command:

   $ oc edit cloudcredential cluster

   Text to add

   ...
     metadata:
       annotations:
         cloudcredential.openshift.io/upgradeable-to: <version_number>
   ...

   Where <version_number> is the version that you are upgrading to, in the format x.y.z. For example, use 4.12.2 for OpenShift Container Platform 4.12.2.

   It may take several minutes after adding the annotation for the upgradeable status to change.

Verification

1. In the Administrator perspective of the web console, navigate to Administration → Cluster Settings.

2. To view the CCO status details, click cloud-credential in the Cluster Operators list.

   • If the Upgradeable status in the Conditions section is False, verify that the upgradeable-to annotation is free of typographical errors.
3. When the Upgradeable status in the Conditions section is True, begin the OpenShift Container Platform upgrade.

Procedure

1. Extract and examine the CredentialsRequest custom resource for the new release.

   The "Manually creating IAM" section of the installation content for your cloud provider explains how to obtain and use the credentials required for your cloud.

2. Update the manually maintained credentials on your cluster:

   • Create new secrets for any CredentialsRequest custom resources that are added by the new release image.
   • If the CredentialsRequest custom resources for any existing credentials that are stored in secrets have changed permissions requirements, update the permissions as required.

3. If your cluster uses cluster capabilities to disable one or more optional components, delete the CredentialsRequest custom resources for any disabled components.

   Example credrequests directory contents for OpenShift Container Platform 4.12 on AWS

   0000_30_machine-api-operator_00_credentials-request.yaml 1
   0000_50_cloud-credential-operator_05-iam-ro-credentialsrequest.yaml 2
   0000_50_cluster-image-registry-operator_01-registry-credentials-request.yaml 3
   0000_50_cluster-ingress-operator_00-ingress-credentials-request.yaml 4
   0000_50_cluster-network-operator_02-cncc-credentials.yaml 5
   0000_50_cluster-storage-operator_03_credentials_request_aws.yaml 6

   1

   The Machine API Operator CR is required.

   2

   The Cloud Credential Operator CR is required.

   3

   The Image Registry Operator CR is required.

   4

   The Ingress Operator CR is required.

   5

   The Network Operator CR is required.

   6

   The Storage Operator CR is an optional component and might be disabled in your cluster.

   Example credrequests directory contents for OpenShift Container Platform 4.12 on GCP

   0000_26_cloud-controller-manager-operator_16_credentialsrequest-gcp.yaml 1
   0000_30_machine-api-operator_00_credentials-request.yaml 2
   0000_50_cloud-credential-operator_05-gcp-ro-credentialsrequest.yaml 3
   0000_50_cluster-image-registry-operator_01-registry-credentials-request-gcs.yaml 4
   0000_50_cluster-ingress-operator_00-ingress-credentials-request.yaml 5
   0000_50_cluster-network-operator_02-cncc-credentials.yaml 6
   0000_50_cluster-storage-operator_03_credentials_request_gcp.yaml 7

   1

   The Cloud Controller Manager Operator CR is required.

   2

   The Machine API Operator CR is required.

   3

   The Cloud Credential Operator CR is required.

   4

   The Image Registry Operator CR is required.

   5

   The Ingress Operator CR is required.

   6

   The Network Operator CR is required.

   7

   The Storage Operator CR is an optional component and might be disabled in your cluster.

Procedure

1. Log in to the OpenShift Container Platform web console.
2. Navigate to Compute → MachineHealthChecks.

3. To pause the machine health checks, add the cluster.x-k8s.io/paused="" annotation to each MachineHealthCheck resource. For example, to add the annotation to the machine-api-termination-handler resource, complete the following steps:

   1. Click the Options menu next to the machine-api-termination-handler and click Edit annotations.
   2. In the Edit annotations dialog, click Add more.
   3. In the Key and Value fields, add cluster.x-k8s.io/paused and "" values, respectively, and click Save.

Procedure

1. From the web console, click Administration → Cluster Settings and review the contents of the Details tab.

2. For production clusters, ensure that the Channel is set to the correct channel for the version that you want to update to, such as stable-4.12.

   Important

   For production clusters, you must subscribe to a stable-*, eus-* or fast-* channel.

   Note

   When you are ready to move to the next minor version, choose the channel that corresponds to that minor version. The sooner the update channel is declared, the more effectively the cluster can recommend update paths to your target version. The cluster might take some time to evaluate all the possible updates that are available and offer the best update recommendations to choose from. Update recommendations can change over time, as they are based on what update options are available at the time.

   If you cannot see an update path to your target minor version, keep updating your cluster to the latest patch release for your current version until the next minor version is available in the path.

   • If the Update status is not Updates available, you cannot update your cluster.
   • Select channel indicates the cluster version that your cluster is running or is updating to.

3. Select a version to update to, and click Save.

   The Input channel Update status changes to Update to <product-version> in progress, and you can review the progress of the cluster update by watching the progress bars for the Operators and nodes.

   Note

   If you are upgrading your cluster to the next minor version, like version 4.y to 4.(y+1), it is recommended to confirm your nodes are updated before deploying workloads that rely on a new feature. Any pools with worker nodes that are not yet updated are displayed on the Cluster Settings page.

4. After the update completes and the Cluster Version Operator refreshes the available updates, check if more updates are available in your current channel.

   • If updates are available, continue to perform updates in the current channel until you can no longer update.
   • If no updates are available, change the Channel to the stable-*, eus-* or fast-* channel for the next minor version, and update to the version that you want in that channel.

   You might need to perform several intermediate updates until you reach the version that you want.

Procedure

1. Navigate to Administration → Cluster Settings, click version.

2. Click the YAML tab and then edit the upstream parameter value:

   Example output

     ...
     spec:
       clusterID: db93436d-7b05-42cc-b856-43e11ad2d31a
       upstream: '<update-server-url>' 1
     ...

   1

   The <update-server-url> variable specifies the URL for the update server.

   The default upstream is https://api.openshift.com/api/upgrades_info/v1/graph.

3. Click Save.

Procedure

1. To list all the available MachineHealthCheck resources that you want to pause, run the following command:

   $ oc get machinehealthcheck -n openshift-machine-api

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

   Important

   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-

Procedure

1. View the available updates and note the version number of the update that you want to apply:

   $ oc adm upgrade

   Example output

   Cluster version is 4.9.23
   Upstream is unset, so the cluster will use an appropriate default.
   Channel: stable-4.9 (available channels: candidate-4.10, candidate-4.9, fast-4.10, fast-4.9, stable-4.10, stable-4.9, eus-4.10)
   Recommended updates:
   VERSION IMAGE
   4.9.24  quay.io/openshift-release-dev/ocp-release@sha256:6a899c54dda6b844bb12a247e324a0f6cde367e880b73ba110c056df6d018032
   4.9.25  quay.io/openshift-release-dev/ocp-release@sha256:2eafde815e543b92f70839972f585cc52aa7c37aa72d5f3c8bc886b0fd45707a
   4.9.26  quay.io/openshift-release-dev/ocp-release@sha256:3ccd09dd08c303f27a543351f787d09b83979cd31cf0b4c6ff56cd68814ef6c8
   4.9.27  quay.io/openshift-release-dev/ocp-release@sha256:1c7db78eec0cf05df2cead44f69c0e4b2c3234d5635c88a41e1b922c3bedae16
   4.9.28  quay.io/openshift-release-dev/ocp-release@sha256:4084d94969b186e20189649b5affba7da59f7d1943e4e5bc7ef78b981eafb7a8
   4.9.29  quay.io/openshift-release-dev/ocp-release@sha256:b04ca01d116f0134a102a57f86c67e5b1a3b5da1c4a580af91d521b8fa0aa6ec
   4.9.31  quay.io/openshift-release-dev/ocp-release@sha256:2a28b8ebb53d67dd80594421c39e36d9896b1e65cb54af81fbb86ea9ac3bf2d7
   4.9.32  quay.io/openshift-release-dev/ocp-release@sha256:ecdb6d0df547b857eaf0edb5574ddd64ca6d9aff1fa61fd1ac6fb641203bedfa

   Note
   • If there are no available updates, updates that are supported but not recommended might still be available. See Updating along a conditional update path for more information.
   • For details and information on how to perform an EUS-to-EUS channel update, please refer to the Preparing to perform an EUS-to-EUS upgrade page, listed in the Additional resources section.

2. Based on your organization requirements, set the appropriate update channel. For example, you can set your channel to stable-4.13 or fast-4.13. For more information about channels, refer to Understanding update channels and releases listed in the Additional resources section.

   $ oc adm upgrade channel <channel>

   For example, to set the channel to stable-4.12:

   $ oc adm upgrade channel stable-4.12

   Important

   For production clusters, you must subscribe to a stable-*, eus-*, or fast-* channel.

   Note

   When you are ready to move to the next minor version, choose the channel that corresponds to that minor version. The sooner the update channel is declared, the more effectively the cluster can recommend update paths to your target version. The cluster might take some time to evaluate all the possible updates that are available and offer the best update recommendations to choose from. Update recommendations can change over time, as they are based on what update options are available at the time.

   If you cannot see an update path to your target minor version, keep updating your cluster to the latest patch release for your current version until the next minor version is available in the path.

3. Apply an update:

   • To update to the latest version:

     $ oc adm upgrade --to-latest=true 1

   • To update to a specific version:

     $ oc adm upgrade --to=<version> 1

     1 1

     <version> is the update version that you obtained from the output of the oc adm upgrade command.

4. Review the status of the Cluster Version Operator:

   $ oc adm upgrade

5. After the update completes, you can confirm that the cluster version has updated to the new version:

   $ oc get clusterversion

   Example output

   Cluster version is <version>
   
   Upstream is unset, so the cluster will use an appropriate default.
   Channel: stable-4.10 (available channels: candidate-4.10, candidate-4.11, eus-4.10, fast-4.10, fast-4.11, stable-4.10)
   
   No updates available. You may force an upgrade to a specific release image, but doing so might not be supported and might result in downtime or data loss.

6. If you are updating your cluster to the next minor version, such as version X.y to X.(y+1), it is recommended to confirm that your nodes are updated before deploying workloads that rely on a new feature:

   $ oc get nodes

   Example output

   NAME                           STATUS   ROLES    AGE   VERSION
   ip-10-0-168-251.ec2.internal   Ready    master   82m   v1.25.0
   ip-10-0-170-223.ec2.internal   Ready    master   82m   v1.25.0
   ip-10-0-179-95.ec2.internal    Ready    worker   70m   v1.25.0
   ip-10-0-182-134.ec2.internal   Ready    worker   70m   v1.25.0
   ip-10-0-211-16.ec2.internal    Ready    master   82m   v1.25.0
   ip-10-0-250-100.ec2.internal   Ready    worker   69m   v1.25.0

Procedure

1. To view the description of the update when it is not recommended because a risk might apply, run the following command:

   $ oc adm upgrade --include-not-recommended

2. If the cluster administrator evaluates the potential known risks and decides it is acceptable for the current cluster, then the administrator can waive the safety guards and proceed the update by running the following command:

   $ oc adm upgrade --allow-not-recommended --to <version> <.>

   <.> <version> is the supported but not recommended update version that you obtained from the output of the previous command.

1. Create custom machine config pools (MCP) based on the worker pool.

   Note

   You can change the maxUnavailable setting in an MCP to specify the percentage or the number of machines that can be updating at any given time. The default is 1.

2. Add a node selector to the custom MCPs. For each node that you do not want to update simultaneously with the rest of the cluster, add a matching label to the nodes. This label associates the node to the MCP.

   Important

   Do not remove the default worker label from the nodes. The nodes must have a role label to function properly in the cluster.

3. Pause the MCPs you do not want to update as part of the update process.

   Note

   Pausing the MCP also pauses the kube-apiserver-to-kubelet-signer automatic CA certificates rotation. New CA certificates are generated at 292 days from the installation date and old certificates are removed 365 days from the installation date. See the Understand CA cert auto renewal in Red Hat OpenShift 4 to find out how much time you have before the next automatic CA certificate rotation.

   Make sure the pools are unpaused when the CA certificate rotation happens. If the MCPs are paused, the MCO cannot push the newly rotated certificates to those nodes. This causes the cluster to become degraded and causes failure in multiple oc commands, including oc debug, oc logs, oc exec, and oc attach. You receive alerts in the Alerting UI of the OpenShift Container Platform web console if an MCP is paused when the certificates are rotated.

4. Perform the cluster update. The update process updates the MCPs that are not paused, including the control plane nodes.
5. Test your applications on the updated nodes to ensure they are working as expected.
6. Unpause one of the remaining MCPs, wait for the nodes in that pool to finish updating, and test the applications on those nodes. Repeat this process until all worker nodes are updated.
7. Optional: Remove the custom label from updated nodes and delete the custom MCPs.

Procedure

1. List the worker nodes in your cluster by running the following command:

   $ oc get -l 'node-role.kubernetes.io/master!=' -o 'jsonpath={range .items[*]}{.metadata.name}{"\n"}{end}' nodes

   Example output

   ci-ln-pwnll6b-f76d1-s8t9n-worker-a-s75z4
   ci-ln-pwnll6b-f76d1-s8t9n-worker-b-dglj2
   ci-ln-pwnll6b-f76d1-s8t9n-worker-c-lldbm

2. For each node that you want to delay, add a custom label to the node by running the following command:

   $ oc label node <node_name> node-role.kubernetes.io/<custom_label>=

   For example:

   $ oc label node ci-ln-0qv1yp2-f76d1-kl2tq-worker-a-j2ssz node-role.kubernetes.io/workerpool-canary=

   Example output

   node/ci-ln-gtrwm8t-f76d1-spbl7-worker-a-xk76k labeled

3. Create the new MCP:

   1. Create an MCP YAML file:

      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfigPool
      metadata:
        name: workerpool-canary 1
      spec:
        machineConfigSelector:
          matchExpressions:
            - {
               key: machineconfiguration.openshift.io/role,
               operator: In,
               values: [worker,workerpool-canary] 2
              }
        nodeSelector:
          matchLabels:
            node-role.kubernetes.io/workerpool-canary: "" 3

      1

      Specify a name for the MCP.

      2

      Specify the worker and custom MCP name.

      3

      Specify the custom label you added to the nodes that you want in this pool.

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

      $ oc create -f <file_name>

      Example output

      machineconfigpool.machineconfiguration.openshift.io/workerpool-canary created

4. View the list of MCPs in the cluster and their current state by running the following command:

   $ oc get machineconfigpool

   Example output

   NAME              CONFIG                                                        UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
   master            rendered-master-b0bb90c4921860f2a5d8a2f8137c1867              True      False      False      3              3                   3                     0                      97m
   workerpool-canary rendered-workerpool-canary-87ba3dec1ad78cb6aecebf7fbb476a36   True      False      False      1              1                   1                     0                      2m42s
   worker            rendered-worker-87ba3dec1ad78cb6aecebf7fbb476a36              True      False      False      2              2                   2                     0                      97m

   The new machine config pool, workerpool-canary, is created and the number of nodes to which you added the custom label are shown in the machine counts. The worker MCP machine counts are reduced by the same number. It can take several minutes to update the machine counts. In this example, one node was moved from the worker MCP to the workerpool-canary MCP.

Procedure

1. Create a secondary MCP as described in the following two steps:

   1. Save the following configuration file as machineConfigPool.yaml.

      Example machineConfigPool YAML

      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfigPool
      metadata:
        name: worker-perf
      spec:
        machineConfigSelector:
          matchExpressions:
            - {
               key: machineconfiguration.openshift.io/role,
               operator: In,
               values: [worker,worker-perf]
              }
        nodeSelector:
          matchLabels:
            node-role.kubernetes.io/worker-perf: ""
      # ...

   2. Create the new machine config pool by running the following command:

      $ oc create -f machineConfigPool.yaml

      Example output

      machineconfigpool.machineconfiguration.openshift.io/worker-perf created

2. Add some machines to the secondary MCP. The following example labels the worker nodes worker-a, worker-b, and worker-c to the MCP worker-perf:

   $ oc label node worker-a node-role.kubernetes.io/worker-perf=''

   $ oc label node worker-b node-role.kubernetes.io/worker-perf=''

   $ oc label node worker-c node-role.kubernetes.io/worker-perf=''

3. Create a new MachineConfig for the MCP worker-perf as described in the following two steps:

   1. Save the following MachineConfig example as a file called new-machineconfig.yaml:

      Example MachineConfig YAML

      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfig
      metadata:
        labels:
          machineconfiguration.openshift.io/role: worker-perf
        name: 06-kdump-enable-worker-perf
      spec:
        config:
          ignition:
            version: 3.2.0
          systemd:
            units:
            - enabled: true
              name: kdump.service
        kernelArguments:
          - crashkernel=512M
      # ...

   2. Apply the MachineConfig by running the following command:

      $ oc create -f new-machineconfig.yaml

4. Create the new canary MCP and add machines from the MCP you created in the previous steps. The following example creates an MCP called worker-perf-canary, and adds machines from the worker-perf MCP that you previosuly created.

   1. Label the canary worker node worker-a by running the following command:

      $ oc label node worker-a node-role.kubernetes.io/worker-perf-canary=''

   2. Remove the canary worker node worker-a from the original MCP by running the following command:

      $ oc label node worker-a node-role.kubernetes.io/worker-perf-

   3. Save the following file as machineConfigPool-Canary.yaml.

      Example machineConfigPool-Canary.yaml file

      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfigPool
      metadata:
        name: worker-perf-canary
      spec:
        machineConfigSelector:
          matchExpressions:
            - {
               key: machineconfiguration.openshift.io/role,
               operator: In,
               values: [worker,worker-perf,worker-perf-canary] 1
              }
        nodeSelector:
          matchLabels:
            node-role.kubernetes.io/worker-perf-canary: ""

      1

      Optional value. This example includes worker-perf-canary as an additional value. You can use a value in this way to configure members of an additional MachineConfig.

   4. Create the new worker-perf-canary by running the following command:

      $ oc create -f machineConfigPool-Canary.yaml

      Example output

      machineconfigpool.machineconfiguration.openshift.io/worker-perf-canary created

5. Check if the MachineConfig is inherited in worker-perf-canary.

   1. Verify that no MCP is degraded by running the following command:

      $ oc get mcp

      Example output

      NAME                  CONFIG                                                          UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
      master                rendered-master-2bf1379b39e22bae858ea1a3ff54b2ac                True      False      False      3              3                   3                     0                      5d16h
      worker                rendered-worker-b9576d51e030413cfab12eb5b9841f34                True      False      False      0              0                   0                     0                      5d16h
      worker-perf          rendered-worker-perf-b98a1f62485fa702c4329d17d9364f6a          True      False      False      2              2                   2                     0                      56m
      worker-perf-canary   rendered-worker-perf-canary-b98a1f62485fa702c4329d17d9364f6a   True      False      False      1              1                   1                     0                      44m

   2. Verify that the machines are inherited from worker-perf into worker-perf-canary.

      $ oc get nodes

      Example output

      NAME       STATUS   ROLES                        AGE     VERSION
      ...
      worker-a   Ready    worker,worker-perf-canary   5d15h   v1.27.13+e709aa5
      worker-b   Ready    worker,worker-perf          5d15h   v1.27.13+e709aa5
      worker-c   Ready    worker,worker-perf          5d15h   v1.27.13+e709aa5

   3. Verify that kdump service is enabled on worker-a by running the following command:

      $ systemctl status kdump.service

      Example output

      NAME       STATUS   ROLES                        AGE     VERSION
      ...
      kdump.service - Crash recovery kernel arming
           Loaded: loaded (/usr/lib/systemd/system/kdump.service; enabled; preset: disabled)
           Active: active (exited) since Tue 2024-09-03 12:44:43 UTC; 10s ago
          Process: 4151139 ExecStart=/usr/bin/kdumpctl start (code=exited, status=0/SUCCESS)
         Main PID: 4151139 (code=exited, status=0/SUCCESS)

   4. Verify that the MCP has updated the crashkernel by running the following command:

      $ cat /proc/cmdline

      The output should include the updated crashekernel value, for example:

      Example output

      crashkernel=512M

6. Optional: If you are satisfied with the upgrade, you can return worker-a to worker-perf.

   1. Return worker-a to worker-perf by running the following command:

      $ oc label node worker-a node-role.kubernetes.io/worker-perf=''

   2. Remove worker-a from the canary MCP by running the following command:

      $ oc label node worker-a node-role.kubernetes.io/worker-perf-canary-

Procedure

1. Patch the MCP that you want paused by running the following command:

   $ oc patch mcp/<mcp_name> --patch '{"spec":{"paused":true}}' --type=merge

   For example:

   $  oc patch mcp/workerpool-canary --patch '{"spec":{"paused":true}}' --type=merge

   Example output

   machineconfigpool.machineconfiguration.openshift.io/workerpool-canary patched

Procedure

1. Patch the MCP that you want to unpause:

   $ oc patch mcp/<mcp_name> --patch '{"spec":{"paused":false}}' --type=merge

   For example:

   $  oc patch mcp/workerpool-canary --patch '{"spec":{"paused":false}}' --type=merge

   Example output

   machineconfigpool.machineconfiguration.openshift.io/workerpool-canary patched

2. Optional: Check the progress of the update by using one of the following options:

   1. Check the progress from the web console by clicking Administration → Cluster settings.

   2. Check the progress by running the following command:

      $ oc get machineconfigpools

3. Test your applications on the updated nodes to ensure that they are working as expected.
4. Repeat this process for any other paused MCPs, one at a time.

Procedure

1. For each node in a custom MCP, remove the custom label from the node by running the following command:

   $ oc label node <node_name> node-role.kubernetes.io/<custom_label>-

   For example:

   $ oc label node ci-ln-0qv1yp2-f76d1-kl2tq-worker-a-j2ssz node-role.kubernetes.io/workerpool-canary-

   Example output

   node/ci-ln-0qv1yp2-f76d1-kl2tq-worker-a-j2ssz labeled

   The Machine Config Operator moves the nodes back to the original MCP and reconciles the node to the MCP configuration.

2. To ensure that node has been removed from the custom MCP, view the list of MCPs in the cluster and their current state by running the following command:

   $ oc get mcp

   Example output

   NAME                CONFIG                                                   UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
   master              rendered-master-1203f157d053fd987c7cbd91e3fbc0ed         True      False      False      3              3                   3                     0                      61m
   workerpool-canary   rendered-mcp-noupdate-5ad4791166c468f3a35cd16e734c9028   True      False      False      0              0                   0                     0                      21m
   worker              rendered-worker-5ad4791166c468f3a35cd16e734c9028         True      False      False      3              3                   3                     0                      61m

   When the node is removed from the custom MCP and moved back to the original MCP, it can take several minutes to update the machine counts. In this example, one node was moved from the removed workerpool-canary MCP to the worker MCP.

3. Optional: Delete the custom MCP by running the following command:

   $ oc delete mcp <mcp_name>

1. Inspect the system status:

   # bootupctl status

   Example output for x86_64

   Component EFI
     Installed: grub2-efi-x64-1:2.04-31.el8_4.1.x86_64,shim-x64-15-8.el8_1.x86_64
     Update: At latest version

   Example output for aarch64

   Component EFI
     Installed: grub2-efi-aa64-1:2.02-99.el8_4.1.aarch64,shim-aa64-15.4-2.el8_1.aarch64
     Update: At latest version

2. OpenShift Container Platform clusters initially installed on version 4.4 and older require an explicit adoption phase.

   If the system status is Adoptable, perform the adoption:

   # bootupctl adopt-and-update

   Example output

   Updated: grub2-efi-x64-1:2.04-31.el8_4.1.x86_64,shim-x64-15-8.el8_1.x86_64

3. If an update is available, apply the update so that the changes take effect on the next reboot:

   # bootupctl update

   Example output

   Updated: grub2-efi-x64-1:2.04-31.el8_4.1.x86_64,shim-x64-15-8.el8_1.x86_64

1. Create a Butane config file, 99-worker-bootupctl-update.bu, including the contents of the bootupctl-update.service systemd unit.

   Note

   See "Creating machine configs with Butane" for information about Butane.

   Example output

   variant: openshift
   version: 4.12.0
   metadata:
     name: 99-worker-chrony 1
     labels:
       machineconfiguration.openshift.io/role: worker 2
   systemd:
     units:
     - name: bootupctl-update.service
       enabled: true
       contents: |
         [Unit]
         Description=Bootupd automatic update
   
         [Service]
         ExecStart=/usr/bin/bootupctl update
         RemainAfterExit=yes
   
         [Install]
         WantedBy=multi-user.target

   1 2

   On control plane nodes, substitute master for worker in both of these locations.

2. Use Butane to generate a MachineConfig object file, 99-worker-bootupctl-update.yaml, containing the configuration to be delivered to the nodes:

   $ butane 99-worker-bootupctl-update.bu -o 99-worker-bootupctl-update.yaml

3. Apply the configurations in one of two ways:

   • If the cluster is not running yet, after you generate manifest files, add the MachineConfig object file to the <installation_directory>/openshift directory, and then continue to create the cluster.

   • If the cluster is already running, apply the file:

     $ oc apply -f ./99-worker-bootupctl-update.yaml

Procedure

1. From the web console, click Administration → Cluster Settings and review the contents of the Details tab.

2. For production clusters, ensure that the Channel is set to the correct channel for the version that you want to update to, such as stable-4.12.

   Important

   For production clusters, you must subscribe to a stable-*, eus-* or fast-* channel.

   Note

   When you are ready to move to the next minor version, choose the channel that corresponds to that minor version. The sooner the update channel is declared, the more effectively the cluster can recommend update paths to your target version. The cluster might take some time to evaluate all the possible updates that are available and offer the best update recommendations to choose from. Update recommendations can change over time, as they are based on what update options are available at the time.

   If you cannot see an update path to your target minor version, keep updating your cluster to the latest patch release for your current version until the next minor version is available in the path.

   • If the Update status is not Updates available, you cannot update your cluster.
   • Select channel indicates the cluster version that your cluster is running or is updating to.

3. Select a version to update to, and click Save.

   The Input channel Update status changes to Update to <product-version> in progress, and you can review the progress of the cluster update by watching the progress bars for the Operators and nodes.

   Note

   If you are upgrading your cluster to the next minor version, like version 4.y to 4.(y+1), it is recommended to confirm your nodes are updated before deploying workloads that rely on a new feature. Any pools with worker nodes that are not yet updated are displayed on the Cluster Settings page.

4. After the update completes and the Cluster Version Operator refreshes the available updates, check if more updates are available in your current channel.

   • If updates are available, continue to perform updates in the current channel until you can no longer update.
   • If no updates are available, change the Channel to the stable-*, eus-* or fast-* channel for the next minor version, and update to the version that you want in that channel.

   You might need to perform several intermediate updates until you reach the version that you want.

   Note

   When you update a cluster that contains Red Hat Enterprise Linux (RHEL) worker machines, those workers temporarily become unavailable during the update process. You must run the upgrade playbook against each RHEL machine as it enters the NotReady state for the cluster to finish updating.

Procedure

1. Stop and disable firewalld on the host:

   # systemctl disable --now firewalld.service

   Note

   By default, the base OS RHEL with "Minimal" installation option enables firewalld service. Having the firewalld service enabled on your host prevents you from accessing OpenShift Container Platform logs on the worker. Do not enable firewalld later if you wish to continue accessing OpenShift Container Platform logs on the worker.

2. Enable the repositories that are required for OpenShift Container Platform 4.12:

   1. On the machine that you run the Ansible playbooks, update the required repositories:

      # subscription-manager repos --disable=rhocp-4.11-for-rhel-8-x86_64-rpms \
                                   --disable=ansible-2.9-for-rhel-8-x86_64-rpms \
                                   --enable=rhocp-4.12-for-rhel-8-x86_64-rpms

      Important

      As of OpenShift Container Platform 4.11, the Ansible playbooks are provided only for RHEL 8. If a RHEL 7 system was used as a host for the OpenShift Container Platform 4.10 Ansible playbooks, you must either upgrade the Ansible host to RHEL 8, or create a new Ansible host on a RHEL 8 system and copy over the inventories from the old Ansible host.

   2. On the machine that you run the Ansible playbooks, update the Ansible package:

      # yum swap ansible ansible-core

   3. On the machine that you run the Ansible playbooks, update the required packages, including openshift-ansible:

      # yum update openshift-ansible openshift-clients

   4. On each RHEL compute node, update the required repositories:

      # subscription-manager repos --disable=rhocp-4.11-for-rhel-8-x86_64-rpms \
                                   --enable=rhocp-4.12-for-rhel-8-x86_64-rpms

3. Update a RHEL worker machine:

   1. Review your Ansible inventory file at /<path>/inventory/hosts and update its contents so that the RHEL 8 machines are listed in the [workers] section, as shown in the following example:

      [all:vars]
      ansible_user=root
      #ansible_become=True
      
      openshift_kubeconfig_path="~/.kube/config"
      
      [workers]
      mycluster-rhel8-0.example.com
      mycluster-rhel8-1.example.com
      mycluster-rhel8-2.example.com
      mycluster-rhel8-3.example.com

   2. Change to the openshift-ansible directory:

      $ cd /usr/share/ansible/openshift-ansible

   3. Run the upgrade playbook:

      $ ansible-playbook -i /<path>/inventory/hosts playbooks/upgrade.yml 1

      1

      For <path>, specify the path to the Ansible inventory file that you created.

      Note

      The upgrade playbook only upgrades the OpenShift Container Platform packages. It does not update the operating system packages.

4. After you update all of the workers, confirm that all of your cluster nodes have updated to the new version:

   # oc get node

   Example output

   NAME                        STATUS                        ROLES    AGE    VERSION
   mycluster-control-plane-0   Ready                         master   145m   v1.25.0
   mycluster-control-plane-1   Ready                         master   145m   v1.25.0
   mycluster-control-plane-2   Ready                         master   145m   v1.25.0
   mycluster-rhel8-0           Ready                         worker   98m    v1.25.0
   mycluster-rhel8-1           Ready                         worker   98m    v1.25.0
   mycluster-rhel8-2           Ready                         worker   98m    v1.25.0
   mycluster-rhel8-3           Ready                         worker   98m    v1.25.0

5. Optional: Update the operating system packages that were not updated by the upgrade playbook. To update packages that are not on 4.12, use the following command:

   # yum update

   Note

   You do not need to exclude RPM packages if you are using the same RPM repository that you used when you installed 4.12.

1. Install the OpenShift CLI (oc) on all devices being used to retrieve and push release images.
2. Download the registry pull secret and add it to your cluster.

3. If you use the oc-mirror OpenShift CLI (oc) plugin:

   1. Install the oc-mirror plugin on all devices being used to retrieve and push release images.
   2. Create an image set configuration file for the plugin to use when determining which release images to mirror. You can edit this configuration file later to change which release images that the plugin mirrors.
   3. Mirror your targeted release images directly to a mirror registry, or to removable media and then to a mirror registry.
   4. Configure your cluster to use the resources generated by the oc-mirror plugin.
   5. Repeat these steps as needed to update your mirror registry.

4. If you use the oc adm release mirror command:

   1. Set environment variables that correspond to your environment and the release images you want to mirror.
   2. Mirror your targeted release images directly to a mirror registry, or to removable media and then to a mirror registry.
   3. Repeat these steps as needed to update your mirror registry.

1. Configure access to a secured registry.
2. Update the global cluster pull secret to access your mirror registry.
3. Install the OSUS Operator.
4. Create a graph data container image for the OpenShift Update Service.
5. Install the OSUS application and configure your clusters to use the local OpenShift Update Service.
6. Perform a supported update procedure from the documentation as you would with a connected cluster.

1. Image validation stage
2. Build validation stage
3. Sign validation stage