第 9 章 故障排除

本节论述了对 Migration Toolkit for Containers(MTC)进行故障排除的资源。

有关已知问题,请参阅 MTC 发行注记

9.1. 日志和调试工具

本节论述了可用于故障排除的日志和调试工具。

9.1.1. 查看迁移计划资源

您可以使用 MTC web 控制台和命令行界面(CLI)查看迁移计划资源来监控正在运行的迁移或排除迁移失败的问题。

流程

  1. 在 MTC web 控制台中点 Migration Plans
  2. 点迁移计划旁边的 Migrations 编号来查看 Migrations 页面。

    Migrations 页面显示与迁移计划关联的迁移类型,如 StageMigrationRollback

  3. Type 链接查看 Migration 详情页面。
  4. 扩展 Migration resources 以查看迁移资源及其状态。

    注意

    要对失败的迁移进行故障排除,请从失败的高级别资源开始,然后向下级资源组成资源树。

  5. 点击资源 kebab 旁边的 Options 菜单并选择以下选项之一:

    • 复制 oc describe 命令将命令复制到您的剪贴板。

      • 登录相关集群,然后运行命令。

        资源的条件和事件以 YAML 格式显示。

    • 复制 oc logs 命令将命令复制到您的剪贴板。

      • 登录相关集群,然后运行命令。

        如果资源支持日志过滤,则会显示过滤的日志。

    • View JSON 在 Web 浏览器中以 JSON 格式显示资源数据。

      其数据与 oc get <resource> 命令的输出结果相同。

9.1.2. 查看迁移计划日志

您可以查看迁移计划的聚合日志。您可以使用 MTC web 控制台将命令复制到剪贴板中,然后从命令行界面(CLI)运行命令。

该命令显示以下 pod 的过滤日志:

  • Migration Controller
  • Velero
  • Restic
  • Rsync
  • Stunnel
  • 容器镜像仓库(Registry)

流程

  1. 在 MTC web 控制台中点 Migration Plans
  2. 点迁移计划旁边的 Migrations 编号来查看 Migrations 页面。
  3. 在迁移旁边,单击 View logs
  4. 点击 Copy 图标将 oc logs 命令复制到您的剪贴板。
  5. 登录到相关的集群并在 CLI 中输入命令。

    此时会显示迁移计划的聚合日志。

9.1.3. 使用迁移日志读取器

您可以使用迁移日志读取器显示所有迁移日志的过滤视图。

流程

  1. 获取 mig-log-reader pod:

    $ oc -n openshift-migration get pods | grep log
  2. 输入以下命令显示单个迁移日志:

    $ oc -n openshift-migration logs -f <mig-log-reader-pod> -c color 1
    1
    -c plain 选项显示没有颜色的日志。

9.1.4. 使用 must-gather 工具

您可以使用 must-gather 工具来收集 MTC 自定义资源的日志、指标和相关信息。

must-gather 数据必须附加到所有客户案例。

您可以收集 1 小时或 24 小时内的数据,并使用 Prometheus 控制台查看数据。

先决条件

  • 您必须使用具有 cluster-admin 角色的用户登录到 OpenShift Container Platform 集群。
  • 已安装 OpenShift CLI (oc)。

流程

  1. 进入要存储 must-gather 数据的目录。
  2. 运行 oc adm must-gather 命令:

    • 为过去几小时收集数据:

      $ oc adm must-gather --image=registry.redhat.io/rhmtc/openshift-migration-must-gather-rhel8:v1.5

      数据被保存为 /must-gather/must-gather.tar.gz。您可以将此文件上传到红帽客户门户网站中的支持问题单中。

    • 为过去 24 小时收集数据:

      $ oc adm must-gather --image= \
        registry.redhat.io/rhmtc/openshift-migration-must-gather-rhel8: \
        v1.5 -- /usr/bin/gather_metrics_dump

      此操作可能需要很长时间。数据保存为 /must-gather/metrics/prom_data.tar.gz。您可以使用 Prometheus 控制台查看此文件。

使用 Prometheus 控制台查看数据

  1. 创建本地 Prometheus 实例:

    $ make prometheus-run

    命令输出 Prometheus URL:

    输出。

    Started Prometheus on http://localhost:9090

  2. 启动 Web 浏览器,再导航到 URL 以使用 Prometheus Web 控制台查看数据。
  3. 查看数据后,删除 Prometheus 实例和数据:

    $ make prometheus-cleanup

9.1.5. 使用 Velero CLI 调试备份和恢复 CR

您可以使用 Velero 命令行界面(CLI)调试 BackupRestore 自定义资源(CR)和迁移部分失败的情况。Velero CLI 在 velero pod 中运行。

9.1.5.1. Velero 命令语法

Velero CLI 命令使用以下语法:

$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero <resource> <command> <resource_id>

您可以在 $(oc get pods -n openshift-migration -o name | grep velero) 中指定 velero-<pod> -n openshift-migration

9.1.5.2. help 命令

Velero help 命令列出所有 Velero CLI 命令:

$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero --help

9.1.5.3. describe 命令

Velero describe 命令提供了与 Velero 资源相关的警告和错误概述信息:

$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero  <resource> describe <resource_id>

示例

$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero backup describe 0e44ae00-5dc3-11eb-9ca8-df7e5254778b-2d8ql

9.1.5.4. logs 命令

Velero logs 命令提供与 Velero 资源关联的日志:

velero <resource> logs <resource_id>

示例

$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero restore logs ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf

9.1.6. 调试部分迁移失败

您可以使用 Velero CLI 检查 Restore 自定义资源(CR)日志来调试部分迁移失败警告消息。

当 Velero 遇到没有导致迁移失败的问题时,会导致迁移部分失败。例如,缺少自定义资源定义(CRD),或者源集群和目标集群的 CRD 版本之间存在冲突,则迁移会完成,但不会在目标集群上创建 CR。

Velero 将问题作为部分失败记录,然后处理 备份 CR 中的其他对象。

流程

  1. 检查 MigMigration CR 的状态:

    $ oc get migmigration <migmigration> -o yaml

    输出示例

    status:
      conditions:
      - category: Warn
        durable: true
        lastTransitionTime: "2021-01-26T20:48:40Z"
        message: 'Final Restore openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf: partially failed on destination cluster'
        status: "True"
        type: VeleroFinalRestorePartiallyFailed
      - category: Advisory
        durable: true
        lastTransitionTime: "2021-01-26T20:48:42Z"
        message: The migration has completed with warnings, please look at `Warn` conditions.
        reason: Completed
        status: "True"
        type: SucceededWithWarnings

  2. 使用 Velero describe 命令检查 Restore CR 的状态:

    $ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -n openshift-migration -- ./velero restore describe <restore>

    输出示例

    Phase:  PartiallyFailed (run 'velero restore logs ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf' for more information)
    
    Errors:
      Velero:     <none>
      Cluster:    <none>
      Namespaces:
        migration-example:  error restoring example.com/migration-example/migration-example: the server could not find the requested resource

  3. 使用 Velero logs 命令检查 Restore CR 日志:

    $ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -n openshift-migration -- ./velero restore logs <restore>

    输出示例

    time="2021-01-26T20:48:37Z" level=info msg="Attempting to restore migration-example: migration-example" logSource="pkg/restore/restore.go:1107" restore=openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf
    time="2021-01-26T20:48:37Z" level=info msg="error restoring migration-example: the server could not find the requested resource" logSource="pkg/restore/restore.go:1170" restore=openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf

    Restore CR 会记录日志错误消息, the server could not find the requested resource,代表迁移部分失败的原因。

9.1.7. 使用 MTC 自定义资源进行故障排除

您可以检查以下 MTC 自定义资源(CR)来排除迁移失败的问题:

  • MigCluster
  • MigStorage
  • MigPlan
  • BackupStorageLocation

    BackupStorageLocation CR 包含一个 migrationcontroller 标签,用于标识创建 CR 的 MTC 实例:

        labels:
          migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93
  • VolumeSnapshotLocation

    VolumeSnapshotLocation CR 包含一个 migrationcontroller 标签,用于标识创建 CR 的 MTC 实例:

        labels:
          migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93
  • MigMigration
  • Backup

    在目标集群中,MTC 将迁移的持久性卷(PV)的重新声明策略设置为 RetainBackup CR 包含 openshift.io/orig-reclaim-policy 注解,用于指示原始重新声明策略。您可以手动恢复迁移 PV 的重新声明策略。

  • 恢复

流程

  1. 列出 openshift-migration 命名空间中的 MigMigration CR:

    $ oc get migmigration -n openshift-migration

    输出示例

    NAME                                   AGE
    88435fe0-c9f8-11e9-85e6-5d593ce65e10   6m42s

  2. 检查 MigMigration CR:

    $ oc describe migmigration 88435fe0-c9f8-11e9-85e6-5d593ce65e10 -n openshift-migration

    输出结果类似以下示例。

MigMigration 示例输出

name:         88435fe0-c9f8-11e9-85e6-5d593ce65e10
namespace:    openshift-migration
labels:       <none>
annotations:  touch: 3b48b543-b53e-4e44-9d34-33563f0f8147
apiVersion:  migration.openshift.io/v1alpha1
kind:         MigMigration
metadata:
  creationTimestamp:  2019-08-29T01:01:29Z
  generation:          20
  resourceVersion:    88179
  selfLink:           /apis/migration.openshift.io/v1alpha1/namespaces/openshift-migration/migmigrations/88435fe0-c9f8-11e9-85e6-5d593ce65e10
  uid:                 8886de4c-c9f8-11e9-95ad-0205fe66cbb6
spec:
  migPlanRef:
    name:        socks-shop-mig-plan
    namespace:   openshift-migration
  quiescePods:  true
  stage:         false
status:
  conditions:
    category:              Advisory
    durable:               True
    lastTransitionTime:  2019-08-29T01:03:40Z
    message:               The migration has completed successfully.
    reason:                Completed
    status:                True
    type:                  Succeeded
  phase:                   Completed
  startTimestamp:         2019-08-29T01:01:29Z
events:                    <none>

Velero 备份 CR #2 示例输出来描述 PV 数据

apiVersion: velero.io/v1
kind: Backup
metadata:
  annotations:
    openshift.io/migrate-copy-phase: final
    openshift.io/migrate-quiesce-pods: "true"
    openshift.io/migration-registry: 172.30.105.179:5000
    openshift.io/migration-registry-dir: /socks-shop-mig-plan-registry-44dd3bd5-c9f8-11e9-95ad-0205fe66cbb6
    openshift.io/orig-reclaim-policy: delete
  creationTimestamp: "2019-08-29T01:03:15Z"
  generateName: 88435fe0-c9f8-11e9-85e6-5d593ce65e10-
  generation: 1
  labels:
    app.kubernetes.io/part-of: migration
    migmigration: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6
    migration-stage-backup: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6
    velero.io/storage-location: myrepo-vpzq9
  name: 88435fe0-c9f8-11e9-85e6-5d593ce65e10-59gb7
  namespace: openshift-migration
  resourceVersion: "87313"
  selfLink: /apis/velero.io/v1/namespaces/openshift-migration/backups/88435fe0-c9f8-11e9-85e6-5d593ce65e10-59gb7
  uid: c80dbbc0-c9f8-11e9-95ad-0205fe66cbb6
spec:
  excludedNamespaces: []
  excludedResources: []
  hooks:
    resources: []
  includeClusterResources: null
  includedNamespaces:
  - sock-shop
  includedResources:
  - persistentvolumes
  - persistentvolumeclaims
  - namespaces
  - imagestreams
  - imagestreamtags
  - secrets
  - configmaps
  - pods
  labelSelector:
    matchLabels:
      migration-included-stage-backup: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6
  storageLocation: myrepo-vpzq9
  ttl: 720h0m0s
  volumeSnapshotLocations:
  - myrepo-wv6fx
status:
  completionTimestamp: "2019-08-29T01:02:36Z"
  errors: 0
  expiration: "2019-09-28T01:02:35Z"
  phase: Completed
  startTimestamp: "2019-08-29T01:02:35Z"
  validationErrors: null
  version: 1
  volumeSnapshotsAttempted: 0
  volumeSnapshotsCompleted: 0
  warnings: 0

Velero 恢复 CR #2 示例输出来描述 Kubernetes 资源

apiVersion: velero.io/v1
kind: Restore
metadata:
  annotations:
    openshift.io/migrate-copy-phase: final
    openshift.io/migrate-quiesce-pods: "true"
    openshift.io/migration-registry: 172.30.90.187:5000
    openshift.io/migration-registry-dir: /socks-shop-mig-plan-registry-36f54ca7-c925-11e9-825a-06fa9fb68c88
  creationTimestamp: "2019-08-28T00:09:49Z"
  generateName: e13a1b60-c927-11e9-9555-d129df7f3b96-
  generation: 3
  labels:
    app.kubernetes.io/part-of: migration
    migmigration: e18252c9-c927-11e9-825a-06fa9fb68c88
    migration-final-restore: e18252c9-c927-11e9-825a-06fa9fb68c88
  name: e13a1b60-c927-11e9-9555-d129df7f3b96-gb8nx
  namespace: openshift-migration
  resourceVersion: "82329"
  selfLink: /apis/velero.io/v1/namespaces/openshift-migration/restores/e13a1b60-c927-11e9-9555-d129df7f3b96-gb8nx
  uid: 26983ec0-c928-11e9-825a-06fa9fb68c88
spec:
  backupName: e13a1b60-c927-11e9-9555-d129df7f3b96-sz24f
  excludedNamespaces: null
  excludedResources:
  - nodes
  - events
  - events.events.k8s.io
  - backups.velero.io
  - restores.velero.io
  - resticrepositories.velero.io
  includedNamespaces: null
  includedResources: null
  namespaceMapping: null
  restorePVs: true
status:
  errors: 0
  failureReason: ""
  phase: Completed
  validationErrors: null
  warnings: 15

用于调试工具的其他资源