故障排除

请参阅以下流程来使用 must-gather 命令：

在断开连接的环境中，按照以下步骤运行 must-gather 命令：

如果您在当前支持的某个版本或产品文档时遇到问题，请访问 红帽支持，您可以在其中进行故障排除、查看知识库文章、与支持团队连接，或者创建一个问题单。您必须使用您的红帽凭证登录。

如果您在托管 control plane 集群时遇到问题，您可以运行 must-gather 命令来收集信息，以帮助您进行故障排除。

安装 MultiClusterHub 后已超过了十分钟，一个或多个来自 MultiClusterHub 资源的 status.components 字段的组件报告 ProgressDeadlineExceeded。这可能是集群中的资源限制的问题。

检查安装了 Multiclusterhub 的命名空间中的 pod。您可能会看到 Pending 状态，如下所示：

reason: Unschedulable
message: '0/6 nodes are available: 3 Insufficient cpu, 3 node(s) had taint {node-role.kubernetes.io/master:
        }, that the pod didn't tolerate.'

在这种情况下，集群中 worker 节点资源不足以运行该产品。

如果您有这个问题，则需要使用更大或多个 worker 节点来更新集群。如需了解调整集群大小的信息，请参阅调整集群大小。

尝试列出 ManagedClusterSet 和 ManagedClusterSetBinding 自定义资源定义后，会出现以下出错信息：

Error from server: request to convert CR from an invalid group/version: cluster.open-cluster-management.io/v1beta1

前面的消息表示，从 v1beta1 到 v1beta2 的 ManagedClusterSets 和 ManagedClusterSetBindings 自定义资源定义的迁移失败。

要解决这个问题，您必须手动启动 API 迁移。完成以下步骤：

oc get managedclusterset
oc get managedclustersetbinding -A

完成创建集群的步骤后，您无法从 Red Hat Advanced Cluster Management 控制台访问集群，集群的状态为离线（offline）。

完成导入集群的步骤后，您无法从 Red Hat Advanced Cluster Management for Kubernetes 控制台访问它。

在尝试导入集群后，有几个可能的原因会导致导入集群的不可用。如果集群导入失败，请完成以下步骤，直到找到失败导入的原因：

在使用 Red Hat Advanced Cluster Management 控制台导入一个集群后，出现在控制台中的集群带有 Pending import 状态。

将 OpenShift Container Platform 集群导入到 Red Hat Advanced Cluster Management MultiClusterHub 时会显示错误日志：

error log:
Warning: apiextensions.k8s.io/v1beta1 CustomResourceDefinition is deprecated in v1.16+, unavailable in v1.22+; use apiextensions.k8s.io/v1 CustomResourceDefinition
Error from server (AlreadyExists): error when creating "STDIN": customresourcedefinitions.apiextensions.k8s.io "klusterlets.operator.open-cluster-management.io" already exists
The cluster cannot be imported because its Klusterlet CRD already exists.
Either the cluster was already imported, or it was not detached completely during a previous detach process.
Detach the existing cluster before trying the import again."

运行以下命令，检查您要导入的集群中的任何与 Red Hat Advanced Cluster Management MultiClusterHub 相关的资源：

oc get all -n open-cluster-management-agent
oc get all -n open-cluster-management-agent-addon

使用以下命令删除 klusterlet 自定义资源：

oc get klusterlet | grep klusterlet | awk '{print $1}' | xargs oc patch klusterlet --type=merge -p '{"metadata":{"finalizers": []}}'

运行以下命令以删除预先存在的资源：

oc delete namespaces open-cluster-management-agent open-cluster-management-agent-addon --wait=false
oc get crds | grep open-cluster-management.io | awk '{print $1}' | xargs oc delete crds --wait=false
oc get crds | grep open-cluster-management.io | awk '{print $1}' | xargs oc patch crds --type=merge -p '{"metadata":{"finalizers": []}}'

在使用自签名证书在 Red Hat OpenStack Platform 上创建新的 Red Hat OpenShift Container Platform 集群后，集群会失败，并显示 unknown authority 错误。

受管集群的部署失败，并返回以下出错信息：

x509: certificate signed by unknown authority

验证是否已正确配置以下文件：

完成更新证书 secret 的步骤后，在线的一个或多个集群现在在控制台中显示 离线状态。

更新自定义 API 服务器证书信息后，在新证书前导入并运行的集群会处于 offline 状态。

表示证书有问题的错误会出现在离线受管集群的 open-cluster-management-agent 命名空间中的 pod 日志中。以下示例与日志中显示的错误类似：

请参阅以下 work-agent 日志：

E0917 03:04:05.874759       1 manifestwork_controller.go:179] Reconcile work test-1-klusterlet-addon-workmgr fails with err: Failed to update work status with err Get "https://api.aaa-ocp.dev02.location.com:6443/apis/cluster.management.io/v1/namespaces/test-1/manifestworks/test-1-klusterlet-addon-workmgr": x509: certificate signed by unknown authority
E0917 03:04:05.874887       1 base_controller.go:231] "ManifestWorkAgent" controller failed to sync "test-1-klusterlet-addon-workmgr", err: Failed to update work status with err Get "api.aaa-ocp.dev02.location.com:6443/apis/cluster.management.io/v1/namespaces/test-1/manifestworks/test-1-klusterlet-addon-workmgr": x509: certificate signed by unknown authority
E0917 03:04:37.245859       1 reflector.go:127] k8s.io/client-go@v0.19.0/tools/cache/reflector.go:156: Failed to watch *v1.ManifestWork: failed to list *v1.ManifestWork: Get "api.aaa-ocp.dev02.location.com:6443/apis/cluster.management.io/v1/namespaces/test-1/manifestworks?resourceVersion=607424": x509: certificate signed by unknown authority

请参阅以下 registration-agent 日志：

I0917 02:27:41.525026       1 event.go:282] Event(v1.ObjectReference{Kind:"Namespace", Namespace:"open-cluster-management-agent", Name:"open-cluster-management-agent", UID:"", APIVersion:"v1", ResourceVersion:"", FieldPath:""}): type: 'Normal' reason: 'ManagedClusterAvailableConditionUpdated' update managed cluster "test-1" available condition to "True", due to "Managed cluster is available"
E0917 02:58:26.315984       1 reflector.go:127] k8s.io/client-go@v0.19.0/tools/cache/reflector.go:156: Failed to watch *v1beta1.CertificateSigningRequest: Get "https://api.aaa-ocp.dev02.location.com:6443/apis/cluster.management.io/v1/managedclusters?allowWatchBookmarks=true&fieldSelector=metadata.name%3Dtest-1&resourceVersion=607408&timeout=9m33s&timeoutSeconds=573&watch=true"": x509: certificate signed by unknown authority
E0917 02:58:26.598343       1 reflector.go:127] k8s.io/client-go@v0.19.0/tools/cache/reflector.go:156: Failed to watch *v1.ManagedCluster: Get "https://api.aaa-ocp.dev02.location.com:6443/apis/cluster.management.io/v1/managedclusters?allowWatchBookmarks=true&fieldSelector=metadata.name%3Dtest-1&resourceVersion=607408&timeout=9m33s&timeoutSeconds=573&watch=true": x509: certificate signed by unknown authority
E0917 02:58:27.613963       1 reflector.go:127] k8s.io/client-go@v0.19.0/tools/cache/reflector.go:156: Failed to watch *v1.ManagedCluster: failed to list *v1.ManagedCluster: Get "https://api.aaa-ocp.dev02.location.com:6443/apis/cluster.management.io/v1/managedclusters?allowWatchBookmarks=true&fieldSelector=metadata.name%3Dtest-1&resourceVersion=607408&timeout=9m33s&timeoutSeconds=573&watch=true"": x509: certificate signed by unknown authority

如果您的受管集群是 local-cluster，或者您的受管集群是使用 Red Hat Advanced Cluster Management for Kubernetes 创建的，则必须等待 10 分钟或更长时间重新导入受管集群。

要立即重新导入受管集群，您可以删除 hub 集群上的受管集群导入 secret，并使用 Red Hat Advanced Cluster Management 重新导入它。运行以下命令:

oc delete secret -n <cluster_name> <cluster_name>-import

将 <cluster_name> 替换为您要导入的受管集群的名称。

如果要重新导入使用 Red Hat Advanced Cluster Management 导入的受管集群，请完成以下步骤以再次导入受管集群：

注：前面的步骤不会从 hub 集群中分离受管集群。步骤使用受管集群中的当前设置更新所需的清单，包括新证书信息。

删除受管集群后，命名空间没有被删除。

完成以下步骤以手动删除命名空间：

当导入 hive 集群以进行管理时，会显示 auto-import-secret already exists 错误。

当您试图导入之前由 Red Hat Advanced Cluster Management 管理的集群时，会出现这种情况。如果出现这种情况，当您尝试重新导入集群时，secret 会发生冲突。

要临时解决这个问题，请完成以下步骤：

您可以将 VolSync ReplicationSource 或 ReplicationDestination 配置为使用快照。另外，您可以在 ReplicationSource 和 ReplicationDestination 中配置 storageclass 和 volumesnapshotclass。cinder volumesnapshotclass 上有一个参数，名为 force-create，默认值为 false。volumesnapshotclass 上的 force-create 参数意味着 cinder 不允许将 volumesnapshot 视为使用中的 PVC。因此，volumesnapshot 处于错误状态。

您可能会遇到多集群全局 hub 的各种错误。您可以运行 must-gather 命令来排除多集群全局 hub 的问题。

运行 must-gather 命令来收集详情、日志并采取调试问题的步骤。当您请求支持时，这个调试信息会很有用。oc adm must-gather CLI 命令会收集解决问题通常需要的集群信息，包括：

您可能会遇到多集群全局 hub 的各种错误。您可以访问置备的 PostgreSQL 数据库来查看对多集群全局 hub 问题进行故障排除的信息。

There are two ways to access the provisioned PostgreSQL database.

您可能会遇到多集群全局 hub 的各种错误。您可以使用数据库转储和恢复来排除多集群全局 hub 的问题。

有时您需要转储多集群全局 hub 数据库中的输出，以调试问题。PostgreSQL 数据库提供 pg_dump 命令行工具来转储数据库的内容。要转储 localhost 数据库服务器的数据，请运行以下命令：

pg_dump hoh > hoh.sql

要转储位于带有压缩格式的远程服务器中的多集群全局 hub 数据库，请使用命令行选项控制连接详情，如下例所示：

pg_dump -h my.host.com -p 5432 -U postgres -F t hoh -f hoh-$(date +%d-%m-%y_%H-%M).tar

要恢复 PostgreSQL 数据库，您可以使用 psql 或 pg_restore 命令行工具。psql 工具用于恢复 pg_dump 创建的纯文本文件：

psql -h another.host.com -p 5432 -U postgres -d hoh < hoh.sql

pg_restore 工具用于在其中一个非纯文本格式(custom、tar 或目录)中从 pg_dump 创建的存档中恢复 PostgreSQL 数据库：

pg_restore -h another.host.com -p 5432 -U postgres -d hoh hoh-$(date +%d-%m-%y_%H-%M).tar

当将受管集群连接到 hub 集群的网络不稳定时，hub 集群所报告的受管集群的状态在离线和可用之间不断转换。

hub 集群和受管集群之间的连接通过租期维护，该租期在 leaseDurationSeconds 间隔值验证。如果租期没有在 leaseDurationSeconds 值的五个连续尝试中验证，则集群被标记为 offline。

例如，集群在五分钟后标记为 离线，其中 leaseDurationSeconds 间隔为 60 秒。由于连接问题或延迟等原因，此配置可能不足，从而导致不稳定。

五个验证尝试是默认设置且无法更改，但您可以更改 leaseDurationSeconds 间隔。

确定您希望集群标记为 离线 的时间（以分钟为单位），然后将该值乘以 60 以转换为秒。然后，按默认的五次尝试次数划分。结果是您的 leaseDurationSeconds 值。

在使用 Red Hat Advanced Cluster Management 控制台创建一个新集群后，在控制台中集群会一直显示Pending 或 Failed 状态。

如果集群显示 Failed 状态，进入集群的详情页面并使用提供的日志的链接。如果没有找到日志或集群显示 Pending 状态，请按照以下步骤检查日志：

在日志中找到错误后，确定如何在销毁集群并重新创建它之前解决相关的错误。

以下示例包括了一个选择不支持的区的日志错误，以及解决它所需的操作：

No subnets provided for zones

When you created your cluster, you selected one or more zones within a region that are not supported.在重新创建集群时完成以下操作之一以解决此问题：

在处理了日志中记录的问题后，销毁集群并重新创建它。

如需了解更多与创建集群 相关的信息，请参阅创建集群。

如果您在 Grafana explorer 中查询一些耗时的指标时遇到 Gateway Time-out 错误，则超时可能是由 open-cluster-management-observability 命名空间中的 Grafana 造成的。

如果您有这个问题，请完成以下步骤：

刷新 Grafana 页面，并尝试再次查询指标。网关超时错误不再显示。

所有受管集群都使用放置规则选择，但 local-cluster 不是。放置规则用户没有在 local-cluster 命名空间中获取 managedcluster 资源的权限。

已弃用： PlacementRule

要解决这个问题，您需要在 local-cluster 命名空间中授予 managedcluster 管理权限。完成以下步骤：

如果 Subscription YAML 文件中的一个或多个应用程序资源使用弃用的 API，您可能会收到与以下类似的错误信息：

failed to install release: unable to build kubernetes objects from release manifest: unable to recognize "": no matches for
kind "Deployment" in version "extensions/v1beta1"

或者，带有新 Kubernetes API 版本的 YAML 文件名为 old.yaml，您可能会收到以下错误：

error: unable to recognize "old.yaml": no matches for kind "Deployment" in version "deployment/v1beta1"

在受管集群中部署 Klusterlet 后，KlusterletRegistrationDegraded 或 KlusterletWorkDegraded 条件会显示 True 的状态。

请查看以下降级状态列表，以及如何尝试解决这些问题：

Object 存储频道的订阅无法自动获取更新的 secret。这可会阻止订阅 operator 协调并将资源从对象存储部署到受管集群的过程。

您需要手动输入凭证来创建 secret，然后引用频道中的 secret。

运行命令后，您可以进入 Application 控制台以验证资源是否已部署到受管集群。或者您可以登录到受管集群，以查看应用程序资源是否在给定命名空间中创建。

如果在安装并创建 Observability 自定义资源定义 (CRD) 后，可观察性 (observability) 状态会一直处于 Installing 状态，则可能是因为没有为 spec:storageConfig:storageClass 参数定义值。或者，可观察性组件自动找到默认的 storageClass，但如果没有存储值，则组件会停留在 Installing 状态下。

如果您有这个问题，请完成以下步骤：

storageclass.kubernetes.io/is-default-class: "true"

安装完成后，可观察组件状态会被更新为 Ready 状态。如果安装无法完成，则会显示 Fail 状态。

endpoint-observability-operator-x pod 会检查 prometheus-k8s 服务是否在 openshift-monitoring 命名空间中可用。如果这个服务没有出现在 openshift-monitoring 命名空间中，则不会部署 metrics-collector。您可能会收到以下出错信息：Failed to get prometheus resource。

如果您有这个问题，请完成以下步骤：

可能有一个受管集群，其中的指标不可用。如果出现这种情况，您可能会从 metrics-collector 部署中收到以下错误：

error: response status code is 500 Internal Server Error, response body is x509: certificate signed by unknown authority (possibly because of "crypto/rsa: verification error" while trying to verify candidate authority certificate "observability-client-ca-certificate")

如果您有这个问题，请完成以下步骤：

重新创建 metrics-collector 部署并更新 observability-controller-open-cluster-management.io-observability-signer-client-cert secret。

错误消息重装以下内容会出现在 search-api 日志中：ERROR: could not resize shared memory segment "/PostgreSQL.1083654800" to 25031264 bytes: No space left on device (SQLSTATE 53100)

要解决这个问题，更新 search-postgres ConfigMap 中找到的 PostgreSQL 资源。完成以下步骤以更新资源：

有关添加环境变量的更多信息，请参阅 搜索自定义和配置。

Thanos compactor 会停止，因为持久性卷声明(PVC)中没有剩余空间。您会收到以下信息：

ts=2024-01-24T15:34:51.948653839Z caller=compact.go:491 level=error msg="critical error detected; halting" err="compaction: group 0@5827190780573537664: compact blocks [ /var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE]: 2 errors: populate block: add series: write series data: write /var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE.tmp-for-creation/index: no space left on device; write /var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE.tmp-for-creation/index: no space left on device"

要解决这个问题，增大 Thanos compactor PVC 的存储空间。完成以下步骤：

Thanos compactor 会停止，因为您已损坏的块。您可能会收到以下输出，其中 01HKZYEZ2DVDQXF1STVEXAMPLE 块已损坏：

ts=2024-01-24T15:34:51.948653839Z caller=compact.go:491 level=error msg="critical error detected; halting" err="compaction: group 0@15699422364132557315: compact blocks [/var/thanos/compact/compact/0@15699422364132557315/01HKZGQGJCKQWF3XMA8EXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HKZQK7TD06J2XWGR5EXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HKZYEZ2DVDQXF1STVEXAMPLE /var/thanos/compact/compact/0@15699422364132557315/01HM05APAHXBQSNC0N5EXAMPLE]: populate block: chunk iter: cannot populate chunk 8 from block 01HKZYEZ2DVDQXF1STVEXAMPLE: segment index 0 out of range"

在对象存储配置中添加 thanos bucket verify 命令。完成以下步骤：

在安装后，Submariner 网络不会被通信。

如果在部署 Submariner 后没有建立网络连接，请开始故障排除步骤。请注意，部署 Submariner 的过程可能需要几分钟时间。

当 Submariner 在部署后无法正常工作时，请完成以下步骤：

当端到端数据平面测试失败时，Submariner 测试显示 连接器 pod 可以连接到 监听程序 pod，但后续 连接器 pod 会一直处于 侦听 阶段。

最大传输单元(MTU)可能会导致端到端数据平面测试失败。例如，MTU 可能会导致互联网协议安全(IPsec) 的集群间通信 失败。通过运行使用小数据包大小的端到端数据平面测试来验证 MTU 是否为故障。

要运行这类测试，请在 Submariner 工作区中运行以下命令：

subctl verify --verbose --only connectivity --context <from_context> --tocontext <to_context> --image-override submariner-nettest=quay.io/submariner/nettest:devel --packet-size 200

如果测试使用这个小数据包大小成功，您可以通过设置传输控制协议(TCP)最大片段大小(MSS)来解决连接问题。通过完成以下步骤设置 TCP MSS：

如果容器网络接口(CNI)是 OpenShiftSDN，或者将虚拟可扩展 local-area 网络(VXLAN)用于 集群 隧道，则端到端数据平面测试可能会失败。

硬件的用户数据报 Protocal (UDP)校验和计算中存在一个错误，可能是裸机集群的端到端数据平面测试失败的一个根本原因。要排除这个程序错误，请通过应用以下 YAML 文件来禁用硬件卸载：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: disable-offload
  namespace: submariner-operator
spec:
  selector:
    matchLabels:
      app: disable-offload
  template:
    metadata:
      labels:
        app: disable-offload
    spec:
      tolerations:
      - operator: Exists
      containers:
        - name: disable-offload
          image: nicolaka/netshoot
          imagePullPolicy: IfNotPresent
          securityContext:
            allowPrivilegeEscalation: true
            capabilities:
              add:
              - net_admin
              drop:
              - all
            privileged: true
            readOnlyRootFilesystem: false
            runAsNonRoot: false
          command: ["/bin/sh", "-c"]
          args:
            - ethtool --offload vxlan-tunnel rx off tx off;
              ethtool --offload vx-submariner rx off tx off;
sleep infinity
      restartPolicy: Always
      securityContext: {}
      serviceAccount: submariner-routeagent
      serviceAccountName: submariner-routeagent
      hostNetwork: true

Red Hat Advanced Cluster Management 显示 FinishedWithErrors 状态，由 Red Hat Advanced Cluster Management 恢复所创建的一个或多个 Velero 恢复资源显示 PartiallyFailed 状态。

如果您从空备份中恢复，可以安全地忽略 FinishedWithErrors 状态。

Red Hat Advanced Cluster Management for Kubernetes 恢复显示所有 Velero 恢复资源的累积状态。如果一个状态是 PartiallyFailed，另一个状态为 Completed，则您会看到累积的状态 PartiallyFailed，代表至少有一个问题。

要解决这个问题，请检查所有带有 PartiallyFailed 状态的单独 Velero 恢复资源的状态，并查看日志以了解更多详情。您可以直接从对象存储获取日志，或使用 DownloadRequest 自定义资源从 OADP Operator 下载它。

要从控制台创建 DownloadRequest，请完成以下步骤：

当受管集群和 hub 集群与证书数据进行隐藏的集群时，则内容不会被解析为模板 JSON 字符串。您可能会收到以下出错信息：

message: >-
            [spec.tls.caCertificate: Invalid value: "redacted ca certificate
            data": failed to parse CA certificate: data does not contain any
            valid RSA or ECDSA certificates, spec.tls.certificate: Invalid
            value: "redacted certificate data": data does not contain any valid
            RSA or ECDSA certificates, spec.tls.key: Invalid value: "": no key specified]

配置证书策略，以获取 hub 集群和受管集群 fromSecret 值。使用 autoindent 功能更新您的证书策略，其内容如下：

                 tls:
                    certificate: |
                      {{ print "{{hub fromSecret "open-cluster-management" "minio-cert" "tls.crt" hub}}" | base64dec | autoindent }}