使用生命周期代理为单节点 OpenShift 集群执行基于镜像的升级 - 单节点 OpenShift 集群的基于镜像的升级 | 边缘计算 | OpenShift Container Platform 4.17

使用生命周期代理将基于镜像的升级迁移到准备阶段
使用生命周期代理将基于镜像的升级迁移到升级阶段
使用生命周期代理将基于镜像的升级迁移到回滚阶段
对使用生命周期代理的基于镜像的升级进行故障排除

您可以使用生命周期代理对单节点 OpenShift 集群进行手动基于镜像的升级。

在集群上部署生命周期代理后，会自动创建ImageBasedUpgrade CR。您可以更新此 CR 以指定种子镜像的镜像存储库并遍历不同的阶段。

使用生命周期代理将基于镜像的升级迁移到准备阶段

在集群上部署生命周期代理后，会自动创建一个ImageBasedUpgrade自定义资源 (CR)。

创建升级期间所需的所有资源后，您可以继续进行准备阶段。有关更多信息，请参见“为使用生命周期代理的基于镜像的升级创建 ConfigMap 对象”部分。

先决条件

您已创建资源以备份和恢复您的集群。

步骤

检查您是否已修补您的ImageBasedUpgrade CR

apiVersion: lca.openshift.io/v1
kind: ImageBasedUpgrade
metadata:
  name: upgrade
spec:
  stage: Idle
  seedImageRef:
    version: 4.15.2 (1)
    image: <seed_container_image> (2)
    pullSecretRef: <seed_pull_secret> (3)
  autoRollbackOnFailure: {}
#    initMonitorTimeoutSeconds: 1800 (4)
  extraManifests: (5)
  - name: example-extra-manifests-cm
    namespace: openshift-lifecycle-agent
  - name: example-catalogsources-cm
    namespace: openshift-lifecycle-agent
  oadpContent: (6)
  - name: oadp-cm-example
    namespace: openshift-adp

1	目标平台版本。该值必须与种子镜像的版本匹配。
2	目标集群可以从中提取种子镜像的存储库。
3	如果镜像位于私有注册表中，则引用包含提取容器镜像凭据的密钥。
4	可选：如果升级在第一次重新引导后未在该时间范围内完成，则回滚的时间范围（以秒为单位）。如果未定义或设置为`0`，则使用默认值`1800` 秒（30 分钟）。
5	可选：包含升级后要保留的自定义目录源以及要应用于目标集群的不在种子镜像中的额外清单的`ConfigMap`资源列表。
6	包含 OADP`备份`和`恢复`CR 的`ConfigMap`资源列表。

要启动准备阶段，请通过运行以下命令将ImageBasedUpgrade CR 中的stage字段的值更改为准备
$ oc patch imagebasedupgrades.lca.openshift.io upgrade -p='{"spec": {"stage": "Prep"}}' --type=merge -n openshift-lifecycle-agent
如果您为 OADP 资源和额外清单提供了ConfigMap对象，则生命周期代理会在准备阶段验证指定的ConfigMap对象。您可能会遇到以下问题
- 如果生命周期代理检测到extraManifests参数有任何问题，则会发出验证警告或错误。
- 如果生命周期代理检测到oadpContent参数有任何问题，则会发出验证错误。
验证警告不会阻止升级阶段，但您必须确定是否可以安全地继续升级。例如，缺少 CRD、命名空间或干运行失败等警告会更新准备阶段的status.conditions和ImageBasedUpgrade CR 中的annotation字段，其中包含有关警告的详细信息。
验证警告示例
# ... metadata: annotations: extra-manifest.lca.openshift.io/validation-warning: '...' # ...
但是，验证错误（例如，将MachineConfig或 Operator 清单添加到额外清单）会导致准备阶段失败并阻止升级阶段。

验证通过后，集群将创建一个新的ostree stateroot，这涉及提取和解压种子镜像以及运行主机级命令。最后，所有必需的镜像都将预缓存到目标集群上。

验证

通过运行以下命令检查ImageBasedUpgrade CR 的状态

$ oc get ibu -o yaml

示例输出

  conditions:
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: In progress
    observedGeneration: 13
    reason: InProgress
    status: "False"
    type: Idle
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Prep completed
    observedGeneration: 13
    reason: Completed
    status: "False"
    type: PrepInProgress
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Prep stage completed successfully
    observedGeneration: 13
    reason: Completed
    status: "True"
    type: PrepCompleted
  observedGeneration: 13
  validNextStages:
  - Idle
  - Upgrade

其他资源

使用生命周期代理创建基于镜像升级的 ConfigMap 对象

迁移到使用生命周期代理的基于镜像升级的升级阶段

生成种子镜像并完成准备阶段后，您可以升级目标集群。在升级过程中，OADP 运算符会创建 OADP 自定义资源 (CR) 中指定的工件备份，然后生命周期代理升级集群。

如果升级失败或停止，将启动自动回滚。如果升级后出现问题，您可以启动手动回滚。有关手动回滚的更多信息，请参阅“迁移到使用生命周期代理的基于镜像升级的回滚阶段”。

先决条件

您已完成准备阶段。

步骤

要迁移到升级阶段，请通过运行以下命令将ImageBasedUpgrade CR 中的stage字段的值更改为Upgrade
```
$ oc patch imagebasedupgrades.lca.openshift.io upgrade -p='{"spec": {"stage": "Upgrade"}}' --type=merge
```

通过运行以下命令检查ImageBasedUpgrade CR 的状态

$ oc get ibu -o yaml

示例输出

status:
  conditions:
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: In progress
    observedGeneration: 5
    reason: InProgress
    status: "False"
    type: Idle
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Prep completed
    observedGeneration: 5
    reason: Completed
    status: "False"
    type: PrepInProgress
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Prep completed successfully
    observedGeneration: 5
    reason: Completed
    status: "True"
    type: PrepCompleted
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: |-
      Waiting for system to stabilize: one or more health checks failed
        - one or more ClusterOperators not yet ready: authentication
        - one or more MachineConfigPools not yet ready: master
        - one or more ClusterServiceVersions not yet ready: sriov-fec.v2.8.0
    observedGeneration: 1
    reason: InProgress
    status: "True"
    type: UpgradeInProgress
  observedGeneration: 1
  rollbackAvailabilityExpiration: "2024-05-19T14:01:52Z"
  validNextStages:
  - Rollback

OADP 运算符会创建 OADP 备份和恢复CR 中指定的数据备份，目标集群将重新启动。

通过运行以下命令监控 CR 的状态
```
$ oc get ibu -o yaml
```
如果您对升级满意，请通过运行以下命令将ImageBasedUpgrade CR 中的stage字段的值修补为Idle以完成更改
$ oc patch imagebasedupgrades.lca.openshift.io upgrade -p='{"spec": {"stage": "Idle"}}' --type=merge
升级后迁移到Idle阶段后，您将无法回滚更改。

生命周期代理将删除升级过程中创建的所有资源。
成功升级后，您可以删除 OADP 运算符及其配置文件。有关更多信息，请参阅“从集群中删除运算符”。

验证

通过运行以下命令检查ImageBasedUpgrade CR 的状态

$ oc get ibu -o yaml

示例输出

status:
  conditions:
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: In progress
    observedGeneration: 5
    reason: InProgress
    status: "False"
    type: Idle
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Prep completed
    observedGeneration: 5
    reason: Completed
    status: "False"
    type: PrepInProgress
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Prep completed successfully
    observedGeneration: 5
    reason: Completed
    status: "True"
    type: PrepCompleted
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Upgrade completed
    observedGeneration: 1
    reason: Completed
    status: "False"
    type: UpgradeInProgress
  - lastTransitionTime: "2024-01-01T09:00:00Z"
    message: Upgrade completed
    observedGeneration: 1
    reason: Completed
    status: "True"
    type: UpgradeCompleted
  observedGeneration: 1
  rollbackAvailabilityExpiration: "2024-01-01T09:00:00Z"
  validNextStages:
  - Idle
  - Rollback

通过运行以下命令检查集群恢复的状态

$ oc get restores -n openshift-adp -o custom-columns=NAME:.metadata.name,Status:.status.phase,Reason:.status.failureReason

示例输出

NAME             Status      Reason
acm-klusterlet   Completed   <none> (1)
apache-app       Completed   <none>
localvolume      Completed   <none>

1	`acm-klusterlet`仅适用于 RHACM 环境。

其他资源

迁移到使用生命周期代理的基于镜像升级的回滚阶段

如果升级在重新启动后未在initMonitorTimeoutSeconds字段中指定的时间范围内完成，则会启动自动回滚。

ImageBasedUpgrade CR 示例

apiVersion: lca.openshift.io/v1
kind: ImageBasedUpgrade
metadata:
  name: upgrade
spec:
  stage: Idle
  seedImageRef:
    version: 4.15.2
    image: <seed_container_image>
  autoRollbackOnFailure: {}
#    initMonitorTimeoutSeconds: 1800 (1)
# ...

1	可选：如果升级在第一次重新启动后的时间范围内未完成，则回滚的时间范围（以秒为单位）。如果未定义或设置为`0`，则使用默认值`1800`秒（30分钟）。

升级后遇到无法解决的问题，您可以手动回滚更改。

先决条件

您已以具有cluster-admin权限的用户身份登录到 hub 集群。
您已确保原始 stateroot 上的控制平面证书有效。如果证书过期，请参阅“从过期的控制平面证书中恢复”。

步骤

要迁移到回滚阶段，请通过运行以下命令将ImageBasedUpgrade CR 中的stage字段的值修补为Rollback
$ oc patch imagebasedupgrades.lca.openshift.io upgrade -p='{"spec": {"stage": "Rollback"}}' --type=merge
生命周期代理将使用先前安装的 OpenShift Container Platform 版本重新启动集群并恢复应用程序。
如果您对更改满意，请通过运行以下命令将ImageBasedUpgrade CR 中的stage字段的值修补为Idle以完成回滚
$ oc patch imagebasedupgrades.lca.openshift.io upgrade -p='{"spec": {"stage": "Idle"}}' --type=merge -n openshift-lifecycle-agent
回滚后迁移到Idle阶段，生命周期代理将清理可用于对失败升级进行故障排除的资源。

其他资源

从过期的控制平面证书中恢复

使用生命周期代理对基于镜像的升级进行故障排除

对受问题影响的托管集群执行故障排除步骤。

如果您使用ImageBasedGroupUpgrade CR 来升级集群，请确保在对托管集群执行故障排除或恢复步骤后，lcm.openshift.io/ibgu-<stage>-completed或lcm.openshift.io/ibgu-<stage>-failed集群标签已正确更新。这确保 TALM 继续管理集群的基于镜像的升级。

收集日志

您可以使用oc adm must-gather CLI 收集用于调试和故障排除的信息。

步骤

通过运行以下命令收集有关运算符的数据

$  oc adm must-gather \
  --dest-dir=must-gather/tmp \
  --image=$(oc -n openshift-lifecycle-agent get deployment.apps/lifecycle-agent-controller-manager -o jsonpath='{.spec.template.spec.containers[?(@.name == "manager")].image}') \
  --image=quay.io/konveyor/oadp-must-gather:latest \// (1)
  --image=quay.io/openshift/origin-must-gather:latest (2)

1	可选：如果您需要从 OADP 运算符收集更多信息，请添加此选项。
2	可选：如果您需要从 SR-IOV 运算符收集更多信息，请添加此选项。

AbortFailed 或 FinalizeFailed 错误

问题

在完成阶段或在准备阶段停止进程时，生命周期代理将清理以下资源：

不再需要的 Stateroot
预缓存资源
OADP CR
ImageBasedUpgrade CR

如果生命周期代理未能执行上述步骤，它将转换为AbortFailed或FinalizeFailed状态。条件消息和日志显示哪些步骤失败。

错误消息示例

message: failed to delete all the backup CRs. Perform cleanup manually then add 'lca.openshift.io/manual-cleanup-done' annotation to ibu CR to transition back to Idle
      observedGeneration: 5
      reason: AbortFailed
      status: "False"
      type: Idle

解决方案

检查日志以确定失败的原因。
要提示生命周期代理重试清理，请将lca.openshift.io/manual-cleanup-done注释添加到ImageBasedUpgrade CR。

观察到此注释后，生命周期代理将重试清理，如果成功，则ImageBasedUpgrade阶段将转换为Idle。

如果清理再次失败，您可以手动清理资源。

手动清理 stateroot

问题

在准备阶段停止时，生命周期代理将清理新的 stateroot。成功升级或回滚后完成时，生命周期代理将清理旧的 stateroot。如果此步骤失败，建议您检查日志以确定失败的原因。

解决方案

通过运行以下命令检查 stateroot 中是否存在任何现有部署
```
$ ostree admin status
```
如果存在任何现有部署，请运行以下命令清理现有部署
```
$ ostree admin undeploy <index_of_deployment>
```

清理 stateroot 的所有部署后，运行以下命令擦除 stateroot 目录

确保引导的部署不在此 stateroot 中。

$ stateroot="<stateroot_to_delete>"

$ unshare -m /bin/sh -c "mount -o remount,rw /sysroot && rm -rf /sysroot/ostree/deploy/${stateroot}"

手动清理 OADP 资源

问题: 由于生命周期代理和 S3 后端之间的连接问题，OADP 资源的自动清理可能会失败。通过恢复连接并添加lca.openshift.io/manual-cleanup-done注释，生命周期代理可以成功清理备份资源。
解决方案

通过运行以下命令检查后端连接

$ oc get backupstoragelocations.velero.io -n openshift-adp

示例输出

NAME                          PHASE       LAST VALIDATED   AGE   DEFAULT
dataprotectionapplication-1   Available   33s              8d    true

删除所有备份资源，然后将lca.openshift.io/manual-cleanup-done注释添加到ImageBasedUpgrade CR。

未恢复 LVM 存储卷内容

当使用 LVM 存储提供动态持久卷存储时，如果配置不正确，LVM 存储可能无法恢复持久卷内容。

备份 CR 中缺少与 LVM 存储相关的字段

问题

您的备份CR 可能缺少恢复持久卷所需的字段。您可以检查应用程序 pod 中的事件以确定是否出现此问题，方法是运行以下命令：

$ oc describe pod <your_app_name>

显示备份 CR 中缺少与 LVM 存储相关的字段的示例输出

Events:
  Type     Reason            Age                From               Message
  ----     ------            ----               ----               -------
  Warning  FailedScheduling  58s (x2 over 66s)  default-scheduler  0/1 nodes are available: pod has unbound immediate PersistentVolumeClaims. preemption: 0/1 nodes are available: 1 Preemption is not helpful for scheduling..
  Normal   Scheduled         56s                default-scheduler  Successfully assigned default/db-1234 to sno1.example.lab
  Warning  FailedMount       24s (x7 over 55s)  kubelet            MountVolume.SetUp failed for volume "pvc-1234" : rpc error: code = Unknown desc = VolumeID is not found

解决方案

您必须在应用程序备份CR 中包含logicalvolumes.topolvm.io。没有此资源，应用程序会正确恢复其持久卷声明和持久卷清单，但是，此持久卷关联的逻辑卷在枢轴后未正确恢复。

备份 CR 示例

apiVersion: velero.io/v1
kind: Backup
metadata:
  labels:
    velero.io/storage-location: default
  name: small-app
  namespace: openshift-adp
spec:
  includedNamespaces:
  - test
  includedNamespaceScopedResources:
  - secrets
  - persistentvolumeclaims
  - deployments
  - statefulsets
  includedClusterScopedResources: (1)
  - persistentVolumes
  - volumesnapshotcontents
  - logicalvolumes.topolvm.io

1	要恢复应用程序的持久卷，您必须按所示配置此部分。

恢复 CR 中缺少与 LVM 存储相关的字段

问题

升级后，应用程序的预期资源已恢复，但持久卷内容未保留。

通过运行以下命令在枢轴前列出应用程序的持久卷

$ oc get pv,pvc,logicalvolumes.topolvm.io -A

枢轴前的示例输出

NAME                        CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM            STORAGECLASS   REASON   AGE
persistentvolume/pvc-1234   1Gi        RWO            Retain           Bound    default/pvc-db   lvms-vg1                4h45m

NAMESPACE   NAME                           STATUS   VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
default     persistentvolumeclaim/pvc-db   Bound    pvc-1234   1Gi        RWO            lvms-vg1       4h45m

NAMESPACE   NAME                                AGE
            logicalvolume.topolvm.io/pvc-1234   4h45m

枢纽迁移后，请运行以下命令列出您应用程序的持久卷

$ oc get pv,pvc,logicalvolumes.topolvm.io -A

枢纽迁移后的示例输出

NAME                        CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM            STORAGECLASS   REASON   AGE
persistentvolume/pvc-1234   1Gi        RWO            Delete           Bound    default/pvc-db   lvms-vg1                19s

NAMESPACE   NAME                           STATUS   VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
default     persistentvolumeclaim/pvc-db   Bound    pvc-1234   1Gi        RWO            lvms-vg1       19s

NAMESPACE   NAME                                AGE
            logicalvolume.topolvm.io/pvc-1234   18s

解决方案

此问题的原因是logicalvolume状态未在Restore CR中保留。此状态非常重要，因为Velero需要它来引用在枢纽迁移后必须保留的卷。您必须在应用程序Restore CR中包含以下字段

示例Restore CR

apiVersion: velero.io/v1
kind: Restore
metadata:
  name: sample-vote-app
  namespace: openshift-adp
  labels:
    velero.io/storage-location: default
  annotations:
    lca.openshift.io/apply-wave: "3"
spec:
  backupName:
    sample-vote-app
  restorePVs: true (1)
  restoreStatus: (2)
    includedResources:
      - logicalvolumes

1	要保留应用程序的持久卷，必须将`restorePVs`设置为`true`。
2	要保留应用程序的持久卷，必须按如下所示配置此部分。

调试失败的备份和还原 CR

问题

工件的备份或还原失败。

解决方案

您可以使用 Velero CLI 工具调试Backup 和 Restore CR 并检索日志。与 OpenShift CLI 工具相比，Velero CLI 工具提供更详细的信息。

运行以下命令来描述包含错误的Backup CR

$ oc exec -n openshift-adp velero-7c87d58c7b-sw6fc -c velero -- ./velero describe backup -n openshift-adp backup-acm-klusterlet --details

运行以下命令来描述包含错误的Restore CR

$ oc exec -n openshift-adp velero-7c87d58c7b-sw6fc -c velero -- ./velero describe restore -n openshift-adp restore-acm-klusterlet --details

运行以下命令将备份的资源下载到本地目录

$ oc exec -n openshift-adp velero-7c87d58c7b-sw6fc -c velero -- ./velero backup download -n openshift-adp backup-acm-klusterlet -o ~/backup-acm-klusterlet.tar.gz