|
| 1 | +// Module included in the following assemblies: |
| 2 | +// * edge_computing/image-based-upgrade/cnf-image-based-upgrade-base.adoc |
| 3 | + |
| 4 | +:_mod-docs-content-type: PROCEDURE |
| 5 | +[id="ztp-image-based-upgrade-prep_{context}"] |
| 6 | += Moving to the Prep stage of the image-based upgrade with {lcao} |
| 7 | + |
| 8 | +When you deploy the {lcao} on a cluster, an `ImageBasedUpgrade` custom resource (CR) is automatically created. |
| 9 | + |
| 10 | +After you created all the resources that you need during the upgrade, you can move on to the `Prep` stage. |
| 11 | +For more information, see the "Creating ConfigMap objects for the image-based upgrade with {lcao}" section. |
| 12 | + |
| 13 | +.Prerequisites |
| 14 | + |
| 15 | +* You have created resources to back up and restore your clusters. |
| 16 | +
|
| 17 | +.Procedure |
| 18 | + |
| 19 | +. Check that you have patched your `ImageBasedUpgrade` CR: |
| 20 | ++ |
| 21 | +[source,yaml] |
| 22 | +---- |
| 23 | +apiVersion: lca.openshift.io/v1 |
| 24 | +kind: ImageBasedUpgrade |
| 25 | +metadata: |
| 26 | + name: upgrade |
| 27 | +spec: |
| 28 | + stage: Idle |
| 29 | + seedImageRef: |
| 30 | + version: 4.15.2 <1> |
| 31 | + image: <seed_container_image> <2> |
| 32 | + pullSecretRef: <seed_pull_secret> <3> |
| 33 | + autoRollbackOnFailure: {} |
| 34 | +# initMonitorTimeoutSeconds: 1800 <4> |
| 35 | + extraManifests: <5> |
| 36 | + - name: example-extra-manifests-cm |
| 37 | + namespace: openshift-lifecycle-agent |
| 38 | + - name: example-catalogsources-cm |
| 39 | + namespace: openshift-lifecycle-agent |
| 40 | + oadpContent: <6> |
| 41 | + - name: oadp-cm-example |
| 42 | + namespace: openshift-adp |
| 43 | +---- |
| 44 | +<1> Specify the target platform version. The value must match the version of the seed image. |
| 45 | +<2> Specify the repository where the target cluster can pull the seed image from. |
| 46 | +<3> Specify the reference to a secret with credentials to pull container images if the images are in a private registry. |
| 47 | +<4> (Optional) Specify the 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 default value of `1800` seconds (30 minutes) is used. |
| 48 | +<5> (Optional) Specify the list of `ConfigMap` resources that contain your custom catalog sources to retain after the upgrade and your extra manifests to apply to the target cluster that are not part of the seed image. |
| 49 | +<6> Add the `oadpContent` section with the OADP `ConfigMap` information. |
| 50 | + |
| 51 | +. To start the `Prep` stage, change the value of the `stage` field to `Prep` in the `ImageBasedUpgrade` CR by running the following command: |
| 52 | ++ |
| 53 | +-- |
| 54 | +[source,terminal] |
| 55 | +---- |
| 56 | +$ oc patch imagebasedupgrades.lca.openshift.io upgrade -p='{"spec": {"stage": "Prep"}}' --type=merge -n openshift-lifecycle-agent |
| 57 | +---- |
| 58 | + |
| 59 | +If you provide `ConfigMap` objects for OADP resources and extra manifests, {lcao} validates the specified `ConfigMap` objects during the `Prep` stage. |
| 60 | +You might encounter the following issues: |
| 61 | + |
| 62 | +* Validation warnings or errors if the {lcao} detects any issues with the `extraManifests` parameters. |
| 63 | +* Validation errors if the {lcao} detects any issues with the `oadpContent` parameters. |
| 64 | +
|
| 65 | +Validation warnings do not block the `Upgrade` stage but you must decide if it is safe to proceed with the upgrade. |
| 66 | +These warnings, for example missing 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. |
| 67 | + |
| 68 | +.Example validation warning |
| 69 | +[source,yaml] |
| 70 | +---- |
| 71 | +[...] |
| 72 | +metadata: |
| 73 | +annotations: |
| 74 | + extra-manifest.lca.openshift.io/validation-warning: '...' |
| 75 | +[...] |
| 76 | +---- |
| 77 | + |
| 78 | +However, validation errors, such as adding `MachineConfig` or Operator manifests to extra manifests, cause the `Prep` stage to fail and block the `Upgrade` stage. |
| 79 | + |
| 80 | +When the validations pass, the cluster creates a new `ostree` stateroot, which involves pulling and unpacking the seed image, and running host-level commands. |
| 81 | +Finally, all the required images are precached on the target cluster. |
| 82 | +-- |
| 83 | + |
| 84 | +.Verification |
| 85 | + |
| 86 | +* Check the status of the `ImageBasedUpgrade` CR by running the following command: |
| 87 | ++ |
| 88 | +-- |
| 89 | +[source,terminal] |
| 90 | +---- |
| 91 | +$ oc get ibu -o yaml |
| 92 | +---- |
| 93 | +
|
| 94 | +.Example output |
| 95 | +[source,yaml] |
| 96 | +---- |
| 97 | + conditions: |
| 98 | + - lastTransitionTime: "2024-01-01T09:00:00Z" |
| 99 | + message: In progress |
| 100 | + observedGeneration: 13 |
| 101 | + reason: InProgress |
| 102 | + status: "False" |
| 103 | + type: Idle |
| 104 | + - lastTransitionTime: "2024-01-01T09:00:00Z" |
| 105 | + message: Prep completed |
| 106 | + observedGeneration: 13 |
| 107 | + reason: Completed |
| 108 | + status: "False" |
| 109 | + type: PrepInProgress |
| 110 | + - lastTransitionTime: "2024-01-01T09:00:00Z" |
| 111 | + message: Prep stage completed successfully |
| 112 | + observedGeneration: 13 |
| 113 | + reason: Completed |
| 114 | + status: "True" |
| 115 | + type: PrepCompleted |
| 116 | + observedGeneration: 13 |
| 117 | + validNextStages: |
| 118 | + - Idle |
| 119 | + - Upgrade |
| 120 | +---- |
| 121 | +-- |
0 commit comments