错误参考信息

本页介绍了 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 注解。 只能为命名空间范围的对象配置声明 NamespaceSelector。

从 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 或 NamespaceSelector。选择器必须存在，然后您才能在配置的注解中使用该选择器。

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

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 字段。如果需要升级，请按照版本说明中的说明进行操作。

目录名称不得超过 63 个字符，必须由小写字母、数字字符或“-”组成，并且必须以字母数字字符开头和结尾。

重命名或移除名称有误的目录。

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

重命名或移除错误消息中引用的所有配置，确保它们都具有唯一的名称。

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

移除重复的配置，使命名空间资源不超过一个。

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

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

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

移除存在问题的配置，或将您的代码库转换为使用 sourceFormat: hierarchy。

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

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

禁止声明 config-management-system、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。

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 不是有效的文件名。如需解决此问题，请从文件或路径名称中移除特殊字符。

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

Kubernetes API 请求可能会因多种原因而失败。出现该消息的常见原因包括：

  • API 发现错误
  • 客户端或服务器端请求或响应超时
  • 身份、身份验证或授权错误
  • 网络连接错误
  • Webhook 拒绝了请求
  • Webhook 运行状况不佳或无法被 API 服务器访问

在发生大多数 API 服务器错误后，Config Sync 会进行重试。有些可能是可以自行解决的暂时性问题，但大多数都需要用户干预才能解决。API 服务器错误很少是由 Config Sync 本身引起的，但如果您怀疑可能是这种情况，请提交bug 报告。

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

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

多种问题可能会导致此错误。如需排查连接到可靠来源的问题，请参阅排查连接到可靠来源的问题。 如需了解会导致 KNV2004 错误的已知问题，请参阅已知问题。

Config Sync 正在与其他控制器争夺资源。 此类争夺会消耗大量资源并降低性能。 如需了解有关如何诊断和解决控制器争夺问题的提示，请参阅排查控制器争夺问题。

为了帮助防止意外删除，Config Sync 不允许在单个提交作业中移除所有命名空间或集群级资源。

如果 Config Sync 准入网络钩子被停用，请还原删除所有资源的提交。
如果 Config Sync 准入网络钩子已启用，则您的命名空间可能会陷入终止状态。如需修复此错误，请执行以下步骤：

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

如果要删除管理下的所有资源集，请完成以下步骤：

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

在 Config Sync 尝试修改 API 服务器上的某个资源时，该资源也被修改或删除。

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

如果这些错误不是短暂的错误（持续数分钟），则说明系统可能存在严重的问题并且 nomos status 会报告控制器冲突。

这是一个总体性的错误，指出 Config Sync 未能将部分配置同步到集群。

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

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

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

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

创建或恢复缺失的资源。

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

移除了额外的 APIResource。

命名空间协调器的权限不足，无法管理资源。

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

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

移除非法修改的 webhook。

渲染进程遇到了内部问题。例如，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

此错误代表一个暂时性问题，稍后应该会自动解决。 例如，如果渲染状态与源配置不匹配，您可能会看到此错误。

此错误应会自动解决。

Config Sync 本身存在问题。

请提交 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 Collector 中的组件无法访问同一命名空间下的默认服务账号时，您可能会注意到 config-management-monitoring 下的 otel-collector Pod 处于 CrashLoopBackoff 状态，或者您可能会看到类似于以下列表中的错误消息。

此问题通常在集群中启用了适用于 GKE 的工作负载身份联合时出现。

如需解决此问题，请按照监控 Config Sync 中的说明向默认服务账号授予指标写入权限。

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

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

服务器证书验证失败

如果 git-sync、helm-sync 或 oci-sync 容器无法提取制品，您可能会看到此错误消息。

此消息表示服务器配置了来自自定义证书授权机构 (CA) 的证书。但是，自定义 CA 未正确配置，从而导致容器无法从服务器提取数据。

如需解决此问题，首先，您可以验证是否已在 RootSync 或 RepoSync 对象中正确配置了 caCertSecretRef 字段，并检查 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."

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

如果您使用的是 Google Distributed Cloud 私有注册表，则 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 角色。

返回页首

后续步骤