Referência de erros

As mensagens de erro do Config Sync consistem em um ID de erro no formato KNV1234, em que 1234 é um número único, seguido por uma descrição do problema e uma sugestão de como corrigi-lo. K é herdada das convenções do Kubernetes, as regras com o prefixo N são específicas para nomos, os códigos para erros detectáveis no estado inicial do repositório e o cluster são do formato KNV1XXX. Os códigos para erros que só podem ser detectados durante a execução estão no formato KNV2XXX.

Esta página documenta cada uma dessas mensagens de erro e as etapas para resolvê-lo.

Veja também a introdução à solução de problemas do Config Sync e aos problemas conhecidos.

KNV1000: InternalError

O ID de InternalError foi alterado para KNV9998 com o Config Sync 1.6.1.

KNV1001: ReservedDirectoryNameError

Obsoleto no Config Sync 1.3.

KNV1002: DuplicateDirectoryNameError

Obsoleto no Config Sync 1.3.

KNV1003: IllegalNamespaceSubdirectoryError

Ao usar uma estrutura hierárquica de repo, um diretório que contém uma configuração de namespace não pode conter nenhum subdiretório.

Um diretório sem uma configuração de namespace é um diretório de namespace abstrato, tem diretórios herdados dele e, consequentemente, precisa de subdiretórios. Um diretório contendo uma configuração de namespace é um diretório de namespace e não pode ser herdado. Por isso, não pode ter nenhum subdiretório.

Para fazer a correção, remova a configuração de namespace do diretório pai ou mova o subdiretório para outro local.

Isso poderá acontecer se um diretório contendo um namespace tiver um subdiretório.

namespaces/
└── prod/
    ├── namespace.yaml
    └── us_west_1/
# namespaces/prod/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: prod

Essa estrutura de diretório e o conteúdo de namespace.yaml geram esse erro:

KNV1003: A Namespace directory MUST NOT have subdirectories. Remove the
         Namespace policy from "prod", or move "us_west_1" to an Abstract
         Namespace:

path: namespaces/prod/us_west_1
name: us_west_1

KNV1004: IllegalSelectorAnnotationError

Um objeto com escopo de cluster não pode declarar a anotação configmanagement.gke.io/namespace-selector. Os NamespaceSelectors só podem ser declarados para objetos com escopo de namespace.

Para corrigir o erro, remova configmanagement.gke.io/namespace-selector do campo metadata.annotations.

A seguinte configuração do ClusterRole produz este erro:

# cluster/namespace-reader-clusterrole.yaml
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: namespace-reader
  annotations: {
    "configmanagement.gke.io/namespace-selector" : "shipping-dev",
  }
rules:
- apiGroups: [""]
  resources: ["namespaces"]
  verbs: ["get", "watch"]

Ao tentar incluir isso no cluster, nomos vet retornará o erro a seguir:

KNV1004: Cluster-scoped objects may not be namespace-selected, and so MUST NOT declare the annotation 'configmanagement.gke.io/namespace-selector'. To fix, remove `metadata.annotations.configmanagement.gke.io/namespace-selector` from:
source: cluster/namespace-reader-clusterrole.yaml
metadata.name: namespace-reader
group: rbac.authorization.k8s.io
version: v1
kind: ClusterRole

Um objeto de cluster não pode declarar a anotação configmanagement.gke.io/cluster-selector. Para corrigir o erro, remova configmanagement.gke.io/cluster-selector de metadata.annotations.

Se um objeto de cluster declarar configmanagement.gke.io/cluster-selector, nomos vet retornará o seguinte erro:

KNV1004: Clusters may not be cluster-selected, and so MUST NOT declare the annotation 'configmanagement.gke.io/cluster-selector'. To fix, remove `metadata.annotations.configmanagement.gke.io/cluster-selector` from:

source: clusterregistry/cluster.yaml
metadata.name: default-name
group: clusterregistry.k8s.io
version: v1alpha1
kind: Cluster

KNV1005: IllegalManagementAnnotationError

A única configuração válida para a anotação de gerenciamento é configmanagement.gke.io/managed=disabled. Essa configuração é usada para cancelar explicitamente o gerenciamento de um recurso no repositório do Git, deixando a configuração registrada. A anotação configmanagement.gke.io/managed=enabled não é necessária. Para mais informações, consulte Como gerenciar objetos.

Definir uma anotação diferente resulta em um erro como este:

KNV1005: Config has invalid management annotation configmanagement.gke.io/managed=invalid. If set, the value must be "disabled".

source: namespaces/foo/role.yaml
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1006: ObjectParseError

Esse erro ocorre quando não é possível analisar um objeto declarado no repositório. Para corrigir, valide o formato yaml com uma ferramenta como kubectl --validate.

Exemplo:

KNV1006: The following config could not be parsed as a rbac.authorization.k8s.io/v1, Kind=Role:

source: namespaces/foo/role.yaml
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1007: IllegalAbstractNamespaceObjectKindError

Ao usar um repo não estruturado, os configs não podem ser declarados em um diretório de namespaces abstratos. Para mais informações sobre como usar repositórios não estruturados, consulte Como usar um repositório não estruturado.

KNV1007: Config "default-name" illegally declared in an abstract namespace directory. Move this config to a namespace directory:

source: namespaces/foo/bar/role.yaml
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1009: IllegalMetadataNamespaceDeclarationError

Ao usar a estrutura hierárquica do repo, as configurações declaram namespaces que correspondem ao diretório do namespace que os contém ou omitem o campo.

Veja a seguir um exemplo de configuração de papel que aciona o erro:

# namespaces/shipping-prod/pod-reader-role.yaml
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: pod-reader
  namespace: shipping-dev
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "watch", "list"]

Se você declarar um config com esse namespace, este erro ocorrerá:

KNV1009: A config MUST either declare a `namespace` field exactly matching the directory containing the config, "shipping-prod", or leave the field blank:

source: namespaces/shipping-prod/pod-reader-role.yaml
namespace: shipping-dev
metadata.name: pod-reader
group: rbac.authorization.k8s.io
version: v1
kind: Role

Para mais informações sobre a estrutura hierárquica do repositório, consulte Estrutura do repositório hierárquico.

KNV1010: IllegalAnnotationDefinitionError

As configurações não podem declarar anotações incompatíveis de configmanagement.gke.io.

As anotações compatíveis são:

Exemplo de erros:

KNV1010: Configs MUST NOT declare unsupported annotations starting with
         "configmanagement.gke.io/". The config has invalid annotations:
         "configmanagement.gke.io/invalid", "configmanagement.gke.io/sync-token"

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1011: IllegalLabelDefinition

As configurações não podem ter rótulos com chaves que começam com configmanagement.gke.io/. Este prefixo de chave de rótulo está reservado para ser usado pelo Config Sync.

Veja a seguir um exemplo de um ConfigMap que aciona esse erro:

# namespaces/prod/mymap.yaml
kind: ConfigMap
apiVersion: v1
metadata:
  name: my-map
  labels:
    configmanagement.gke.io/bad-label: label-value
data:
  mydata: moredata

Se você declarar um config com esse rótulo, este erro ocorrerá:

KNV1011: Configs MUST NOT declare labels starting with "configmanagement.gke.io/". The config has disallowed labels: "configmanagement.gke.io/bad-label"

source: namespaces/prod/mymap.yaml
metadata.name: my-map
group:
version: v1
kind: ConfigMap

KNV1012: NamespaceSelectorMayNotHaveAnnotation

Obsoleto no Config Sync 1.3.

KNV1013: ObjectHasUnknownSelector

A configuração refere-se a um ClusterSelector ou NamespaceSelector que não existe. Antes de usar um seletor em uma anotação para uma configuração, o seletor precisa existir.

Se o seletor for removido, remova também todas as configurações que se referem a ele. Neste exemplo, suponha que não exista o ClusterSelector unknown-cluster-selector no diretório clusterregistry/ do repo.

# namespaces/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: foo
  annotations:
    configmanagement.gke.io/cluster-selector: unknown-cluster-selector

Isso causa este erro:

KNV1013: Config "foo" MUST refer to an existing ClusterSelector, but has
         annotation
         "configmanagement.gke.io/cluster-selector=unknown-cluster-selector",
         which maps to no declared ClusterSelector

As anotações NamespaceSelector têm outro requisito: que o NamespaceSelector mencionado seja definido no mesmo diretório ou no diretório pai da referência de configuração. Caso contrário, ocorrerá este erro:

KNV1013: Config "default-name" MUST refer to a NamespaceSelector in its directory or a parent directory. Either remove the annotation "configmanagement.gke.io/namespace-selector=default-ns-selector" from "default-name" or move NamespaceSelector "default-ns-selector" to a parent directory of "default-name".

    source: namespaces/bar/selector.yaml
    metadata.name: default-ns-selector
    group: configmanagement.gke.io
    version: v1
    kind: NamespaceSelector

    source: namespaces/foo/role.yaml
    metadata.name: default-name
    group: rbac.authorization.k8s.io
    version: v1
    kind: Role

KNV1014: InvalidSelectorError

As configurações de ClusterSelector e NamespaceSelector usam a sintaxe correta, mas foi encontrado um erro de sintaxe. Para fazer a correção, especifique a configuração de acordo com o esquema de dados adequado:

Por exemplo, este ClusterSelector inválido:

kind: ClusterSelector
apiVersion: configmanagement.gke.io/v1
metadata:
  name: selector-1
spec:
  selector:
    someUnknownField:  # This field is not defined for a LabelSelector
      foo: bar

Causa o seguinte erro:

KNV1014: ClusterSelector has validation errors that must be corrected: invalid field "someUnknownField"
    source: clusterregistry/cs.yaml
    metadata.name: selector-1
    group: configmanagement.gke.io
    version: v1
    kind: ClusterSelector

Especificamente, as definições de ClusterSelector e NamespaceSelector definem o campo spec.selector. Se isso não for feito, ocorrerá o seguinte erro:

   KNV1014: NamespaceSelectors MUST define `spec.selector`

    source: namespaces/ns.yaml
    metadata.name: ns-selector-1
    group: configmanagement.gke.io
    version: v1
    kind: NamespaceSelector

KNV1016: PolicyManagementNotInstalledError

Obsoleto no Config Sync 1.3.2

KNV1017: MissingRepoError

Ao usar a estrutura hierárquica do repo, uma configuração de repo precisa existir no diretório system/ do repo e incluir as informações necessárias, como a versão semântica do repo.

Se um config do repo não existir, ocorrerá o seguinte erro:

KNV1017: The system/ directory must declare a Repo Resource.
path: system/

To fix, define at least a minimal Repo config.
# system/repo.yaml
kind: Repo
apiVersion: configmanagement.gke.io/v1
metadata:
  name: repo
spec:
  version: "0.1.0"

Para mais informações sobre a estrutura hierárquica do repositório, consulte Estrutura do repositório hierárquico.

KNV1018: IllegalSubdirectoryError

Obsoleto no Config Sync 1.3.

KNV1019: IllegalTopLevelNamespaceError

Ao usar a estrutura hierárquica do repo, os namespaces não podem ser declarados diretamente em namespaces.

Veja a seguir um config que aciona o erro:

# namespaces/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: namespaces
source: namespaces/namespace.yaml
metadata.name: namespaces
group:
version: v1
kind: Namespace
   KNV1019: Namespaces MUST be declared in subdirectories of 'namespaces/'. Create a subdirectory for the following Namespace configs:

    source: namespaces/namespace.yaml
    metadata.name: namespaces
    group:
    version: v1
    kind: Namespace

Para mais informações sobre a estrutura hierárquica do repositório, consulte Estrutura do repositório hierárquico.

KNV1020: InvalidNamespaceNameError

Ao usar a estrutura hierárquica do repo, uma configuração de namespace declara metadata.name, e o valor dela precisa corresponder ao nome do diretório do namespace. Para fazer a correção, ajuste o metadata.name do namespace ou o diretório dele.

Veja a seguir um config que aciona o erro:

# namespaces/prod/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: dev
KNV1020: A Namespace MUST declare `metadata.name` that matches the name of its
         directory.

expected `metadata.name`: prod

source: namespaces/prod/namespace.yaml
metadata.name: dev
group:
version: v1
kind: Namespace

Para mais informações sobre a estrutura hierárquica do repositório, consulte Estrutura do repositório hierárquico.

KNV1021: UnknownObjectError

KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.
         Resource types that are not native Kubernetes objects must have a
         CustomResourceDefinition.

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1024: IllegalKindInSystemError

KNV1024: Configs of this Kind may not be declared in the `system/` directory of
         the repo:

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1027: UnsupportedRepoSpecVersion

O campo spec.version na configuração do repo representa a versão semântica dele. Esse erro indica que você está usando uma versão sem suporte.

Se o formato do repo for compatível com a versão compatível, atualize o campo spec.version.

Se precisar fazer upgrade, siga as instruções nas notas de lançamento.

# system/repo.yaml
kind: Repo
apiVersion: configmanagement.gke.io/v1
metadata:
  name: repo
spec:
  version: "0.0.0"

Isso produz este erro:

KNV1027: Unsupported Repo spec.version: "0.0.0". Must use version "main"

source: system/repo.yaml
name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1028: InvalidDirectoryNameError

KNV1028: Directory names have fewer than 64 characters, consist of lower case
         alphanumeric characters or '-', and must start and end with an
         alphanumeric character. Rename or remove directory:

path: namespaces/a.b`c
name: a.b`c

KNV1029: MetadataNameCollisionError

KNV1029: Configs of the same Kind MUST have unique names in the same Namespace
         and their parent abstract namespaces:

source: namespaces/foo/r1.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

source: namespaces/foo/r2.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1030: MultipleSingletonsError

KNV1030: Multiple Namespace resources cannot exist in the same directory. To fix, remove the duplicate config(s) such that no more than 1 remains:

source: namespaces/foo/namespace.yaml
metadata.name: foo
group:
version: v1
kind: Namespace

source: namespaces/foo/namespace.yaml
metadata.name: foo
group:
version: v1
kind: Namespace

KNV1031: MissingObjectNameError

Todas as configurações precisam declarar metadata.name. Para corrigir, adicione o campo metadata.name às configurações problemáticas.

KNV1031: A config must declare metadata.name:

source: namespaces/foo/role.yaml
metadata.name:
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1032: IllegalHierarchicalKindErrorCode

KNV1032: The type Repo.configmanagement.gke.io is not allowed if `sourceFormat` is set to `unstructured`. To fix, remove the problematic config, or convert your repo to use `sourceFormat: hierarchy`.

source: system/repo.yaml
metadata.name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1033: IllegalSystemResourcePlacementError

Alguns tipos só podem ser declarados dentro do diretório system/. Veja a seguir uma lista de tipos que podem existir exclusivamente no diretório system/: HierarquiaConfig, Repo

KNV1033: A config of the below Kind MUST NOT be declared outside system/:

source: namespaces/foo/repo.yaml
metadata.name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1034: IllegalNamespaceError

É proibido declarar o namespace config-management-system ou os recursos dele. Para fazer a correção, remova o namespace config-management-system e todas as configurações dele.

KNV1034: Configs must not be declared in the "config-management-system" namespace

source: namespaces/config-management-system/role.yaml
namespace: namespaces/config-management-system
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role
KNV1034: The "config-management-system" namespace must not be declared

source: namespaces/config-management-system/namespace.yaml
metadata.name: config-management-system
group:
version: v1
kind: Namespace

A partir da versão 1.17.0 do Config Sync, os namespaces resource-group-system e config-management-monitoring não podem ser declarados em uma fonte de verdade. Também não é recomendado declarar nenhum recurso nos namespaces resource-group-system e config-management-monitoring.

Se sua fonte de verdade contiver esses dois namespaces, o Config Sync informará o seguinte erro:

KNV1034: The "config-management-system" namespace must not be declared

source: namespaces/config-management-monitoring/namespace.yaml
metadata.name: config-management-monitoring
group:
version: v1
kind: Namespace

Para resolver esse problema e cancelar o gerenciamento do namespace do controlador com segurança:

  • Atualize o Config Sync para parar de gerenciar o namespace e todos os recursos declarados abaixo.

  • Aguarde uma sincronização e confirme se os recursos correspondentes ainda estão disponíveis no cluster, mas não no nomos status.

  • Remova da origem o arquivo YAML do namespace do controlador.

  • Deixe o Config Sync retomar o gerenciamento dos recursos.

Se você já estava sincronizando com um repositório hierárquico e teve que declarar o namespace do controlador junto com todos os recursos, considere mudar para repositório não estruturado para ter mais flexibilidade na estrutura de origem.

KNV1036: InvalidMetadataNameError

O metadata.name fornecido é de formato inválido. Um metadata.name válido precisa: - Ter menos de 254 caracteres; - Ter caracteres alfanuméricos minúsculos, '-' ou '.'; - Começar e terminar com um caractere alfanumérico.

Para corrigir, altere o metadata.name para atender às condições anteriores.

KNV1036: Configs MUST define a metadata.name that is shorter than 254
        characters, consists of lower case alphanumeric characters, '-' or '.',
         and must start and end with an alphanumeric character. Rename or remove
         the config:

source: namespaces/foo/role.yaml
metadata.name: a`b.c
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1037: IllegalKindInClusterregistryError

Obsoleto no Config Sync 1.3.

KNV1038: IllegalKindInNamespacesError

KNV1038: Configs of the below Kind may not be declared in `namespaces/`:

source: cluster/cr.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: ClusterRole

KNV1039: IllegalKindInClusterError

É proibido declarar um objeto com escopo de namespace fora dos namespaces, ou um objeto com escopo de cluster fora do cluster. Para corrigir, realoque os configs problemáticos para que eles estejam em um diretório jurídico.

Para mais informações sobre objetos com escopo de cluster, consulte Objetos com escopo de cluster.

Para mais informações sobre objetos com escopo de namespace, consulte Objetos com escopo de namespace.

KNV1039: Namespace-scoped configs of the below Kind must not be declared in
         cluster/:

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1040: UnknownResourceInHierarchyConfigError

Obsoleto no Config Sync 1.3.

KNV1041: UnsupportedResourceInHierarchyConfigError

KNV1041: This Resource Kind MUST NOT be declared in a HierarchyConfig:

source: system/hc.yaml
group: configmanagement.gke.io
kind: Repo

KNV1042: IllegalHierarchyModeError

Um valor ilegal para HierarchyMode foi detectado em uma HierarchyConfig. HierarchyMode precisa ser nenhum ou herdar.

Para ler mais sobre HierarchyConfigs, consulte Como desativar a herança para um tipo de objeto.

KNV1042: HierarchyMode invalid is not a valid value for the APIResource Role.rbac.authorization.k8s.io. Allowed values are [none,inherit].

source: system/hc.yaml
metadata.name: default-name
group: configmanagement.gke.io
version: v1
kind: HierarchyConfig

KNV1043: UnsupportedObjectError

KNV1043: Config Sync cannot configure this object. To fix, remove this
         config from the repo.

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1044: UnsyncableResourcesErrorCode

KNV1044: An Abstract Namespace directory with configs MUST have at least one
Namespace subdirectory. To fix, do one of the following: add a Namespace
directory below "bar", add a Namespace config to "bar", or remove the configs in
"bar":

path: namespaces/foo/bar/

KNV1045: IllegalFieldsInConfigError

Exemplo de mensagem de erro:

KNV1045: Configs with "metadata.ownerReference" specified are not allowed. To
fix, either remove the config or remove the "metadata.ownerReference" field in
the config:

source: namespaces/foo/replicaset.yaml
metadata.name: replicaSet
group: apps
version: v1
kind: ReplicaSet

O campo status é um dos inválidos que causa esse erro. Não é permitido usar o Config Sync para sincronizar o campo status porque outro controlador precisa gerenciar e atualizar o campo status no cluster dinamicamente. Se o Config Sync tentar controlar o status pretendido do campo status, ele vai entrar em conflito com o controlador responsável por gerenciar o campo status.

Para corrigir esse erro, remova o campo status do repositório de origem. Para configurações de terceiros que não pertencem a você, use patches kustomize para remover campos status especificados nos manifestos em massa.

KNV1046: ClusterScopedResourceInHierarchyConfigError

KNV1046: This HierarchyConfig references the APIResource "ClusterSelector.configmanagement.gke.io" which has cluster scope. Cluster scoped objects are not permitted in HierarchyConfig.

source: system/hc.yaml
metadata.name: hierarchyconfig
group: configmanagement.gke.io
version: v1
kind: HierarchyConfig

KNV1047: UnsupportedCRDRemovalError

KNV1047: Removing a CRD and leaving the corresponding Custom Resources in the
repo is disallowed. To fix, remove the CRD along with the Custom Resources.

source: cluster/crd.yaml
metadata.name: customResourceDefinition
group: apiextensions.k8s.io
version: v1beta1
kind: CustomResourceDefinition

KNV1048: InvalidCRDNameError

KNV1048: The CustomResourceDefinition has an invalid name. To fix, change the
name to `spec.names.plural+"."+spec.group`.

source: cluster/crd.yaml
metadata.name: customResourceDefinition
group: apiextensions.k8s.io
version: v1beta1
kind: CustomResourceDefinition

KNV1050: DeprecatedGroupKindError

KNV1050: The config is using a deprecated Group and Kind. To fix, set the Group and Kind to "Deployment.apps"

source: namespaces/deployment.yaml
metadata.name: default-name
group: extensions
version: v1beta1
kind: Deployment

KNV1052: IllegalNamespaceOnClusterScopedResourceError

KNV1052: cluster-scoped resources MUST NOT declare metadata.namespace

namespace: foo
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: ClusterRole

KNV1053: MissingNamespaceOnNamespacedResourceError

KNV1053: namespace-scoped resources MUST either declare either metadata.namespace or metadata.annotations.configmanagement.gke.io/namespace-selector

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1054: InvalidAnnotationValueError

Esse erro ocorre quando os configs contêm um valor inválido para uma anotação.

Exemplo de erros:

KNV1054: Values in metadata.annotations MUST be strings. To fix, add quotes around the values. Non-string values for:

metadata.annotations.foo
metadata.annotations.bar

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1055: InvalidNamespaceError

Esse erro indica que o valor de metadata.namespace não é um nome de namespace válido do Kubernetes.

Exemplo de erros:

KNV1055: metadata.namespace MUST be valid Kubernetes Namespace names. Rename "FOO" so that it:

1. has a length of 63 characters or fewer;
2. consists only of lowercase letters (a-z), digits (0-9), and hyphen '-'; and
3. begins and ends with a lowercase letter or digit.

namespace: FOO
metadata.name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1056: ManagedResourceInUnmanagedNamespace

Esse erro indica que um recurso é declarado em um namespace não gerenciado. Para corrigi-lo, remova a anotação configmanagement.gke.io/managed: disabled ou adicione a anotação ao recurso declarado.

Exemplo de erros:

KNV1056: Managed resources must not be declared in unmanaged Namespaces. Namespace "foo" is declared unmanaged but contains managed resources. Either remove the managed: disabled annotation from Namespace "foo" or declare its resources as unmanaged by adding configmanagement.gke.io/managed:disabled annotation.

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1057: IllegalDepthLabel

Esse erro indica que um recurso tem um rótulo ilegal. Para corrigi-lo, remova os rótulos que terminam com .tree.hnc.x-k8s.io/depth.

Exemplo de erros:

KNV1057: Configs MUST NOT declare labels ending with ".tree.hnc.x-k8s.io/depth". The config has disallowed labels: "label.tree.hnc.x-k8s.io/depth"

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1058: BadScopeError

Um repositório de namespaces só pode declarar recursos com escopo de namespace no namespace a que o repositório se aplica. Por exemplo, o repositório do namespaces shipping só pode gerenciar recursos no namespace shipping.

O valor de metadata.namespace é opcional. Por padrão, o Config Sync considera que todos os recursos em um repositório de namespace pertencem a esse namespace.

Por exemplo, se um config no repositório de namespaces shipping declarar metadata.namespace: billing, o comando nomos exibirá o seguinte erro.

KNV1058: Resources in the "shipping" repo must either omit metadata.namespace or declare metadata.namespace="shipping"

namespace: billing
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV 1059: MultipleKptfilesError

Um repositório de namespaces pode declarar no máximo um recurso Kptfile.

Por exemplo, se um repositório de namespaces declarar dois Kptfiles, o comando nomos apresentará o seguinte erro:

KNV1059: Namespace Repos may contain at most one Kptfile

metadata.name: package-a
group: kpt.dev
version: v1alpha1
kind: Kptfile

metadata.name: package-b
group: kpt.dev
version: v1alpha1
kind: Kptfile

For more information, see https://g.co/cloud/acm-errors#knv1059

KNV 1060: ManagementConflictError

Ao gerenciar objetos em várias fontes de verdade, podem ocorrer conflitos quando o mesmo objeto (grupo, tipo, nome e namespace correspondentes) é declarado em mais de uma fonte.

Confira alguns cenários que podem causar conflitos:

  • RootSync x RepoSync: quando o mesmo objeto é gerenciado por uma RootSync e um RepoSync, o RootSync vence. Se o RootSync for aplicado primeiro, o RepoSync informará um erro de status KNV1060. Se o RepoSync se aplicar primeiro, o RepoSync substituirá o objeto do RepoSync e o RepoSync informará um erro de status KNV1060 ao ver a atualização.

  • RepoSync x RepoSync: quando o mesmo objeto é gerenciado por dois RepoSyncs, o primeiro RepoSync a aplicar o objeto é o vencedor. O segundo RepoSync a aplicar verá que o objeto já é gerenciado pelo primeiro RepoSync e relatará um erro de status KNV1060.

  • RootSync x RootSync quando o webhook de admissão estiver ativado: quando o mesmo objeto é gerenciado por dois RootSyncs e o webhook de admissão está ativado, o primeiro RootSync a aplicar o objeto ganha. O segundo RootSync a ser aplicado receberá um erro do webhook de admissão de que o objeto já é gerenciado e relatará um erro de status KNV1060.

  • RootSync x RootSync quando o webhook de admissão estiver desativado: quando o mesmo objeto é gerenciado por dois RootSyncs e o webhook de admissão é desativado, os dois objetos RootSync lutam continuamente para adotar a propriedade do objeto e ambos relatarão o erro de status KNV1060.

Um exemplo do erro conflitante:

KNV1060: The root reconciler detects a management conflict for a resource declared in another repository. Remove the declaration for this resource from either the current repository, or the repository managed by root-reconciler.

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

Quando o erro acontece, é possível resolver o conflito atualizando a configuração para corresponder à outra fonte de verdade ou excluindo o objeto conflitante de uma das fontes.

KNV 1061: InvalidRepoSyncError

Os objetos do RepoSync precisam ser configurados corretamente para que o Config Sync sincronize a configuração dos repositórios de namespace. Um InvalidRepoSyncError informa que um RepoSync está configurado incorretamente, com uma mensagem informando explicitamente como corrigi-lo.

Por exemplo, se o repositório shipping precisa ter um RepoSync chamado repo-sync, mas o RepoSync é denominado invalid, o comando nomos apresenta o seguinte erro.

KNV1061: RepoSyncs must be named "repo-sync", but the RepoSync for Namespace "shipping" is named "invalid"

metadata.name: invalid
group: configsync.gke.io
version: v1alpha1
kind: RepoSync

KNV1062: InvalidKptfileError

Esse erro ocorre quando o Kptfile não tem um campo de inventário válido. Um Kptfile precisa ter um campo de inventário não vazio com o identificador e o namespace especificados. Para corrigi-lo, é necessário especificar os valores de .inventory.identifier e .inventory.namespace no Kptfile.

Exemplo de erros:

KNV1062: Invalid inventory invalid name

metadata.name: default-name
group: kpt.dev
version: v1alpha1
kind: Kptfile

KNV1063: KptfileExistError

Esse erro ocorre quando os Kptfiles são encontrados no repositório raiz. Os arquivos Kptfiles são compatíveis apenas com repositórios com escopo de namespace.

Para corrigir, remova os Kptfiles do repositório Root.

Exemplo de erros:

KNV1063: Found Kptfile(s) in the Root Repo. Kptfile(s) are only supported in Namespace Repos. To fix, remove the Kptfile(s) from the Root Repo.

namespace: namespace
metadata.name: default-name
group: kpt.dev
version: v1alpha1
kind: Kptfile

For more information, see https://g.co/cloud/acm-errors#knv1063

KNV1064: InvalidAPIResourcesError

Esse erro indica que não foi possível analisar o arquivo api-resources.txt em um repositório.

Exemplo de erros:

KNV1064: invalid NAMESPACED column value "other" in line:
rbac      other     Role

Re-run "kubectl api-resources > api-resources.txt" in the root policy directory

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

KNV1064: unable to find APIVERSION column. Re-run "kubectl api-resources > api-resources.txt" in the root policy directory

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

KNV1064: unable to read cached API resources: missing file permissions

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

Na versão 1.16.1 e anteriores do nomos, você também recebe este erro:

KNV1064: unable to find APIGROUP column. Re-run "kubectl api-resources > api-resources.txt" in the root policy directory

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

Isso é causado pela mudança do nome da coluna de APIGROUP para APIVERSION. Para atenuar esse problema, substitua manualmente APIVERSION em api-resources.txt de volta para APIGROUP.

KNV1065: MalformedCRDError

Esse erro ocorre quando CustomResourceDefinition é inválido. Para corrigir, verifique o campo especificado pela mensagem de erro e verifique se o valor está formatado corretamente.

Exemplo de erros:

KNV1065: malformed CustomResourceDefinition: spec.names.shortNames accessor error: foo is of the type string, expected []interface{}.

path: namespaces/foo/crd.yaml

For more information, see https://g.co/cloud/acm-errors#knv1065

KNV1066: ClusterSelectorAnnotationConflictError

Um objeto de configuração PRECISA declarar SOMENTE uma anotação de seletor de cluster. Esse erro ocorre quando a anotação legada (configmanagement.gke.io/cluster-selector) e a anotação in-line (configsync.gke.io/cluster-name-selector) existem.

Para corrigir, remova uma das anotações do campo metadata.annotations.

Por exemplo, se uma configuração de namespace declarar as duas anotações, o comando nomos emitirá o seguinte erro:

KNV1066: Config "my-namespace" MUST declare ONLY ONE cluster-selector annotation, but has both inline annotation "configsync.gke.io/cluster-name-selector" and legacy annotation "configmanagement.gke.io/cluster-selector". To fix, remove one of the annotations from:

metadata.name: my-namespace
group:
version: v1
kind: Namespace

For more information, see https://g.co/cloud/acm-errors#knv1066

KNV1067: EncodeDeclaredFieldError

Esse erro ocorre quando o reconciliador não codifica os campos declarados em um formato compatível com a aplicação do servidor. Pode ser causado por um esquema desatualizado. Para corrigir, verifique o campo especificado pela mensagem de erro e certifique-se de que ele corresponde ao esquema do tipo de recurso.

Exemplo de erros:

KNV1067: failed to encode declared fields: .spec.version not defined

metadata.name: my-namespace
group:
version: v1
kind: Namespace

For more information, see https://g.co/cloud/acm-errors#knv1067

Há um problema conhecido nos clusters que executam versões anteriores à 1.27 do Kubernetes que podem resultar nesse erro. Para resolver isso, verifique se o campo protocol está definido explicitamente em spec: containers: ports:, mesmo que você esteja usando o TCP padrão.

KNV1068: ActionableRenderingError

Esse erro indica que o processo de renderização encontra um problema que pode ser resolvido pelo usuário.

Um exemplo é que o repositório Git contém configurações do Kustomize, mas nenhum arquivo kustomization.yaml existe no diretório de sincronização do Git:

KNV1068: Kustomization config file is missing from the sync directory 'foo/bar'. To fix, either add kustomization.yaml in the sync directory to trigger the rendering process, or remove kustomization.yaml from all sub directories to skip rendering.

For more information, see https://g.co/cloud/acm-errors#knv1068

Se o erro for causado por falhas de kustomize build, atualize as configurações do Kustomize no repositório Git. É possível visualizar e validar as configurações atualizadas localmente usando nomos hydrate e nomos vet, respectivamente. Se os configs atualizados forem renderizados, você poderá enviar uma nova confirmação para corrigir o erro KNV1068. Para mais detalhes, consulte Como visualizar o resultado de todas as configurações no repo e Como verificar erros no repo.

Exemplo de erro kustomize build:

KNV1068: Error in the hydration-controller container: unable to render the source configs in /repo/source/3b724d1a17314c344fa24512239cb3b22b9d90ec: failed to run kustomize build ...

For more information, see https://g.co/cloud/acm-errors#knv1068

Se ocorrer um erro kustomize build ao extrair bases remotas de repositórios públicos, você precisará definir spec.override.enableShellInRendering como true.

Exemplo de erro kustomize build:

KNV1068: failed to run kustomize build in /repo/source/0a7fd88d6c66362584131f9dfd024024352916af/remote-base, stdout:...
no 'git' program on path: exec: "git": executable file not found in $PATH

For more information, see https://g.co/cloud/acm-errors#knv1068

KNV1069: SelfManageError

Esse erro ocorre quando um reconciliador reconcilia o próprio objeto RootSync ou RepoSync. Um objeto RootSync pode gerenciar outros objetos RootSync e RepoSync. Um objeto RepoSync pode gerenciar outros objetos do RepoSync, mas eles não podem ser autogerenciados. Para corrigir o problema, remova o objeto RootSync ou RepoSync da fonte de verdade da qual o objeto se sincroniza.

Exemplo de erros:

KNV1069: RootSync config-management-system/root-sync must not manage itself in its repo

namespace: config-management-system
metadata.name: root-sync
group: configsync.gke.io
version: v1beta1
kind: RootSync

For more information, see https://g.co/cloud/acm-errors#knv1069

KNV2001: pathError

Esse erro ocorre quando uma chamada de sistema no nível do sistema operacional acessando um recurso de sistema de arquivos falha.

Configuração YAML inválida

Quando você tem uma configuração inválida no seu arquivo YAML, talvez veja uma mensagem de erro semelhante a esta:

KNV2001: yaml: line 2: did not find expected node content path:...

Para resolver esse problema, verifique seus arquivos YAML e resolva todos os problemas de configuração. Isso pode ser causado por qualquer configuração YAML no repositório.

Caracteres especiais no nome do caminho

Se o nome do arquivo ou caminho tiver caracteres especiais, você poderá ver uma mensagem de erro semelhante a esta:

KNV2001: yaml: control characters are not allowed path:
/repo/source/.../._pod.yaml

Neste exemplo, ._pod.yaml não é um nome de arquivo válido.

Para resolver esse problema, remova os caracteres especiais dos arquivos ou nomes dos caminhos.

KNV2002: apiServerError

Isso ocorre quando uma solicitação acessando o servidor da API falha.

KNV2003: osError

Isso ocorre quando uma chamada de sistema genérica no nível do sistema operacional falha.

KNV2004: SourceError

Esse erro indica que o Config Sync não pode ler a fonte da verdade. Geralmente é causado por um dos seguintes erros:

O repositório Git está inacessível no cluster

O contêiner git-sync gera um erro nos registros indicando que não é possível acessar o repositório. Por exemplo, ssh: connect to host source.developers.google.com port 2022: Network is unreachable. Para corrigir o problema, ajuste o firewall ou a configuração de rede do cluster.

Diretório de configuração inválido

Verifique se há erros, como um valor incorreto para policyDir no objeto ConfigManagement ou spec.git.dir ou spec.oci.dir no objeto RootSync ou RepoSync. O valor do diretório está incluído no erro. Verifique o valor em relação ao repositório Git ou à imagem OCI.

Nome de gráfico inválido

Ao sincronizar de um repositório do Helm, certifique-se de definir o valor correto para spec.helm.chart. O nome do gráfico não contém a versão do gráfico ou .tgz. Verifique o nome do gráfico com o comando helm template.

Credenciais Git ou Helm inválidas

Verifique os registros do contêiner git-sync ou helm-sync em busca de um dos seguintes erros:

  • Could not read from remote repository. Ensure you have the correct access rights and the repository exists.
  • Invalid username or password. Authentication failed for ...
  • 401 Unauthorized

Para um repositório Git, verifique se as credenciais Git e o secret git-creds estão configurados corretamente.

Para um repositório do Helm, verifique se as credenciais do Helm estão configuradas corretamente.

URL do repositório Git inválido

Verifique os registros do contêiner git-sync para um erro como Repository not found.

Verifique se você está usando o formato de URL correto. Por exemplo, se você estiver usando um par de chaves SSH para autenticar o repositório do Git, verifique se o URL que você inseriu para o repositório do Git quando você configurar o Config Sync usa o protocolo SSH.

URL do repositório do Helm inválido

Verifique os registros do contêiner helm-sync para um erro como ...not a valid chart repository Verifique se você está usando o formato de URL correto. Por exemplo, se você estiver sincronizando a partir de um registro OCI, o URL precisará começar com oci://. Verifique o URL do repositório do Helm com o comando helm template.

Ramificação do Git inválida

Verifique se há um erro nos registros do contêiner git-sync, como Remote branch BRANCH_NAME not found in upstream origin ou warning: Could not find remote branch BRANCH_NAME to clone.. Observe que a ramificação padrão está definida como master, se não for especificada.

Falha na verificação do certificado do servidor

Essa falha poderá ocorrer ao se conectar a um servidor Git por HTTPS se o servidor Git estiver usando um certificado emitido por uma autoridade certificadora (CA, na sigla em inglês) que não seja reconhecida pelo cliente git-sync.

Se você gerencia sua própria CA, verifique se o servidor Git recebeu um certificado da CA e se o campo caCertSecretRef está configurado corretamente.

Problemas de permissão ao usar a conta de serviço do Google

Sem acesso ao leitor

Ao usar uma conta de serviço do Google (spec.git.gcpServiceAccountEmail, spec.oci.gcpServiceAccountEmail, ou spec.helm.gcpServiceAccountEmail) para se autenticar no Cloud Source Repositories ou no Artifact Registry, a conta de serviço do Google exige o seguinte acesso de leitor:

  • Cloud Source Repositories: roles/source.reader
  • Artifact Registry: roles/artifactregistry.reader

Caso contrário, git-sync, oci-sync ou helm-sync falharão com o erro:

failed to pull image us-docker.pkg.dev/...: GET https://us-docker.pkg.dev/v2/token?scope=repository...: DENIED: Permission \"artifactregistry.repositories.downloadArtifacts\" denied on resource \"projects/.../locations/us/repositories/...\" (or it may not exist)

ou "Err":"failed to render the helm chart: exit status 1, stdout: Error: failed to download ... para corrigir o problema, conceda à conta de serviço o acesso de leitor correto.

Vinculação de política do IAM ausente com a Identidade da carga de trabalho

Ao usar uma conta de serviço do Google para autenticação, é necessário vincular uma política de IAM entre a conta de serviço do Google e a conta de serviço do Kubernetes. Se a vinculação de política do IAM estiver ausente, você receberá o seguinte erro:

KNV2004: unable to sync repo Error in the git-sync container: ERROR: failed to call ASKPASS callback URL: auth URL returned status 500, body: "failed to get token from credentials: oauth2/google: status code 403: {\n \"error\": {\n \"code\": 403,\n \"message\": \"The caller does not have permission\",\n \"status\": \"PERMISSION_DENIED\"\n }\n}\n"

Para corrigir o problema, crie a seguinte vinculação de política do IAM:

gcloud iam service-accounts add-iam-policy-binding \
   --role roles/iam.workloadIdentityUser \
   --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

Substitua:

  • PROJECT_ID: se você estiver usando a Identidade da carga de trabalho do GKE, adicione a ID do projeto da sua organização. Se você usa a Identidade da carga de trabalho da frota, é possível utilizar duas IDs de projetos diferentes. Em serviceAccount:PROJECT_ID, adicione o ID do projeto da frota em que o cluster está registrado. Em GSA_NAME@PROJECT_ID, adicione um ID do projeto para qualquer projeto com acesso de leitura ao repositório no Cloud Source Repositories.

  • KSA_NAME: a conta de serviço do Kubernetes do reconciliador. Para repositórios raiz, se o nome RootSync for root-sync, KSA_NAME será root-reconciler. Caso contrário, será root-reconciler-ROOT_SYNC_NAME.

    Para repositórios de namespace, se o nome do RepoSync for repo-sync, KSA_NAME será ns-reconciler-NAMESPACE. Caso contrário, será ns-reconciler-NAMESPACE-REPO_SYNC_NAME.

  • GSA_NAME: a conta de serviço personalizada do Google que você quer usar para se conectar ao Cloud Source Repositories. Verifique se a conta de serviço do Google selecionada tem o papel source.reader.

Escopo cloud-platform ausente para acessar o Cloud Source Repositories

Ao conceder a uma conta de serviço do Google acesso ao repositório Git no Cloud Source Repositories, o escopo somente leitura precisa ser incluído nos escopos de acesso dos nós no cluster.

O escopo somente leitura pode ser adicionado incluindo cloud-source-repos-ro na lista --scopes especificada no momento da criação do cluster ou usando o escopo cloud-platform no momento da criação do cluster. Exemplo:

gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

Se o escopo somente leitura estiver ausente, você verá um erro semelhante ao seguinte:

Error in the git-sync container: {"Msg":"unexpected error syncing repo, will retry","Err":"Run(git clone -v --no-checkout -b main --depth 1 https://source.developers.google.com/p/PROJECT_ID/r/csr-auth-test /repo/source): exit status 128: { stdout: \"\", stderr: \"Cloning into '/repo/source'...\\nremote: INVALID_ARGUMENT: Request contains an invalid argument\\nremote: [type.googleapis.com/google.rpc.LocalizedMessage]\\nremote: locale: \\\"en-US\\\"\\nremote: message: \\\"Invalid authentication credentials. Please generate a new identifier: https://source.developers.google.com/new-password\\\"\\nremote: \\nremote: [type.googleapis.com/google.rpc.RequestInfo]\\nremote: request_id: \\\"fee01d10ba494552922d42a9b6c4ecf3\\\"\\nfatal: unable to access 'https://source.developers.google.com/p/PROJECT_ID/r/csr-auth-test/': The requested URL returned error: 400\\n\" }","Args":{}}

Escopo storage-ro ausente para acessar o Artifact Registry

As camadas de imagem são mantidas em buckets do Cloud Storage. Ao conceder a uma conta de serviço do Google acesso à imagem OCI ou Helm Chart no Artifact Registry, o escopo somente leitura precisa ser incluído em escopos de acesso para os nós no cluster.

O escopo somente leitura pode ser adicionado incluindo storage-ro na lista --scopes especificada no momento da criação do cluster ou usando o escopo cloud-platform no momento da criação do cluster. Exemplo:

gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

Se o escopo somente leitura estiver ausente, você verá um erro semelhante ao seguinte:

Error in the oci-sync container: {"Msg":"unexpected error fetching package, will retry","Err":"failed to pull image us-docker.pkg.dev/...: GET https://us-docker.pkg.dev/v2/token?scope=repository%3A...%3Apull\u0026service=us-docker.pkg.dev: UNAUTHORIZED: failed authentication","Args":{}}

Talvez a mensagem de erro não inclua todos os detalhes do que causou o erro, mas ela fornecerá um comando que imprime os logs do contêiner git-sync que podem ter mais informações.

Se você estiver usando as APIs RootSync ou RepoSync:

kubectl logs -n config-management-system -l app=reconciler -c git-sync

Se você não ativar as APIs RootSync ou RepoSync:

kubectl logs -n config-management-system -l app=git-importer -c git-sync

Falha em git fetch com o erro remote did not send all necessary objects

O Config Sync cria um clone superficial do seu repositório Git. Em casos raros, o Config Sync talvez não consiga encontrar a confirmação no clone superficial. Quando isso acontece, o Config Sync aumenta o número de confirmações do Git a serem buscadas.

Para definir o número de confirmações do Git a serem buscadas, defina o campo spec.override.gitSyncDepth em um objeto RootSync ou RepoSync.

  • Se esse campo não for fornecido, o Config Sync o configurará automaticamente.
  • O Config Sync fará um clone completo se esse campo for 0 e um clone superficial se ele for maior que 0.
  • Não é permitido definir esse campo como um valor negativo.

Se você instalou o Config Sync usando o console do Google Cloud ou a CLI do Google Cloud, crie um objeto RootSync editável para definir spec.override.gitSyncDepth. Para saber mais, confira Configurar o Config Sync com comandos kubectl.

Veja um exemplo de configuração do número de confirmações do Git a serem buscadas em 88:

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync
  namespace: config-management-system
spec:
  override:
    gitSyncDepth: 88
  git:
    ...

Execute o seguinte comando para verificar se a alteração entra em vigor (GIT_SYNC_DEPTH precisa ser definido como 88 no campo data do ConfigMap root-reconciler-git-sync):

kubectl get cm root-reconciler-git-sync -n config-management-system -o yaml

É possível substituir o número de confirmações do Git para buscar em um reconciliador de namespace da mesma forma.

Não foi possível montar a chave secreta do Git

Se você receber o seguinte erro quando o contêiner git-sync tentar sincronizar um repositório com um secret, ele não será ativado no contêiner git-sync:

KNV2004: unable to sync repo Error in the git-sync container: ERROR: can't configure SSH: can't access SSH key: stat /etc/git-secret/ssh: no such file or directory: lstat /repo/root/rev: no such file or directory

Esse erro pode ser causado pela mudança do tipo de autenticação do repositório Git de none, gcenode ou gcpserviceaccount para outros tipos que precisam de um secret.

Para resolver esse problema, execute os seguintes comandos para reiniciar o Reconciler Manager e o Reconcilers:

# Stop the reconciler-manager Pod. The reconciler-manager Deployment will spin
# up a new Pod which can pick up the latest `spec.git.auth`.
kubectl delete po -l app=reconciler-manager -n config-management-system

# Delete the reconciler Deployments. The reconciler-manager will recreate the
# reconciler Deployments with correct volume mount.
kubectl delete deployment -l app=reconciler -n config-management-system

KNV2005: ResourceFightError

Esse erro indica que o Config Sync está competindo com outro controlador por um recurso. Esses conflitos consomem uma grande quantidade de recursos e podem prejudicar seu desempenho. Os conflitos também são conhecidos como contenção de recursos.

Se você estiver usando a API RootSync ou RepoSync com o Config Sync versão 1.15.0 ou mais recente, vai ser possível analisar os erros usando o comando nomos status ou verificando o campo de status no objeto RootSync ou RepoSync.

Se você estiver usando a API RootSync ou RepoSync com uma versão do Config Sync anterior à 1.15.0, será possível analisar os registros do Config Sync reconciler executando o seguinte comando:

kubectl logs -n config-management-system -l app=reconciler -c reconciler

Se você não tiver as APIs RootSync ou RepoSync ativadas, para detectar conflitos, verifique os registros git-importer do Config Sync executando o seguinte comando:

kubectl logs --namespace config-management-system deployment/git-importer -c importer

Se você vir KNV2005 nos resultados, isso significa que há uma disputa de recursos.

Para encontrar mais informações sobre conflitos de recursos, veja as atualizações do arquivo YAML do recurso executando o seguinte comando:

 kubectl get resource --watch -o yaml

Substitua resource pelo tipo de recurso que está sendo disputado. É possível ver qual recurso adicionar com base nos resultados do registro.

Esse comando retorna um fluxo do estado do recurso depois que as atualizações são aplicadas ao servidor da API. É possível usar uma ferramenta de comparação de arquivos para comparar a saída.

Alguns recursos devem pertencer a outros controladores (por exemplo, alguns operadores instalam ou mantêm CRDs). Esses outros controladores removem automaticamente todos os metadados específicos do Config Sync. Se outro componente no cluster do Kubernetes remover metadados do Config Sync, pare de gerenciar o recurso. Para informações sobre como fazer isso, consulte Como parar de gerenciar um objeto gerenciado. Outra opção,sSe você não quiser que o Config Sync mantenha o estado do objeto no cluster após ele existir, adicione a anotação client.lifecycle.config.k8s.io/mutation: ignore ao objeto em que o Config Sync deve ignorar as mutações. Para informações sobre como fazer isso, consulte Ignorar mutações do objeto.

KNV2006: erros de gerenciamento de config

Para evitar a exclusão acidental, o Config Sync não permite a remoção de todos os namespaces ou recursos com escopo de cluster em uma única confirmação.

Se você confirmou alterações na tentativa de remover todos os recursos, corrija-as no status original e depois exclua-as em duas etapas.

Se o webhook de admissão do Config Sync estiver desativado, será possível reverter a confirmação que exclui todos os recursos.

Se o webhook de admissão do Config Sync estiver ativado, o namespace pode estar travado. Para corrigir isso, execute as seguintes etapas:

  1. Desative o Config Sync e aguarde até que todos os recursos sejam limpos ou estejam em um status estável. Por exemplo, execute kubectl get ns para garantir que os namespaces sejam excluídos.
  2. Reativar o Config Sync.
  3. Reverta a confirmação que exclui todos os recursos.

Como excluir

Se você quiser excluir o conjunto completo de recursos em gerenciamento, serão necessárias duas etapas:

  1. Remova apenas um namespace ou recurso com escopo de cluster em uma primeira confirmação e permita que o Config Sync sincronize essas alterações.
  2. Remova o recurso final em uma segunda confirmação.

KNV2008: APIServerConflictError

Esse tipo de erro ocorre quando um recurso no servidor de API é modificado ou excluído enquanto o Config Sync também está tentando modificá-lo. Se esse tipo de erro só aparecer na inicialização ou com pouca frequência, ignore-os.

Se esses erros não forem temporários (persistirem por vários minutos), isso pode indicar um problema sério, o que nomos status reportará conflitos de recursos.

Exemplo de erros:

KNV2008: tried to create resource that already exists: already exists

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

For more information, see https://g.co/cloud/acm-errors#knv2008

KNV2008: tried to update resource which does not exist: does not exist

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

For more information, see https://g.co/cloud/acm-errors#knv2008

KNV2008: tried to update with stale version of resource: old version

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

For more information, see https://g.co/cloud/acm-errors#knv2008

KNV2009: ApplyError

Esse é um erro genérico indicando que o Config Sync falhou ao sincronizar algumas configurações com o cluster. Exemplo de erros:

KNV2009: no matches for kind "Anvil" in group "acme.com".

É proibida a operação em determinados recursos

Se você receber um erro semelhante ao seguinte:

KNV2009: failed to list demo.foobar.com/v1, Kind=Cluster: clusters.demo.foobar.com is forbidden: User "system:serviceaccount:config-management-system:ns-reconciler-abc" cannot list resource "clusters" in API group "demo.foobar.com" in the namespace "abc"

Esse erro significa que o reconciliador de namespace não tem o acesso necessário para aplicar configurações ao cluster. Para corrigir isso, siga a etapa em Configurar a sincronização a partir de mais de uma fonte de verdade para configurar um RoleBinding para conceder a permissão da conta de serviço do reconciliador de namespace com base no que aparece na mensagem de erro.

Tempo limite de solicitação de webhook de admissão

Se você receber o seguinte erro quando o reconciliador tentar aplicar uma configuração ao cluster, a porta do webhook de admissão 8676 poderá ser bloqueada pelo firewall para a rede do plano de controle:

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s: dial tcp 10.1.1.186:8676: i/o timeout

Para resolver esse problema, adicione uma regra de firewall para autorizar a porta 8676, que o webhook de admissão do Config Sync usa para a prevenção de deslocamento.

Conexão do webhook de entrada recusada

Você pode receber o seguinte erro quando o reconciliador tenta aplicar uma configuração ao cluster:

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post "https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s": dial tcp 10.92.2.14:8676: connect: connection refused

Isso significa que o webhook de admissão ainda não está pronto. É um erro temporário que você talvez você veja ao inicializar o Config Sync.

Se o problema persistir, consulte a implantação do webhook de admissão para ver se os pods podem ser programados e estão íntegros.

kubectl describe deploy admission-webhook -n config-management-system

kubectl get pods -n config-management-system -l app=admission-webhook

O recurso ResourceGroup excede o limite de tamanho de objeto etcd

Se você receber o seguinte erro quando o reconciliador tentar aplicar configurações ao cluster:

KNV2009: too many declared resources causing ResourceGroup.kpt.dev, config-management-system/root-sync failed to be applied: task failed (action: "Inventory", name: "inventory-add-0"): Request entity too large: limit is 3145728. To fix, split the resources into multiple repositories.

Esse erro significa que o recurso ResourceGroup excede o limite de tamanho de objeto etcd. Recomendamos dividir o repositório do Git em vários repositórios. Se não for possível dividir o repositório do Git, no Config Sync v1.11.0 e versões posteriores, é possível atenuar ele desativando os dados de status de superfície. Para isso, defina o campo .spec.override.statusMode do objeto RootSync ou RepoSync como disabled. Ao fazer isso, o Config Sync interromperá a atualização do status dos recursos gerenciados no objeto ResourceGroup. Isso reduz o tamanho do objeto ResourceGroup. No entanto, não será possível ver o status dos recursos gerenciados de nomos status ou gcloud alpha anthos config sync.

Tempo limite de reconciliação de aplicação da dependência

Você talvez receba um erro semelhante ao exemplo a seguir quando o reconciliador tentar aplicar objetos com a anotação config.kubernetes.io/depends-on ao cluster:

KNV2009: skipped apply of Pod, bookstore/pod4: dependency apply reconcile timeout: bookstore_pod3__Pod  For more information, see https://g.co/cloud/acm-errors#knv2009

Esse erro significa que o objeto de dependência não reconciliou dentro do tempo limite padrão de reconciliação de cinco minutos. O Config Sync não pode aplicar o objeto dependente porque com a anotação config.kubernetes.io/depends-on o Config Sync só aplica objetos na ordem que você quer. É possível modificar o tempo limite de reconciliação padrão para um tempo maior, configurando spec.override.reconcileTimeout.

As informações do inventário são nulas

Se você receber o seguinte erro quando o reconciliador tentar aplicar configurações ao cluster, é provável que o inventário não tenha recursos ou o manifesto tenha uma anotação não gerenciada:

KNV2009: inventory info is nil\n\nFor more information, see https://g.co/cloud/acm-errors#knv2009

Para resolver esse problema, tente o seguinte:

  1. Evite configurar sincronizações em que todos os recursos tenham a anotação configmanagement.gke.io/managed: disabled. Para isso, garanta que pelo menos um recurso seja gerenciado pelo Config Sync.
  2. Adicione a anotação configmanagement.gke.io/managed: disabled somente após concluir uma sincronização inicial do recurso sem essa anotação.

Vários modelos de objeto de inventário

Se você receber o seguinte erro quando o reconciliador tentar aplicar configurações ao cluster, é provável que você tenha uma configuração de inventário de kpt na fonte da verdade, por exemplo, um repositório Git:

KNV2009: Package has multiple inventory object templates.  The package should have one and only one inventory object template.   For more information, see https://g.co/cloud/acm-errors#knv2009

O problema acontece porque o Config Sync gerencia a própria configuração de inventário. Para resolver esse problema, exclua a configuração do inventário na sua fonte de verdade.

KNV2010: resourceError

Esse é um erro genérico que indica um problema com um recurso ou conjunto de recursos. A mensagem inclui os recursos específicos que causaram o erro.

KNV2010: Resources were improperly formatted.

Affected resources:
source: system/hc.yaml
group: configmanagement.gke.io
kind: Repo

KNV2011: MissingResourceError

Isso indica que um recurso específico é necessário para continuar, mas ele não foi encontrado. Por exemplo, o ConfigManagement Operator tentou atualizar um recurso, mas o recurso foi excluído ao calcular a atualização.

KNV2012: MultipleSingletonsError

Esse erro informa que mais de uma instância de um APIResource foi encontrada em um contexto em que exatamente um APIResource é permitido. Por exemplo, apenas um recurso de repo pode existir em um cluster.

KNV2013: InsufficientPermissionError

Esse erro ocorre quando um reconciliador de namespace tem permissões insuficientes para gerenciar recursos. Para corrigir, certifique-se de que o acumulador tenha permissões suficientes.

Exemplo de erros:

KNV2013: could not create resources: Insufficient permission. To fix, make sure the reconciler has sufficient permissions.: deployments.apps is forbidden: User 'Bob' cannot create resources

For more information, see https://g.co/cloud/acm-errors#knv2013

KNV2014: InvalidWebhookWarning

Esse aviso ocorre quando a configuração do webhook do Config Sync é modificada ilegalmente. As configurações de webhook ilegais são ignoradas.

Exemplo de aviso:

KNV2014: invalid webhook

KNV2015: InternalRenderingError

Esse erro indica que o processo de renderização encontra um problema interno. Um exemplo não consegue acessar o sistema de arquivos. Isso pode indicar que o pod não está íntegro. Reinicie o pod do reconciliador executando o seguinte comando:

# 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>

Se o erro persistir após a reinicialização, crie um relatório de bug.

KNV2016: TransientError

Esse erro representa um problema temporário que será resolvido automaticamente posteriormente.

Por exemplo, quando a confirmação de origem é alterada ao listar arquivos, o seguinte erro pode ocorrer:

KNV2016: source commit changed while listing files, was 90c1d9e9633a988ee3c3fc4dd145e62af30e9d1f, now 1d60597c56ebe07b269cc0d5ff126f638626c3b7. It will be retried in the next sync

For more information, see https://g.co/cloud/acm-errors#knv2016

Outro exemplo é quando o estado de renderização não corresponde às configurações de origem:

sync source contains only wet configs and hydration-controller is running

For more information, see https://g.co/cloud/acm-errors#knv2016

KNV9998: InternalError

KNV9998 indica um problema com o próprio comando nomos. Envie um relatório do bug com o comando exato que você executou e a mensagem que recebeu.

Exemplo de erros:

KNV9998: we made a mistake: internal error

For more information, see https://g.co/cloud/acm-errors#knv9998

KNV9999: UndocumentedError

Você encontrou um erro sem uma mensagem de erro documentada. Ainda não escrevemos documentação específica para o erro encontrado.

Outras mensagens de erro

O prefixo KNV é exclusivo do Config Sync, mas você pode receber uma mensagem de erro sem esse prefixo.

Não é possível criar exportadores

Quando um componente no Open Telemetry Collector não pode acessar a conta de serviço padrão no mesmo namespace, você pode observar que o pod otel-collector em config-management-monitoring fica no status CrashLoopBackoff ou ver mensagens de erro como estas:

Error: cannot build exporters: error creating stackdriver exporter: cannot configure Google Cloud metric exporter: stackdriver: google: could not find default credentials. See https://developers.google.com/accounts/docs/application-default-credentials for more information.
Error: Permission monitoring.timeSeries.create denied (or the resource may not exist).

Esse problema geralmente acontece quando a Identidade da carga de trabalho está ativada no cluster.

Para resolver esse problema, siga as instruções em Como monitorar o Config Sync para conceder permissão de gravação de métrica à conta de serviço padrão.

Se o erro persistir, configure o pod otel-collector para que as alterações entrem em vigor.

Se você estiver usando uma solução de monitoramento personalizada, mas tiver feito a bifurcação do ConfigMap otel-collector-googlecloud padrão, verifique e realoque qualquer diferença.

Falha na verificação do certificado do servidor

Se o contêiner git-sync não clonar o repositório Git, talvez você veja a seguinte mensagem de erro:

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

Essa mensagem indica que o servidor Git está configurado com certificados de uma autoridade de certificação (CA, na sigla em inglês) personalizada. No entanto, a CA personalizada não está configurada corretamente, resultando na falha do contêiner git-sync para clonar o repositório Git.

Primeiro, verifique se o campo spec.git.caCertSecretRef.name foi especificado no objeto RootSync ou RepoSync e verifique se o objeto Secret existe.

Se o campo tiver sido configurado e o objeto Secret existir, verifique se o objeto Secret contém os certificados completos.

Dependendo de como a CA personalizada é provisionada, as abordagens para verificar os certificados completos podem variar.

Veja um exemplo de como listar os certificados do servidor:

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

Solicite à equipe de administração de rede os certificados de CA.

Não foi possível recuperar o secret de pull, a imagem pode não ser bem-sucedida

Se você estiver usando um registro particular com GKE no VMware, a instalação ou o upgrade do Config Sync podem ficar travados. Você verá um erro semelhante a este:

Error message: "MESSAGE": "Unable to retrieve pull secret, the image pull may not succeed." pod="config-management-system/config-management-operator-7d84fccc5c-khrx4" secret="" err="secret \"private-registry-creds\" not found"",

Para resolver esse problema, siga as etapas em Atualizar o Policy Controller, o Config Sync e o Config Controller usando um registro particular antes de instalar ou fazer upgrade do Config Sync.

Erros de webhook

A seção a seguir detalha os erros que podem ser encontrados ao usar o manual de admissão do Config Sync. Para saber mais sobre o webhook, consulte Evitar desvio de configuração.

Falha ao excluir todos os tipos de recursos

Um namespace travado na fase Terminating precisa ter a seguinte condição:

    message: 'Failed to delete all resource types, 1 remaining: admission webhook
      "v1.admission-webhook.configsync.gke.io" denied the request: system:serviceaccount:kube-system:namespace-controller
      is not authorized to delete managed resource "_configmap_bookstore_cm1"'
    reason: ContentDeletionFailed
    status: "True"
    type: NamespaceDeletionContentFailure

Esse erro acontece quando você tenta excluir um namespace de um repositório raiz, mas alguns objetos no namespace ainda são gerenciados ativamente por um reconciliador de namespace. Quando um namespace é excluído, o controlador de namespace, que tem a conta de serviço system:serviceaccount:kube-system:namespace-controller, tenta excluir todos os objetos nesse namespace. No entanto, o webhook de admissão do Config Sync só permite que o reconciliador de raiz ou de namespace exclua esses objetos e nega o controlador de namespaces para excluí-los.

Para resolver esse problema, exclua o webhook de admissão do Config Sync:

kubectl delete deployment.apps/admission-webhook -n config-management-system

O ConfigManagement Operator recria o webhook de admissão do Config Sync.

Se essa solução alternativa não funcionar, talvez seja necessário reinstalar o Config Sync.

Para evitar que o erro se repita, remova o repositório de namespace antes de remover o namespace.

O campo de webhooks não foi encontrado em ValidatingWebhookConfiguration

Os erros a seguir aparecem nos registros do webhook de admissão do Config Sync ao executar kubectl logs -n config-management-system -l app=admission-webhook se root-reconciler não tiver sincronizado nenhum recurso com o cluster:

cert-rotation "msg"="Unable to inject cert to webhook." "error"="`webhooks` field not found in ValidatingWebhookConfiguration" "gvk"={"Group":"admissionregistration.k8s.io","Version":"v1","Kind":"ValidatingWebhookConfiguration"} "name"="admission-webhook.configsync.gke.io"
controller-runtime/manager/controller/cert-rotator "msg"="Reconciler error" "error"="`webhooks` field not found in ValidatingWebhookConfiguration" "name"="admission-webhook-cert" "namespace"="config-management-system"

Esse erro pode pode acontecer se root-reconciler ainda não estiver pronta ou não houver nada a ser sincronizado do repositório Git (por exemplo, o diretório de sincronização está vazio). Se o problema persistir, verifique a integridade do root-reconciler:

kubectl get pods -n config-management-system -l configsync.gke.io/reconciler=root-reconciler

Se o root-reconciler estiver em um loop de falhas ou com OOMKill, aumente os limites de recursos.

O webhook de admissão negou uma solicitação

Se você receber o seguinte erro ao tentar aplicar uma alteração a um campo que o Config Sync gerencia, é possível que tenha feito uma alteração conflitante:

error: OBJECT could not be patched: admission webhook "v1.admission-webhook.configsync.gke.io"
denied the request: fields managed by Config Sync can not be modified

Quando você declara um campo em uma configuração e seu repositório é sincronizado com um cluster, o Config Sync gerencia esse campo. Qualquer alteração que você tentar fazer nesse campo será uma alteração conflitante.

Por exemplo, se você tiver uma configuração de implantação no seu repositório com um rótulo environment:prod e tentar alterar esse rótulo para environment:dev no seu cluster, haverá um conflito e a mensagem de erro anterior. No entanto, se você adicionar um novo rótulo (por exemplo, tier:frontend) à implantação, não haverá conflito.

Para que o Config Sync ignore qualquer alteração em um objeto, adicione a anotação descrita em Como ignorar mutações de objetos.

Permissão negada

Se você receber um erro semelhante ao exemplo abaixo quando tentar configurar o Config Sync, talvez não tenha o papel de Administrador do GKE Hub:

Permission 'gkehub.features.create' denied on 'projects/PROJECT_ID/locations/global/features/configmanagement'

Para garantir que você tenha as permissões necessárias, verifique se concedeu os papéis do IAM necessários.

A seguir