Referência de erros

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

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 prefixo N são específicas para nomos, V é específico 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 são do formato KNV1XXX. Os códigos de erros que só podem ser detectados no tempo de execução são da forma KNV2XXX.

Tabela de erros do KNV

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

O ID de InternalError foi alterado 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 hierárquica de repositório, 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 com 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.

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

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.

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 do Git, deixando a configuração registrada. 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 posterior 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 hierárquica de repositório, as configurações precisam declarar namespaces que correspondem ao diretório do 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 incompatíveis de 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/. Esse prefixo de chave de rótulo é reservado para uso pelo Config Sync.

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

Obsoleto no Config Sync 1.3.

 N/A

A configuração se refere 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.

Crie os seletores ausentes ou, se o seletor foi removido, remova as configurações que se referem a ele.

As configurações de ClusterSelector e NamespaceSelector 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, uma configuração para o ConfigManagement Operator precisa estar no diretório system/ do repositório. Essa configuração precisa incluir informações obrigatórias, como a versão semântica do repo.

Defina pelo menos uma configuração mínima para o Config Management 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 de namespace listadas na mensagem de erro. Para mais informações, consulte Estrutura do repositório hierárquico.

Ao usar uma estrutura hierárquica de repositório, 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 está definida para o recurso no cluster.

Crie 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 uma CustomResourceDefinition.

Ao usar um repositório hierárquico, as configurações desse tipo não podem ser declaradas no diretório system/.

Mova o recurso referenciado na mensagem de erro para fora do diretório system/. 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 suportada, atualize o campo spec.version. Se precisar fazer upgrade, siga as instruções nas notas da versão.

Os nomes de diretórios precisam ter menos de 64 caracteres, conter 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 abstratos principais.

Renomeie ou remova todas as configurações mencionadas 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 não haja mais de um recurso de namespace.

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 é 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 todas as configurações declaradas no diretório system/ são de um dos tipos permitidos. Se não estiver, mova para outro diretório.

É proibido declarar config-management-system, resource-group-system e config-management-monitoring ou recursos neles.

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

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

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

Se você estava sincronizando com um repositório hierárquico e precisou 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 o 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 for compatível, use o campo spec.resourceID para não receber restrições dessas 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 os configs problemáticos para que eles estejam em um diretório válido. 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 os configs problemáticos para que eles estejam em um diretório válido. 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 esse 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 ao 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.

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 pertencem a você, use kustomize patches para remover campos status especificados nos manifestos em massa.

Esse HierarchyConfig faz referência a um recurso com escopo de cluster. Não é permitido usar objetos com escopo no cluster 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 personalizado (CRD) 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 obsoletos.

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.

Os configs contêm um valor inválido para uma anotação.

Siga as instruções na mensagem de erro para resolver o problema.

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

Atualize o valor de metadata.namespace para que ele esteja em conformidade com as seguintes regras:

  • Tem um comprimento de 63 caracteres ou menos
  • 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 rótulos ilegais listados na mensagem de erro.

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

Verifique se todos os repositórios de namespace estão declarando corretamente os recursos no escopo do namespace. Por exemplo, o repositório do namespace 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, você vai receber um erro.

Além de verificar se os recursos com escopo de namespace estão declarados corretamente, confira 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 namespaces pode declarar no máximo um recurso Kptfile.

 Remova todos os recursos Kptfile, exceto um.

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.

Por exemplo, quando o mesmo objeto é gerenciado por um RootSync e um RepoSync, o RootSync vence. Se o RootSync for aplicado primeiro, o RepoSync vai informar um erro de status KNV1060. Se o RepoSync for aplicado primeiro, o RootSync vai substituir o objeto do RepoSync e o RepoSync vai informar um erro de status KNV1060 ao ver a atualização.

Resolva o conflito atualizando a configuração para corresponder à outra fonte de verdade ou excluindo o objeto conflitante de uma das fontes.

O comando nomos vet só verifica se há erros em um repositório por vez. Por isso, 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 de erro para corrigir os problemas 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.

Os Kptfiles foram encontrados no repositório raiz. Os arquivos Kptfiles são compatíveis apenas 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.

O CustomResourceDefinition está incorreto.

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

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

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. Pode ser causado por um esquema desatualizado.

Verifique o campo especificado pela mensagem de erro e confira se ele corresponde ao esquema do tipo de recurso.

O processo de renderização encontrou um problema que pode ser resolvido pelo usuário.

Se o repositório Git tiver configurações do Kustomize, mas não houver um arquivo kustomization.yaml 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 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.

Se ocorrer um erro kustomize build ao extrair bases remotas de repositórios públicos, defina 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 pode ser autogerenciado.

Remova o objeto RootSync ou RepoSync da fonte de verdade da qual o objeto se sincroniza.

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, vai aparecer 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.

Se o nome do arquivo ou caminho tiver caracteres especiais, você poderá receber 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 os caracteres especiais dos arquivos ou nomes dos caminhos.

Uma solicitação de acesso ao servidor da API Kubernetes falha.

As solicitações da API Kubernetes podem falhar por vários motivos. Estas são as causas mais comuns:

  • Erro de descoberta da API
  • Tempo limite de solicitação ou resposta do lado do cliente ou do servidor
  • Erro de identidade, autenticação ou autorização
  • Erro de conectividade de rede
  • O webhook negou a solicitação
  • Webhook não íntegro ou inacessível pelo servidor de API

O Config Sync tenta novamente após a maioria dos erros do servidor da API. Alguns podem ser problemas temporários que se resolvem sozinhos, mas a maioria exige intervenção do usuário para ser resolvida. Os erros do servidor da API raramente são causados pelo Config Sync em si, mas se você suspeitar que podem ser, envie um relatório de bug.

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

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

Vários problemas podem causar esse erro. Para resolver problemas de conexão com a fonte de verdade, consulte Resolver problemas de conexão com a fonte de verdade. Para saber mais sobre problemas conhecidos que causam erros KNV2004, consulte Problemas conhecidos.

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 dicas sobre como diagnosticar e resolver conflitos entre controladores, consulte Resolver conflitos entre controladores.

Para evitar a exclusão acidental, o Config Sync não permite remover 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, o namespace poderá ficar travado. Para corrigir isso, execute as seguintes etapas:

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

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

  1. Remova apenas um namespace ou recurso com escopo de cluster em uma primeira confirmação e permita que o Config Sync sincronize essas mudanças.
  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 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 controladores.

Esse é um erro genérico indicando que o Config Sync falhou ao 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 Solução de 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. Investigue esses recursos.

Um recurso específico é necessário para continuar, mas ele não foi encontrado. Por exemplo, o operador ConfigManagement tentou atualizar um recurso, mas ele foi excluído durante o cálculo da 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 somente um APIResource é permitido. Por exemplo, apenas um recurso Repo pode existir em um cluster.

Remova o APIResource adicional.

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.

Remova 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. Reinicie 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 será resolvido automaticamente depois. 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 o próprio Config Sync.

Envie um relatório de bug.

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 informados pelos reconciliadores do Config Sync têm o código de erro KNV, mas os erros informados por outros componentes não têm esse código. Por exemplo, o erro de permissão negada vem do controlador da frota, que é uma camada acima do 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 pode acessar a conta de serviço padrão no mesmo namespace, você pode notar que o pod otel-collector em config-management-monitoring está no status CrashLoopBackoff ou ver uma mensagem de erro semelhante às listadas.

Esse problema geralmente acontece quando a federação de identidade da carga de trabalho do GKE 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étrica à conta de serviço padrão.

Se o erro persistir, configure o pod otel-collector para que as mudanças 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.

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, helm-sync ou oci-sync não conseguir buscar artefatos, essa mensagem de erro poderá aparecer.

Essa mensagem indica que o servidor está configurado com certificados de uma autoridade de certificação (CA) personalizada. No entanto, a CA personalizada não está configurada corretamente, resultando na falha do contêiner ao buscar do servidor.

Para resolver esse problema, primeiro verifique se o campo caCertSecretRef foi configurado corretamente no objeto RootSync ou RepoSync e se o objeto Secret existe.

Em seguida, 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'

Você pode pedir à equipe de administração de rede para obter os certificados de CA.

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 Google Distributed Cloud, a instalação ou o upgrade do Config Sync podem ficar travados. Você vai encontrar 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 a este exemplo ao tentar configurar o Config Sync, talvez não tenha o papel de Administrador do GKE Hub.

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

Voltar ao início

A seguir