16.3. Performing an image-based upgrade for single-node OpenShift clusters with the Lifecycle Agent

Procedure

1. Check that you have patched your ImageBasedUpgrade CR:

   apiVersion: lca.openshift.io/v1
   kind: ImageBasedUpgrade
   metadata:
     name: upgrade
   spec:
     stage: Idle
     seedImageRef:
       version: <target_version>
       image: <seed_container_image>
       pullSecretRef: <seed_pull_secret>
     autoRollbackOnFailure: {}
       initMonitorTimeoutSeconds: <initMonitorTimeoutSeconds>
     extraManifests:
     - name: example-extra-manifests-cm
       namespace: openshift-lifecycle-agent
     - name: example-catalogsources-cm
       namespace: openshift-lifecycle-agent
     oadpContent:
     - name: oadp-cm-example
       namespace: openshift-adp

   where:

   <target_version>

   Target platform version. The value must match the version of the seed image.

   <seed_container_image>

   Repository where the target cluster can pull the seed image from.

   <seed_pull_secret>

   Reference to a secret with credentials to pull container images if the images are in a private registry.

   <initMonitorTimeoutSeconds>

   Optional: Time frame in seconds to roll back if the upgrade does not complete within that time frame after the first reboot. If not defined or set to 0, the Lifecycle Agent uses the default value of 1800 seconds (30 minutes).

   extraManifests

   Optional: List of ConfigMap resources. These resources contain your custom catalog sources to retain after the upgrade and any extra manifests that the seed image does not include.

   oadpContent

   List of ConfigMap resources that contain the OADP Backup and Restore CRs.

2. To start the Prep stage, change the value of the stage field to Prep in the ImageBasedUpgrade CR by running the following command:

   $ oc patch imagebasedupgrades.lca.openshift.io upgrade -p='{"spec": {"stage": "Prep"}}' --type=merge -n openshift-lifecycle-agent

   If you include ConfigMap objects for OADP resources and extra manifests, Lifecycle Agent validates the specified ConfigMap objects during the Prep stage.

   The following issues might occur:

   • Validation warnings or errors if the Lifecycle Agent detects any issues with the extraManifests parameters.
   • Validation errors if the Lifecycle Agent detects any issues with the oadpContent parameters.

   Validation warnings do not block the Upgrade stage but you must decide if it is safe to proceed with the upgrade. These warnings, for example missing custom resource definitions (CRDs), namespaces, or dry run failures, update the status.conditions for the Prep stage and annotation fields in the ImageBasedUpgrade CR with details about the warning. The following example shows these details:

   # ...
   metadata:
   annotations:
     extra-manifest.lca.openshift.io/validation-warning: '...'
   # ...

   However, validation errors, such as adding MachineConfig or Operator manifests to extra manifests, cause the Prep stage to fail and block the Upgrade stage.

   When the validations pass, the cluster creates a new ostree stateroot, which involves pulling and unpacking the seed image, and running host-level commands. Finally, the Lifecycle Agent precaches all the required images on the target cluster.