错误参考信息

本页面介绍了 Config Sync 错误代码以及处理这些错误的建议操作。

Config Sync 错误消息由 KNV1234 格式的错误 ID 组成，其中 1234 是一个唯一编号，后跟问题描述和建议解决方法。K 继承自 Kubernetes 惯例，前缀为 N 的规则特定于 nomos，V 特定于在代码库和集群的初始状态下可检测到的错误。在代码库和集群的初始状态下可检测到的错误的代码格式为 KNV1XXX。只能在运行时检测到的错误的代码格式为 KNV2XXX。

KNV 错误表

错误代码 说明 建议采取的操作

在 Config Sync 版本 1.6.1 中，InternalError 的 ID 更改为 KNV9998。

不适用

Config Sync 1.3 中已弃用。

不适用

Config Sync 1.3 中已弃用。

不适用

使用分层代码库结构时，包含命名空间配置的目录不得包含任何子目录。

不含命名空间配置的目录是抽象命名空间目录，并且有一些目录沿用自该目录。因此，抽象命名空间目录必须包含子目录。包含命名空间配置的目录是命名空间目录，这种目录不能被继承，因此不得包含任何子目录。

请从父目录中移除命名空间配置，或将子目录移到其他位置。

集群级对象不得声明 configmanagement.gke.io/namespace-selector 注解。只能为命名空间级对象声明 命名空间选择器。

从 metadata.annotations 字段中移除 configmanagement.gke.io/namespace-selector。

管理注解的唯一有效设置是 configmanagement.gke.io/managed=disabled。此设置用于明确取消管理 Git 代码库中的资源，同时让配置保持选中状态。注解 configmanagement.gke.io/managed=enabled 不是必需的。

确保管理注解为 configmanagement.gke.io/managed=disabled。

如需了解详情，请参阅管理对象。

无法解析代码库中声明的对象。

验证您的 YAML 格式。例如，您可以使用 kubectl --validate 命令。

如果 nomos vet 针对包含 group: configsync.gke.io 的类型（例如 RepoSync）返回此错误，请从下载页面下载 v1.6.0-rc.6 或更高版本以解决此问题。

使用非结构化代码库时，不得在抽象命名空间目录中声明配置。

将错误消息中列出的配置移至命名空间目录。

如需了解详情，请参阅使用非结构化代码库。

使用分层代码库结构时，配置必须声明与包含它们的命名空间目录匹配的命名空间，或省略该字段。

更新错误消息中标识的命名空间字段。

如需了解详情，请参阅分层代码库的结构。

配置不得声明以 configmanagement.gke.io 开头的不受支持的注解。

请确保您使用的是以下受支持的注解之一：

  • configmanagement.gke.io/managed。如需了解详情，请参阅管理对象。
  • configmanagement.gke.io/namespace-selector。如需了解详情，请参阅命名空间级对象。
  • configmanagement.gke.io/cluster-selector。如需了解详情，请参阅 ClusterSelectors。

配置的标签键不得以 configmanagement.gke.io/ 开头。此标签键前缀已预留，专供 Config Sync 使用。

更新错误消息中标识的所有标签。例如，如果您尝试声明名为
configmanagement.gke.io/example-label: label-value的标签，
则可以将其更改为
example-label: label-value。

Config Sync 1.3 中已弃用。

 不适用

配置引用了不存在的 ClusterSelector 或 ContextSelector。选择器必须已存在，才能在配置的注解中使用。

请创建任何缺失的选择器；或者，如果选择器已移除，请移除所有引用它的配置。

ClusterSelector 和 namespaceSelector 配置使用正确的语法，但发现了语法错误。

请务必使用适当的数据架构指定配置：

Config Sync 1.3.2 中已弃用。 不适用

使用分层代码库结构时，ConfigManagement Operator 的配置必须存在于代码库的 system/ 目录中。此配置必须包含所需信息，例如代码库的语义版本。

至少为 ConfigManagement Operator 定义一个最低配置。如需了解详情，请参阅分层代码库的结构。
Config Sync 1.3 中已弃用。 不适用

使用分层代码库结构时，不得在 namespaces/ 目录中直接声明命名空间。

为错误消息中列出的命名空间配置创建一个子目录。如需了解详情，请参阅分层代码库的结构。
使用分层代码库结构时，命名空间配置声明 metadata.name，并且其值必须与命名空间的目录名称匹配。 更正命名空间的 metadata.name 或其目录。

没有为集群中的资源定义任何 CustomResourceDefinition。

为错误消息中引用的资源创建 CustomResourceDefinition。非内置 Kubernetes 对象的资源类型必须具有 CustomResourceDefinition。

使用分层代码库时，无法在 system/ 目录中声明此种类的配置。

将错误消息中引用的资源移出 system/ 目录。如需了解详情，请参阅分层代码库的结构。

代码库配置中的 spec.version 字段表示代码库的语义版本。此错误表示您使用的版本不受支持。

如果您的代码库格式与支持的版本兼容，请更新 spec.version 字段。如果需要升级，请按照版本说明中的说明操作。

目录名称必须少于 64 个字符，由小写字母数字字符或“-”组成，且必须以字母数字字符开头和结尾。

重命名或移除错误命名的目录。

同一种类的配置在同一命名空间及其父级抽象命名空间中必须具有唯一的名称。

重命名或移除错误消息中引用的所有配置，使其均具有唯一的名称。

同一目录中不能存在多个命名空间资源。

请移除重复的配置，确保剩余的命名空间资源不超过一个。

所有配置都必须声明 metadata.name。

将 metadata.name 字段添加到有问题的配置中。

如果 sourceFormat 设置为 unstructured，则不允许使用 Repo.configmanagement.gke.io 类型。

移除有问题的配置，或转换代码库以使用 sourceFormat: hierarchy。

如果您使用的是分层代码库，则只能在 system/ 目录中声明 HierarchyConfig 和 Repo 种类。

确保 system/ 目录中声明的所有配置都是允许的种类之一。如果没有，请将其移至其他目录。

禁止声明 config-management-system 命名空间或其中的资源。

从 Config Sync 1.17.0 版开始，命名空间 resource-group-system 和 config-management-monitoring 也无法在可信来源中声明。此外，我们也不建议在 resource-group-system 和 config-management-monitoring 命名空间下声明任何资源。

如果您声明了 config-management-system 命名空间，请将其移除以及该命名空间中的所有配置。

如果您声明了 resource-group-system 或 config-management-monitoring 命名空间，请取消管理控制器命名空间：

  1. 更新 Config Sync，以停止管理命名空间以及其下声明的所有资源。
  2. 等待同步，然后确认相应资源在集群上仍然可用，但在 nomos status 中不可用。
  3. 从源代码中移除控制器命名空间 YAML 文件。
  4. 让 Config Sync 继续管理资源。

如果您之前已同步到分层代码库，并且必须声明控制器命名空间与所有资源，请考虑切换到非结构化代码库，以便在源代码结构中更加灵活。

提供的 metadata.name 格式无效。

更改 metadata.name 以满足以下条件：

  • 少于 254 个字符
  • 由小写字母数字字符、“-”或“.”组成。
  • 以字母数字字符开头和结尾

如果 metadata.name 无效，并且原始资源支持该字段，请考虑改用 spec.resourceID 字段，以免受到这些限制的限制。如需了解详情，请参阅使用 resourceID 字段管理资源。
Config Sync 1.3 中已弃用。 不适用

禁止在 namespaces/ 目录之外声明命名空间级对象。

移动有问题的配置，使其位于合法目录中。如需详细了解命名空间级对象，请参阅命名空间级对象。

禁止在 cluster/ 目录之外声明集群级对象。

移动有问题的配置，使其位于合法目录中。如需详细了解集群级对象，请参阅集群级对象。
Config Sync 1.3 中已弃用。 不适用

此资源种类不得在 HierarchyConfig 中声明。

移除有问题的资源。如需详细了解 HierarchyConfig，请参阅停用对象类型的继承。

在 HierarchyConfig 上检测到 HierarchyMode 的无效值。

将 HierarchyMode 更改为 none 或 inherit。如需详细了解 HierarchyConfig，请参阅停用对象类型的继承。

Config Sync 无法配置此对象。

 从代码库中移除有问题的配置。

包含配置的抽象命名空间目录必须至少包含一个命名空间子目录。

在抽象命名空间目录下添加一个命名空间目录，向抽象命名空间目录添加命名空间配置，或者移除抽象命名空间目录中的配置。

不允许使用指定了 metadata.ownerReference 的配置。

从源代码库中移除 status 字段。对于您不拥有的第三方配置，请使用 kustomize patches 批量移除清单中指定的 status 字段。

此 HierarchyConfig 引用了具有集群范围的资源。HierarchyConfig 中不允许使用集群级对象。

更新 HierarchyConfig，使其不再引用有问题的资源。

不允许移除自定义资源定义 (CRD) 并将相应的自定义资源保留在代码库中。

移除 CRD 以及自定义资源。

CustomResourceDefinition 的名称无效。

将名称更改为错误消息中的建议名称。

配置使用的是已弃用的 Group 和 Kind。

请将组或种类更改为错误消息中的建议。

集群级资源不得声明 metadata.namespace。

 从集群范围的资源中移除 metadata.namespace 字段。

命名空间级资源必须声明 metadata.namespace 或 metadata.annotations.configmanagement.gke.io/namespace-selector。

将缺失的字段添加到命名空间级资源中。

配置包含无效的注解值。

请按照错误消息中的说明解决错误。

metadata.namespace 的值不是有效的 Kubernetes 命名空间名称。

更新 metadata.namespace 的值，使其符合以下规则：

  • 长度不超过 63 个字符
  • 只能包含小写字母 (a-z)、数字 (0-9) 和连字符“-”
  • 以小写字母或数字开头和结尾

资源是在非代管命名空间中声明的。

您可以移除 configmanagement.gke.io/managed: disabled 注解，也可以将该注解添加到声明的资源中。

资源具有非法标签。

移除错误消息中列出的非法标签。

命名空间代码库只能在其适用的命名空间中声明命名空间级资源。

确保所有命名空间代码库正确声明了命名空间级资源。 例如，shipping 命名空间代码库的代码库只能管理 shipping 命名空间中的资源。metadata.namespace 的值是可选的。默认情况下，Config Sync 假定命名空间代码库中的所有资源都属于该命名空间。

例如，如果 shipping 命名空间代码库中的配置声明了 metadata.namespace: billing，您会收到错误。

除了确保正确声明命名空间级资源外，还要确保在根代码库中声明命名空间。必须这样做，因为命名空间是集群级的。

一个命名空间代码库最多只能声明一个 Kptfile 资源。

 只移除一个 Kptfile 资源。

在多个可信来源中管理对象时，在多个来源中声明同一对象（匹配的组、种类、名称和命名空间）时，可能会发生冲突。

例如，如果同一个对象由 RootSync 和 RepoSync 管理，RootSync 胜出。如果先应用 RootSync，RepoSync 会报告 KNV1060 状态错误。如果先应用 RepoSync，RootSync 会覆盖 RepoSync 的对象，并且 RepoSync 会在看到更新时报告 KNV1060 状态错误。

如需解决冲突，请更新配置以与其他可信来源匹配，或从其中一个来源中删除存在冲突的对象。

nomos vet 命令一次仅检查一个代码库中的错误，因此它无法检测到此问题。

InvalidRepoSyncError 报告 RepoSync 配置有误。必须正确配置 RepoSync 对象，Config Sync 才能同步命名空间代码库中的配置。

请按照错误消息中的说明修正配置错误。

Kptfile 没有有效的商品目录字段。Kptfile 应包含一个同时指定了标识符和命名空间的非空目录字段。

在 Kptfile 中指定 .inventory.identifier 和 .inventory.namespace 的值。

在根代码库中找到了 Kptfile。只有命名空间级代码库支持 Kptfile。

从根代码库中移除 Kptfile。

无法解析代码库中的 api-resources.txt 文件。

请按照错误消息中的说明操作。例如，您可能需要重新运行 kubectl api-resources > api-resources.txt。

在 nomos 1.16.1 版及更低版本中，您还会看到以下错误：KNV1064: unable to find APIGROUP column。此错误是由于列名称从 APIGROUP 更改为 APIVERSION 而导致的。如需缓解此问题，请手动将 api-resources.txt 中的 APIVERSION 重新替换为 APIGROUP。

CustomResourceDefinition 格式错误。

请检查错误消息指定的字段，确保其值的格式正确。

配置对象必须仅声明集群选择器注解。当旧版注解 (configmanagement.gke.io/cluster-selector) 和内嵌注解 (configsync.gke.io/cluster-name-selector) 都存在时，就会发生此错误。

从 metadata.annotations 字段中移除某个注释。

协调器无法将声明的字段编码为与服务器端应用兼容的格式。这可能是因为架构已过时。

请检查错误消息指定的字段，并确保该字段与资源类型的架构匹配。

呈现过程遇到了用户可操作的问题。

如果 Git 代码库包含 Kustomize 配置，但 Git 同步目录中不存在 kustomization.yaml 文件，请在同步目录中添加 kustomization.yaml 以触发渲染过程，或从所有子目录中移除 kustomization.yaml 以跳过渲染。

如果错误是由 kustomize build 失败引起的，您可能需要更新 Git 代码库中的 Kustomize 配置。您可以使用 nomos hydrate 和 nomos vet 在本地预览和验证更新后的配置。如果更新后的配置成功呈现，您可以推送新的提交以修复 KNV1068 错误。

如果从公共代码库拉取远程库时发生 kustomize build 错误，您需要将 spec.override.enableShellInRendering 设置为 true。

协调器已调整了自己的 RootSync 或 RepoSync 对象。RootSync 对象可以管理其他 RootSync 和 RepoSync 对象；RepoSync 对象可以管理其他 RepoSync 对象，但它们无法自行管理。

从与其同步的可信来源中移除 RootSync 或 RepoSync 对象。

访问文件系统资源的操作系统级系统调用失败。

此错误可能是由 YAML 配置无效或使用特殊字符导致的。如果您的 YAML 配置无效，您会看到类似于以下内容的错误消息：KNV2001: yaml: line 2: did not find expected node content path:...。如需解决此问题，请检查您的 YAML 文件并解决所有配置问题。这可能是由代码库中的任何 YAML 配置导致的。

如果文件名或路径包含特殊字符，您可能会看到类似于 KNV2001: yaml: control characters are not allowed path:/repo/source/.../._pod.yaml 的错误消息。 在此示例中，._pod.yaml 不是有效的文件名。如需解决此问题，请从文件或路径名称中移除特殊字符。

访问 API 服务器的请求失败。

您可能遇到了 API 发现错误。如需了解详情，请参阅 API 发现错误。

通用操作系统级系统调用失败。

Config Sync 无法从可信来源读取数据。

有多个问题可能会导致此错误。如需了解有关如何解决连接到可信来源的常见问题的提示，请参阅排查连接到可信来源的问题。
Config Sync 正在与其他控制器争夺资源。此类争夺会消耗大量资源，并可能会降低性能。 如需了解有关如何诊断和解决控制器争用的提示，请参阅排查控制器争用问题。

为了帮助防止意外删除，Config Sync 不允许您通过单次提交移除所有命名空间或集群级资源。

如果 Config Sync 准入 webhook 已停用，请还原删除所有资源的提交。
如果启用了 Config Sync 准入 webhook，则您的命名空间可能会在终止时卡住。如需解决此问题，请执行以下步骤：

  1. 停用 Config Sync，并等待所有资源均清理完毕或处于稳定状态。例如，您可以运行 kubectl get ns 来确保命名空间已删除。
  2. 重新启用 Config Sync。
  3. 还原删除所有资源的提交。

如果您要删除受管的全部资源，请完成以下步骤：

  1. 在首次提交中保留一个命名空间或集群级资源（只保留一个资源），并允许 Config Sync 同步这些更改。
  2. 在第二次提交时移除最终资源。

Config Sync 也尝试修改 API 服务器上的资源时，系统会修改或删除该资源。

如果此类错误仅在启动时出现或者很少出现，您可以忽略这些错误。

如果这些错误不是暂时性的（持续几分钟），则可能表示存在严重问题，并且 nomos status 会报告控制器争用。

这是一个泛指的错误，表示 Config Sync 无法将某些配置同步到集群。

有多个问题可能会导致此错误。如需了解有关如何解决同步常见问题的提示，请参阅排查同步问题。

这是一个泛指的错误，表示某个资源或一组资源存在问题。

错误消息包含导致错误的特定资源。调查这些资源。

需要特定资源才能继续操作，但未找到该资源。例如，ConfigManagement Operator 尝试更新资源，但该资源在计算更新时已被删除。

创建或恢复缺失的资源。

此错误报告表示在只允许使用其中一个 APIResource 的上下文中发现了多个 API 资源实例。例如，集群中只能存在一个 Repo 资源。

移除其他 APIResource。

命名空间协调器没有足够的权限管理资源。

确保协调器具有足够的权限。

非法修改 Config Sync 网络钩子配置时，会出现此警告。系统会忽略非法网络钩子配置。

移除非法修改的网络钩子。

渲染过程遇到了内部问题。例如，Config Sync 无法访问文件系统。

此错误可能表示 Pod 健康状况不佳。您可以通过运行以下命令重启协调器 Pod：


# restart a root reconciler
kubectl delete pod -n config-management-system -l configsync.gke.io/reconciler=root-reconciler

# restart a namespace reconciler
kubectl delete pod -n config-management-system -l configsync.gke.io/reconciler=ns-reconciler-NAMESPACE

此错误表示暂时性问题，稍后应自动解决。例如，如果呈现状态与源配置不匹配，您可能会看到此错误。

错误应该会自动解决。

nomos 命令行工具本身存在问题。

请提交包含您运行的确切命令和收到的消息的 bug 报告。

您遇到的的错误包含未被记录的错误消息。

我们尚未针对您遇到的这种错误编写文档。

返回页首

无 KNV 代码的错误消息

Config Sync 协调器报告的错误具有 KNV 错误代码，但其他组件报告的错误不包含 KNV 代码。例如，“权限遭拒”错误来自舰队控制器，该控制器是 Config Sync 之上的一个层。

下表列出了一些不含 KNV 前缀的常见错误。

错误消息 建议采取的操作

Error: cannot build exporters: error creating stackdriver exporter: cannot configure Google Cloud metric exporter: stackdriver: google: could not find default credentials.

Error: Permission monitoring.timeSeries.create denied (or the resource may not exist).

无法构建导出器

当 Open Telemetry 收集器中的组件无法访问同一命名空间下的默认服务帐号时，您可能会注意到 config-management-monitoring 下的 otel-collector Pod 处于 CrashLoopBackoff 状态，或者您可能会看到类似于列出的错误消息。

在集群中启用 Workload Identity 时，通常发生此问题。

要解决此问题，请按照 Monitoring Config Sync 中的说明向默认服务帐号授予指标写入权限。

如果在设置 IAM 后错误仍然存在，请重启 otel-collector Pod，以使更改生效。
如果您使用的是自定义监控解决方案，但创建了默认 otel-collector-googlecloud ConfigMap，请检查并检查任何差异并实施 rebase 操作。

server certificate verification failed. CAfile:/etc/ca-cert/cert CRLfile: none

服务器证书验证失败

如果 git-sync 容器无法克隆 Git 代码库，您可能会看到此错误消息。

此消息表示 Git 服务器配置了自定义证书授权机构 (CA) 的证书。但是，自定义 CA 未正确配置，导致 git-sync 容器无法克隆 Git 代码库。

如需解决此问题，首先，您可以验证是否已在 RootSync 或 RepoSync 对象中指定 spec.git.caCertSecretRef.name 字段，并检查相应 Secret 对象是否存在。

接下来，如果该字段已配置且 Secret 对象存在，请确保 Secret 对象包含完整证书。
检查完整证书的方法可能会有所不同，具体取决于自定义 CA 的预配方式。

以下示例展示了如何列出服务器证书： 


echo -n | openssl s_client -showcerts -connect HOST:PORT -servername SERVER_NAME 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'

您可以要求网络管理团队为您获取 CA 证书。
Error message: "MESSAGE": "Unable to retrieve pull secret, the image pull may not succeed."

无法检索拉取密钥，映像拉取可能不会成功

如果您为 GKE on VMware 使用了私有注册表，则 Config Sync 安装或升级可能会卡住。您会看到与此消息类似的错误。

如需解决此问题，请在安装或升级 Config Sync 之前，按照使用私有注册表更新 Config Sync 中的步骤操作。
Permission 'gkehub.features.create' denied on 'projects/PROJECT_ID/locations/global/features/configmanagement'

权限遭拒

如果您在尝试配置 Config Sync 时收到与此示例类似的错误，则说明您可能没有 GKE Hub Admin 角色。

为确保您拥有所需的权限，请确保您已授予所需的 IAM 角色。

返回页首

后续步骤