Referência de erros

Nesta página, descrevemos os códigos de erro do Config Sync e as ações recomendadas para lidar com esses erros.

As mensagens de erro do Config Sync consistem em um ID de erro no formato KNV1234, em que 1234 é um número exclusivo, 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 de nomos, V é específica para erros detectáveis no estado inicial do repositório e do cluster. Os códigos para erros detectáveis no estado inicial do repositório e do cluster têm o formato KNV1XXX. Os códigos de erros que só podem ser detectados durante a execução são no formato KNV2XXX.

Tabela de erros do KNV

Código do erro Descrição Ação recomendada

O ID de InternalError mudou para KNV9998 com a versão 1.6.1 do Config Sync.

N/A

Obsoleto no Config Sync 1.3.

N/A

Obsoleto no Config Sync 1.3.

N/A

Ao usar uma estrutura de repositório hierárquica, 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 e tem diretórios herdados dele. Consequentemente, os diretórios de namespace abstratos precisam ter subdiretórios. Um diretório que contém uma configuração de namespace é um diretório de namespace e não pode ser herdado. Por isso, não pode ter subdiretórios.

Remova a configuração do namespace do diretório pai ou mova o subdiretório para outro lugar.

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

Remova configmanagement.gke.io/namespace-selector do campo metadata.annotations.

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 Git, deixando a configuração marcada. A anotação configmanagement.gke.io/managed=enabled não é necessária.

Verifique se a anotação de gerenciamento é configmanagement.gke.io/managed=disabled.

Para mais informações, consulte Como gerenciar objetos.

Não foi possível analisar um objeto declarado no repositório.

Valide o formato YAML. Por exemplo, use o comando kubectl --validate.

Se nomos vet retornar esse erro em um tipo com group: configsync.gke.io, como um RepoSync, faça o download de v1.6.0-rc.6 ou mais recente na página de downloads para resolver.

Ao usar um repositório não estruturado, as configurações não podem ser declaradas em um diretório de namespace abstrato.

Mova a configuração listada na mensagem de erro para um diretório de namespace.

Para mais informações, consulte Como usar um repositório não estruturado.

Ao usar uma estrutura de repositório hierárquica, as configurações precisam declarar namespaces que correspondam ao diretório de namespace que os contém ou omitir o campo.

Atualize o campo de namespace identificado na mensagem de erro.

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

As configurações não podem declarar anotações sem suporte começando com configmanagement.gke.io.

Verifique se você está usando uma das seguintes anotações compatíveis:

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 uso pelo Config Sync.

Atualize os marcadores identificados na mensagem de erro. Por exemplo, se você tentou declarar um rótulo chamado
configmanagement.gke.io/example-label: label-value,
ele pode ser alterado para
example-label: label-value.

Obsoleto no Config Sync 1.3.

 N/A

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

Crie qualquer seletor ausente ou, se ele tiver sido removido, remova as configurações que se referem a ele.

Elas usam a sintaxe correta, mas foi encontrado um erro de sintaxe.

Especifique a configuração usando o esquema de dados adequado:

Obsoleto no Config Sync 1.3.2 N/A

Ao usar a estrutura hierárquica do repositório, é necessário que haja um config para o ConfigManagement Operator no diretório system/ do repositório. Essa configuração precisa incluir as informações necessárias, como a versão semântica do repositório.

Defina pelo menos uma configuração mínima para o ConfigManagement Operator. Para mais informações, consulte Estrutura do repositório hierárquico.

Obsoleto no Config Sync 1.3. N/A

Ao usar a estrutura hierárquica do repositório, os namespaces não podem ser declarados diretamente no diretório namespaces/.

Crie um subdiretório para as configurações do namespace listadas na mensagem de erro. Para mais informações, consulte Estrutura do repositório hierárquico.

Ao usar uma estrutura de repositório hierárquica, uma configuração de namespace declara metadata.name, e o valor dela precisa corresponder ao nome do diretório do namespace. Corrija o metadata.name do namespace ou o diretório dele.

Nenhuma CustomResourceDefinition foi definida para o recurso no cluster.

Criar um CustomResourceDefinition para o recurso referenciado na mensagem de erro. Os tipos de recursos que não são objetos integrados do Kubernetes precisam ter um CustomResourceDefinition.

Quando você usa um repositório hierárquico, não é possível declarar as configurações desse tipo no diretório system/.

Remova do diretório system/ o recurso referenciado na mensagem de erro. Para mais informações, consulte Estrutura do repositório hierárquico.

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

Se o formato do repositório for compatível com a versão compatível, atualize o campo spec.version. Se precisar fazer upgrade, siga as instruções nas notas da versão.

Os nomes de diretório precisam ter menos de 64 caracteres, consistir em caracteres alfanuméricos minúsculos ou "-" e começar e terminar com um caractere alfanumérico.

Renomeie ou remova o diretório com nome incorreto.

As configurações do mesmo tipo precisam ter nomes exclusivos no mesmo namespace e nos namespaces pais abstratos.

Renomeie ou remova as configurações referenciadas na mensagem de erro para que todas tenham nomes exclusivos.

Não é possível ter vários recursos de namespace no mesmo diretório.

Remova as configurações duplicadas para que apenas um recurso de namespace permaneça.

Todas as configurações precisam declarar metadata.name.

Adicione o campo metadata.name às configurações problemáticas.

O tipo Repo.configmanagement.gke.io não será permitido se sourceFormat estiver definido como unstructured.

Remova a configuração problemática ou converta seu repositório para usar sourceFormat: hierarchy.

Se você estiver usando um repositório hierárquico, só poderá declarar os tipos HierarchyConfig e Repo no diretório system/.

Verifique se as configurações declaradas no diretório system/ são um dos tipos permitidos. Se não estiver, mova-o para outro diretório.

É proibido declarar o namespace config-management-system ou os recursos dele.

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

Se você declarou o namespace config-management-system, remova-o e todas as configurações nesse namespace.

Se você declarou os namespaces resource-group-system ou config-management-monitoring, não gerencie o namespace do controlador:

  1. Atualize o Config Sync para parar de gerenciar o namespace e todos os recursos declarados abaixo.
  2. Aguarde uma sincronização e confirme se os recursos correspondentes ainda estão disponíveis no cluster, mas não no nomos status.
  3. Remova da origem o arquivo YAML do namespace do controlador.
  4. Deixe o Config Sync retomar o gerenciamento dos recursos.

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

O metadata.name fornecido tem um formato inválido.

Mude metadata.name para atender às seguintes condições:

  • Ter menos de 254 caracteres
  • Ter caracteres alfanuméricos minúsculos, "-" ou "."
  • Começar e terminar com um caractere alfanumérico

Se metadata.name for inválido e o recurso original oferecer suporte para ele, use o campo spec.resourceID para que você não se restrinja a essas limitações. Para mais informações, consulte Como gerenciar recursos com o campo resourceID.

Obsoleto no Config Sync 1.3. N/A

É proibido declarar um objeto com escopo de namespace fora do diretório namespaces/.

Mova as configurações problemáticas para um diretório legal. Para mais informações sobre objetos com escopo de namespace, consulte Objetos com escopo de namespace.

É proibido declarar um objeto com escopo de cluster fora do diretório cluster/.

Mova as configurações problemáticas para um diretório legal. Para mais informações sobre objetos com escopo de cluster, consulte Objetos com escopo de cluster.

Obsoleto no Config Sync 1.3. N/A

Esse tipo de recurso não pode ser declarado em um HierarchyConfig.

Remova o recurso problemático. Para ler mais sobre HierarchyConfig, consulte Como desativar a herança para um tipo de objeto.

Um valor ilegal para HierarchyMode foi detectado em um HierarchyConfig.

Mude HierarchyMode para none ou inherit. Para ler mais sobre HierarchyConfigs, consulte Como desativar a herança para um tipo de objeto.

O Config Sync não pode configurar este objeto.

 Remova a configuração problemática do repositório.

Um diretório de namespace abstrato com configurações precisa ter pelo menos um subdiretório de namespace.

Adicione um diretório de namespace no diretório de namespace abstrato, adicione uma configuração de namespace ao diretório de namespace abstrato ou remova as configurações do diretório de namespace abstrato.

As configurações com metadata.ownerReference especificado não são permitidas.

Remova o campo status do repositório de origem. Para configurações de terceiros que não são suas, use kustomize patches para remover em massa os campos status especificados nos manifestos.

Este HierarchyConfig faz referência a um recurso que tem escopo de cluster. Objetos com escopo de cluster não são permitidos em HierarchyConfig.

Atualize o HierarchyConfig para que ele não faça mais referência ao recurso problemático.

Não é permitido remover uma definição de recurso personalizada (CRD, na sigla em inglês) e deixar os recursos personalizados correspondentes no repositório.

Remova a CRD e os recursos personalizados.

O CustomResourceDefinition tem um nome inválido.

Mude o nome para a recomendação na mensagem de erro.

A configuração está usando um grupo e um tipo descontinuados.

Mude o grupo ou o tipo para a recomendação na mensagem de erro.

Recursos com escopo de cluster não podem declarar metadata.namespace.

 Remova o campo metadata.namespace do recurso com escopo de cluster.

Os recursos com escopo de namespace precisam declarar metadata.namespace ou metadata.annotations.configmanagement.gke.io/namespace-selector.

Adicione o campo ausente ao recurso com escopo de namespace.

As configurações contêm um valor inválido para uma anotação.

Siga as instruções na mensagem para resolvê-lo.

O valor de metadata.namespace não é um nome de namespace válido do Kubernetes.

Atualize o valor de metadata.namespace para que ele obedeça a estas regras:

  • Tem até 63 caracteres
  • Consiste apenas em letras minúsculas (a-z), dígitos (0-9) e hífen "-"
  • Começa e termina com uma letra minúscula ou um dígito

Um recurso é declarado em um namespace não gerenciado.

Remova a anotação configmanagement.gke.io/managed: disabled ou adicione a anotação ao recurso declarado.

Um recurso tem um rótulo ilegal.

Remova os marcadores ilegais listados na mensagem de erro.

Um repositório de namespace só pode declarar recursos com escopo de namespace no namespace a que ele se aplica.

Verifique se todos os repositórios de namespace estão declarando corretamente os recursos com escopo de namespace. Por exemplo, o repositório do repositório de namespace shipping só pode gerenciar recursos no namespace shipping. O valor de metadata.namespace é opcional. Por padrão, o Config Sync supõe que todos os recursos em um repositório de namespace pertencem a esse namespace.

Por exemplo, se uma configuração no repositório de namespace shipping declarar metadata.namespace: billing, você receberá um erro.

Além de garantir que os recursos com escopo de namespace sejam declarados corretamente, verifique se os namespaces estão declarados no repositório raiz. Isso é necessário porque os namespaces têm escopo de cluster.

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

 Remova todos, exceto um recurso Kptfile.

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

Por exemplo, quando o mesmo objeto é gerenciado por um RootSync e um RepoSync, o RootSync vence. Se o RootSync se aplicar primeiro, o RepoSync informará um erro de status do KNV1060. Se o RepoSync se aplicar primeiro, o RootSync substituirá o objeto do RepoSync e o RepoSync informará um erro de status do KNV1060 quando detectar a atualização.

Para resolver o conflito, atualize a configuração para que ela corresponda à outra fonte de informações ou exclua o objeto conflitante de uma das origens.

O comando nomos vet só verifica erros em um repositório por vez. Portanto, ele não detecta esse problema.

Um InvalidRepoSyncError informa que um RepoSync está configurado incorretamente. Os objetos do RepoSync precisam ser configurados corretamente para que o Config Sync sincronize a configuração dos repositórios de namespace.

Siga as instruções na mensagem para corrigir os erros de configuração.

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.

Especifique os valores de .inventory.identifier e .inventory.namespace no Kptfile.

Kptfiles foram encontrados no repositório raiz. Os Kptfiles só são compatíveis com repositórios com escopo de namespace.

Remova os Kptfiles do repositório raiz.

Não foi possível analisar o arquivo api-resources.txt no seu repositório.

Siga as instruções na mensagem de erro. Por exemplo, talvez seja necessário executar kubectl api-resources > api-resources.txt novamente.

No nomos 1.16.1 e versões anteriores, você também vê este erro: KNV1064: unable to find APIGROUP column. Esse erro é 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.

CustomResourceDefinition está incorreto.

Verifique o campo especificado pela mensagem de erro e se o valor está formatado corretamente.

Um objeto de configuração precisa declarar apenas a anotação do 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.

Remova uma das anotações do campo metadata.annotations.

O reconciliador não codifica os campos declarados em um formato compatível com aplicação do lado do servidor (link em inglês). Pode ser causado por um esquema desatualizado.

Verifique o campo especificado pela mensagem de erro e certifique-se de que ele corresponda ao esquema do tipo de recurso.

O processo de renderização encontrou um problema acionável pelo usuário.

Se o repositório Git contiver configurações do Kustomize, mas nenhum arquivo kustomization.yaml existir no diretório de sincronização do Git, adicione kustomization.yaml no diretório de sincronização para acionar o processo de renderização ou remova kustomization.yaml de todos os subdiretórios para pular a renderização.

Se o erro for causado por falhas kustomize build, talvez seja necessário atualizar 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 as configurações atualizadas forem renderizadas, envie uma nova confirmação para corrigir o erro KNV1068.

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

Um reconciliador reconciliou o próprio objeto RootSync ou RepoSync. Um objeto RootSync pode gerenciar outros objetos RootSync e RepoSync. Um objeto RepoSync pode gerenciar outros objetos RepoSync, mas não é possível gerenciar isso por conta própria.

Remova o objeto RootSync ou RepoSync da fonte de verdade de que o objeto é sincronizado.

Uma chamada de sistema no nível do SO que acessa um recurso do sistema de arquivos falha.

Esse erro provavelmente é causado por uma configuração YAML inválida ou pelo uso de caracteres especiais. Se você tiver uma configuração YAML inválida, verá uma mensagem de erro semelhante a esta: KNV2001: yaml: line 2: did not find expected node content path:.... Para resolver esse problema, verifique os arquivos YAML e resolva todos os problemas de configuração. Isso pode ser causado por qualquer configuração YAML no repositório.

Se o nome do arquivo ou caminho tiver caracteres especiais, talvez você veja uma mensagem de erro semelhante a 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 caracteres especiais dos nomes dos arquivos ou caminhos.

Uma solicitação que acessa o servidor da API falha.

Talvez você esteja enfrentando um erro de descoberta de API. Para saber mais, consulte os erros de descoberta de API.

Uma chamada genérica de sistema no nível do SO falha.

O Config Sync não pode ler a fonte da verdade.

Há vários problemas que podem causar esse erro. Para dicas sobre como resolver problemas comuns ao se conectar à fonte da verdade, consulte Resolver problemas de conexão com a fonte da verdade.

O Config Sync está competindo com outro controlador por um recurso. Esses conflitos consomem uma grande quantidade de recursos e podem prejudicar seu desempenho. Para ver dicas sobre como diagnosticar e resolver conflitos de controles, consulte Resolver problemas de lutas de controles.

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

Se o webhook de admissão do Config Sync estiver desativado, reverta a confirmação que exclui todos os recursos.
Se o webhook de admissão do Config Sync estiver ativado, talvez o namespace esteja travado ao ser encerrado. Para corrigir isso, execute as seguintes etapas:

  1. Desative o Config Sync e aguarde até que todos os recursos sejam limpos ou tenham um status estável. Por exemplo, é possível executar 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.

Se você quiser excluir o conjunto completo de recursos gerenciados, siga estas etapas:

  1. Remova todos, exceto 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.

Um recurso no servidor de API é modificado ou excluído enquanto o Config Sync também tenta modificá-lo.

Se esse tipo de erro só aparece na inicialização ou com pouca frequência, ignore-os.

Se esses erros não forem temporários (persistirem por vários minutos), talvez isso indique um problema sério, e o nomos status vai informar os brigas de controle.

Esse é um erro genérico que indica que o Config Sync não conseguiu sincronizar algumas configurações com o cluster.

Há vários problemas que podem causar esse erro. Para dicas sobre como resolver problemas comuns de sincronização, consulte Resolver problemas de sincronização.

Esse é um erro genérico que indica um problema com um recurso ou conjunto de recursos.

A mensagem de erro inclui os recursos específicos que causaram o erro. Consulte estes recursos.

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

Crie ou restaure o recurso ausente.

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, é preciso que haja apenas um recurso Repo em um cluster.

O APIResource adicional foi removido.

Um reconciliador de namespace não tem permissões suficientes para gerenciar recursos.

Verifique se o reconciliador tem permissões suficientes.

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

Remover o webhook modificado ilegalmente.

O processo de renderização encontrou um problema interno. Por exemplo, o Config Sync não consegue acessar o sistema de arquivos.

Esse erro pode indicar que o pod não está íntegro. É possível reiniciar os pods do reconciliador executando os seguintes comandos:


# 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

Esse erro representa um problema temporário que deve ser resolvido automaticamente mais tarde. Por exemplo, se o estado de renderização não corresponder à configuração de origem, esse erro poderá aparecer.

O erro será resolvido automaticamente.

Há um problema com a própria ferramenta de linha de comando nomos.

Envie um relatório do bug com o comando exato que você executou e a mensagem que recebeu.

Você encontrou um erro sem uma mensagem de erro documentada.

Ainda não escrevemos documentação específica para o erro encontrado.

Voltar ao início

Mensagens de erro sem um código KNV

Os erros relatados pelos reconciliadores do Config Sync têm o código de erro KNV, mas os erros informados de outros componentes não têm. Por exemplo, o erro de permissão negada vem do controlador de frota, que é uma camada sobre o Config Sync.

A tabela a seguir lista alguns erros comuns sem o prefixo KNV.

Mensagem de erro Ação recomendada

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

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

Não é possível criar exportadores

Quando um componente no Open Telemetry Collector não consegue acessar a conta de serviço padrão com o mesmo namespace, é possível que o pod otel-collector em config-management-monitoring esteja no status CrashLoopBackoff ou você veja uma mensagem de erro semelhante às listadas.

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

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

Se o erro persistir após a configuração do IAM, reinicie o pod otel-collector para que as alterações entrem em vigor.
Se você estiver usando uma solução de monitoramento personalizada, mas bifurcou o ConfigMap otel-collector-googlecloud padrão, verifique e realoque qualquer diferença.

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

Falha na verificação do certificado do servidor

Se o contêiner git-sync não clonar o repositório Git, essa mensagem de erro poderá ser exibida.

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 AC personalizada não está configurada corretamente, o que resulta em falha do contêiner git-sync para clonar o repositório Git.

Para resolver esse problema, primeiro você pode verificar se o campo spec.git.caCertSecretRef.name foi especificado no objeto RootSync ou RepoSync e também verificar se o objeto Secret existe.

Em seguida, se o campo tiver sido configurado e o objeto Secret existir, verifique se ele 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'

É possível solicitar que a equipe de administração de rede receba os certificados de CA para você.

Error message: "MESSAGE": "Unable to retrieve pull secret, the image pull may not succeed."

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 o GKE no VMware, a instalação ou o upgrade do Config Sync pode ficar travado. Você verá um erro semelhante a esta mensagem.

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

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

Permissão negada

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

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

Voltar ao início

A seguir