问题排查简介

如果您在使用 Config Sync 时遇到问题，本页面将向您介绍一些常见工具和步骤，可帮助您找出并解决所遇到的问题。

升级到受支持的版本

考虑升级 Config Sync 到受支持的版本。升级通常可以解决常见问题，并让您能够使用最新的功能。

使用 nomos 命令行工具

nomos 命令行工具可提供有关 Config Sync 设置的重要数据分析。在您尝试确定问题来源或需要与 Cloud Customer Care 联系时，以下各部分中介绍的命令特别有用。

查看 Config Sync 状态

nomos status 命令为您提供汇总数据和错误，帮助您了解 Config Sync 安装发生的情况。以下信息可通过 nomos status 获得：

• 每个集群的安装状态
• 同步错误（从 Git 读取和协调更改）

创建错误报告

如果您在使用 Config Sync 时遇到问题，需要 Cloud Customer Care 的帮助，您可以使用 nomos bugreport 命令向他们提供有价值的调试信息。

此命令会生成一个带有时间戳的 ZIP 文件，其中包含有关在 kubectl 上下文中设置的 Kubernetes 集群的信息。该文件包含来自 Config Sync Pod 的日志，但不包含来自与 Config Sync 同步的资源的信息。

查看概览信息中心

Config Sync 信息中心可让您大致了解 Config Sync 管理的软件包的状态以及这些软件包中的资源的状态。探索此信息中心可帮助您快速了解 Config Sync 安装的状态，并发现任何存在问题的软件包。

• 如需访问信息中心，请在 Google Cloud 控制台中前往功能部分中的配置页面：

  转到“配置”

使用监控和日志分析

监控 Config Sync 并探索其日志有助于您确定 bug 的来源，并更好地了解任何意外行为。

了解 Config Sync 指标

使用 Config Sync 指标可了解 Config Sync 的健康状况。

监控 RootSync 和 RepoSync 对象

当您使用 Google Cloud 控制台或 Google Cloud CLI 安装 Config Sync 时，Config Sync 会自动为您创建 RootSyncRootSync 对象。配置从多个仓库同步时，您可以创建 RepoSync 对象 RepoSyncRepoSync，其中包含有关命名空间仓库的配置信息。

监控这些对象可以揭示有关 Config Sync 状态的重要信息。如需了解详情，请参阅监控 RootSync 和 RepoSync 对象。

使用服务等级指标 (SLI)

如需在 Config Sync 未按预期工作时收到通知，请使用 Config Sync SLI。

查询日志

您可以使用 Logs Explorer 来检索、查看和分析 Config Sync 的日志数据。这些日志可能包含在操作器或协调器 Pod 重启时，nomos bugreport 未能捕获的有价值历史数据。如需查看有助于诊断问题的查询示例，请参阅查询 Config Sync 日志。

使用 kubectl 命令行工具检查资源

Config Sync 由多个自定义资源组成，您可以使用 kubectl 命令查询这些资源。这些命令可帮助您了解 Config Sync 的每个对象的状态。

您应该了解 Config Sync 管理的 Kubernetes 资源的以下信息：

• config-management-system 是用于运行 Config Sync 所有核心系统组件的命名空间。
• configmanagement.gke.io 和 configsync.gke.io 是我们用于所有自定义资源的 API 组。

示例

以下各部分介绍了如何使用 kubectl 命令检查 Config Sync。

列出自定义资源

• 通过运行以下命令，您可以获取自定义资源的完整列表：

  kubectl api-resources | grep -E "configmanagement.gke.io|configsync.gke.io"
  

• 通过运行以下命令，可以使用各个自定义资源：

  kubectl get RESOURCE -o yaml.
  

  将 RESOURCE 替换为您要查询的资源的名称。

  例如，以下命令的输出使您可以检查 RootSync 对象的状态：

  kubectl get rootsync -n config-management-system -o yaml
  

检查对象的令牌注释

您可能希望了解 Config Sync 上次更新托管 Kubernetes 对象的时间。每个托管式对象都会使用上次修改时 Git 提交的哈希值以及包含修改内容的配置的路径进行注解。

例如，如需获取名为 namespace-readers 的 ClusterRoleBinding 的注解，请运行以下命令：

kubectl get clusterrolebinding namespace-readers

输出类似于以下内容：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/source-path: cluster/namespace-reader-clusterrolebinding.yaml
    configmanagement.gke.io/token: bbb6a1e2f3db692b17201da028daff0d38797771
  name: namespace-readers
...

如需了解详情，请参阅标签和注释。

借助 Gemini Cloud Assist 加快诊断速度

预览版

此产品或功能 受服务专用条款的约束。 非正式版产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

有时，即使您使用了前几部分中探讨的工具，问题的根本原因也不会立即显现出来。调查复杂案例可能非常耗时，并且需要深厚的专业知识。对于这种情况，Gemini Cloud Assist 可以提供帮助。它可以自动检测隐藏的模式、发现异常情况并提供摘要，帮助您快速查明可能的原因。

作为一项尚处于发展早期的技术，Gemini for Google Cloud产品可能会生成看似合理但实际上不正确的输出。我们建议您在使用 Gemini for Google Cloud 产品的输出前先进行验证。 如需了解详情，请参阅 Gemini for Google Cloud 和 Responsible AI。

访问 Gemini Cloud Assist

如需访问 Gemini Cloud Assist，请完成以下步骤：

1. 在 Google Cloud 控制台中，前往任意页面。

2. 在 Google Cloud 控制台工具栏中，点击打开或关闭 Gemini Cloud Assist 对话。

   系统将打开 Cloud Assist 面板。您可以点击显示的示例提示，也可以在输入提示字段中输入提示。

探索示例提示

为帮助您了解 Gemini Cloud Assist 的用途，下面提供了一些示例提示：

主题	场景	提示示例	Gemini Cloud Assist 可以提供哪些帮助
初始设置	一位平台工程师正在首次设置 Config Sync，以便能够通过 Git 代码库管理 GKE 集群。	如何设置 Config Sync 以将清单从我的 GitHub 代码库同步到我的 GKE 集群？	Gemini Cloud Assist 提供有关设置 Config Sync 的分步指南，其中涵盖了舰队注册和启用该功能，并详细说明了代码库网址、分支、路径和身份验证方法（例如 public、token 或 ssh）。
排查同步错误	开发者提交了新清单，但资源未能应用于集群，并且同步状态显示了错误代码。	我的 Config Sync RootSync 对象显示“KNV2009: the server could not find the requested resource”。这是什么意思？如何解决此问题？	Gemini Cloud Assist 会分析该错误代码，并说明该错误代码通常表示 Config Sync 无法找到或与预期的 Kubernetes 资源互动。然后，它会详细说明常见原因，包括缺少 RBAC 权限、超出资源对象大小限制、目录路径不正确、外部清单冲突以及非受管资源存在问题，并针对每种原因提供具体的问题排查步骤。
管理多个团队	组织需要允许应用团队在特定命名空间中管理自己的配置，而无需向其授予对中央平台代码库的访问权限。	在 Config Sync 中，RootSync 对象和 RepoSync 对象有何区别？我应该在什么情况下使用 RepoSync？	Gemini Cloud Assist 解释了 RootSync 对象和 RepoSync 对象之间的核心区别：RootSync 对象是集群级对象，通常由管理员用于集群范围的配置；而 RepoSync 对象是命名空间级对象，专为应用团队设计，用于管理特定命名空间内的资源，从而促进委托和多租户。 Gemini Cloud Assist 还详细介绍了应使用 RepoSync 对象的情景，强调了它在多租户方面的优势，并可减少错误配置的影响面。
主动验证	某开发者希望在将新清单提交到代码库之前确保其有效，以免在生产环境中中断同步。	在将 Kubernetes 清单推送到 Git 代码库之前，如何检查本地计算机上的 Kubernetes 清单是否存在 Config Sync 错误？	Gemini Cloud Assist 介绍了如何使用 nomos 命令行工具检查 Kubernetes 清单是否存在 Config Sync 错误。其中详细介绍了如何使用 nomos vet 命令进行语法验证，以及如何使用 nomos hydrate 命令预览 Kustomize 或 Helm 中的渲染配置。Gemini Cloud Assist 还概述了在推送到 Git 之前集成这些检查的推荐工作流。

如需了解详情，请参阅以下资源：

• 了解如何撰写更好的提示。
• 了解如何使用 Gemini Cloud Assist 面板。
• 阅读 Gemini for Google Cloud 概览。
• 了解 Gemini for Google Cloud 如何使用您的数据。

使用 Gemini Cloud Assist 调查

除了互动式对话之外，Gemini Cloud Assist 还可以通过 Gemini Cloud Assist 调查执行更深入的自动化分析。此功能直接集成到 Logs Explorer 等工作流中，是一款强大的根本原因分析工具。

当您对某个错误或特定资源发起调查时，Gemini Cloud Assist 会分析相关日志、配置和指标。它会使用这些数据来生成有关潜在根本原因的排名观测结果和假设，然后为您提供建议的后续步骤。您还可以将这些结果转移到 Google Cloud 支持请求中，以为支持团队提供有价值的背景信息，从而帮助您更快地解决问题。

如需了解详情，请参阅 Gemini 文档中的 Gemini Cloud Assist 调查。

阅读其他问题排查文档

如果您仍然遇到问题，以下资源可能会有所帮助：

• 如果您收到错误消息，请参阅错误参考页面，了解有关如何解决错误的建议。

• 检查您遇到的问题是否是由已知问题引起的。

• 如果您在某个特定方面遇到困难，目录中按问题类型排查问题部分列出的某个针对性排查问题指南可能会有所帮助。

后续步骤

• 如果您在文档中找不到问题的解决方案，请参阅获取支持以获取进一步的帮助，包括以下主题的建议：

  • 请与 Cloud Customer Care 联系，以提交支持请求。
  • 通过在 StackOverflow 上提问，从社区获取支持。如果您使用 kpt 或 Kustomize，请使用 kpt 或 kustomize 标记来搜索类似问题。
  • 使用 GitHub 上的公开问题跟踪器提交 bug 或功能请求。