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:
configmanagement.gke.io/managed
: para mais informações sobre o uso, consulte Como gerenciar objetos.configmanagement.gke.io/namespace-selector
: para mais informações sobre o uso, consulte Objetos com escopo de namespace.configmanagement.gke.io/cluster-selector
: para mais informações sobre o uso, consulte ClusterSelectors.
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. EmserviceAccount:PROJECT_ID
, adicione o ID do projeto da frota em que o cluster está registrado. EmGSA_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 forroot-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 papelsource.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:
- 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. - Reativar o Config Sync.
- 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:
- 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.
- 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:
- 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. - 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
- Saiba mais sobre o monitoramento do Config Sync.
- Se precisar de mais ajuda, entre em contato com o Cloud Customer Care.