Como resolver problemas do Config Sync

Nesta página, você aprenderá a solucionar problemas de instalação do Config Sync.

Nós nos esforçamos para que a experiência do Config Sync funcione sempre para você, mas há situações em que você pode precisar da solução de problemas na sua configuração. Este guia orienta você por alguns mecanismos comuns que podem ajudar a resolver problemas.

Práticas recomendadas gerais

nomos status é seu amigo

Investimos muita energia para garantir que você tenha o maior número de dados disponível na palma da sua mão com o comando nomos status. O nomos status fornece dados agregados e erros para ajudar você a entender o que está acontecendo com a instalação do Config Sync. As informações a seguir estão disponíveis com nomos status:

• Status da instalação por cluster
• Erros de sincronização (na leitura do Git e na reconciliação das alterações)

Recursos de KRM do kubectl get para uso avançado

O Config Sync é composto de vários recursos personalizados que podem ser consultados individualmente usando kubectl para entender exatamente o status de cada um dos objetos.

Veja a seguir algumas informações importantes sobre os recursos do Kubernetes que o Config Sync gerencia:

• config-management-system é o namespace que usamos para executar todos os principais componentes do sistema do Config Sync
• configmanagement.gke.io/v1 e configsync.gke.io são os prefixos de versão que usamos para todos os recursos personalizados.

Veja uma lista completa dos recursos personalizados executando o seguinte comando:

kubectl api-resources | grep -E "configmanagement.gke.io|configsync.gke.io"

Recursos personalizados individuais podem ser consumidos ao executar: kubectl get RESOURCE -o yaml.

Por exemplo, na resposta do próximo comando, é possível verificar os objetos RootSync:

kubectl get rootsync -n config-management-system -o yaml

Para ver mais informações, consulte Como explorar os objetos RootSync e RepoSync.

Como usar registros de auditoria

Os registros de auditoria podem ser uma ferramenta útil para depuração.

Se você instalou o Config Sync usando o Console do Cloud ou a ferramenta de linha de comando gcloud, conclua as etapas a seguir para usar os registros de auditoria para investigar o Config Sync.

Console

1. Ative os registros de auditoria das APIs Connect/Hub do GKE.

   1. No Console do Cloud, acesse a página Registros de auditoria do IAM.

      Acessar a página "Registros de auditoria"

   2. Na tabela, marque a caixa de seleção APIs Connect/Hub do GKE.

   3. Marque as seguintes caixas de seleção:

      • Leitura de administradores
      • Leitura de dados
      • Gravação de dados

   4. Clique em Salvar.

2. Acesse a página Explorador de registros.

   Acessar a página Explorador de registros

3. Na caixa de texto Criador de consultas, adicione os seguintes filtros:

   resource.type="audited_resource" resource.labels.service="gkehub.googleapis.com"
   

4. Clique em Run.

5. Na seção Resultados da consulta, selecione entradas para saber mais sobre os eventos.

CPU insuficiente

A saída de kubectl get events pode incluir um evento com o tipo FailedScheduling. O evento será parecido com o seguinte exemplo:

LAST SEEN   TYPE      REASON              OBJECT                                       MESSAGE
9s          Warning   FailedScheduling    pod/config-management-operator-74594dc8f6    0/1 nodes are available: 1 Insufficient cpu.

Para corrigir esse erro, escolha uma das seguintes opções:

• adicionar um nó a um pool de nós do GKE atual.
• criar um pool com nós maiores.

Objeto ConfigManagement válido, mas incorreto

Se a instalação falhar por um problema com o objeto ConfigManagement que não seja causado por um erro de sintaxe YAML ou JSON, o objeto ConfigManagement talvez esteja instanciado no cluster, mas não funcione corretamente. Nesta situação, use o comando nomos status para verificar se há erros no objeto ConfigManagement.

Uma instalação válida sem problemas tem o status PENDING ou SYNCED.

Uma instalação inválida tem o status NOT CONFIGURED e lista um dos seguintes erros:

• missing git-creds Secret
• missing required syncRepo field
• git-creds Secret is missing the key specified by secretType

Para resolver o problema, corrija o erro de configuração. Dependendo do tipo de erro, talvez seja necessário reaplicar o manifesto ConfigManagement ao cluster.

Se o problema for que você esqueceu de criar o Secret git-creds, o Config Sync detectará o Secret assim que ele for criado e você não precisará reaplicar a configuração.

Os campos de ResourceGroup continuam mudando

Para um repositório Git sincronizado com o cluster, o status de reconciliação de todos os recursos é agregado a um recurso denominado ResourceGroup. Para cada objeto RootSync ou RepoSync, um ResourceGroup é gerado para capturar o conjunto de recursos aplicados ao cluster e agregar os status deles.

Finalmente, seu ResourceGroup pode entrar em um loop que continua atualizando o spec do ResourceGroup. Se isso acontecer, você poderá notar os seguintes problemas:

• O metadata.generation de um ResourceGroup continua aumentando em um curto período.
• O ResourceGroup spec está sempre mudando.
• O ResourceGroup spec não inclui o status.resourceStatuses dos recursos que estão sendo sincronizados com o cluster.

Se você observar esses problemas, isso significa que alguns dos recursos nos seus repositórios Git não foram aplicados ao cluster. A causa desses problemas é a falta de permissões necessárias para aplicar esses recursos.

Você pode verificar se as permissões estão ausentes recebendo o status do recurso RepoSync:

kubectl get reposync repo-sync -n NAMESPACE -o yaml

Substitua NAMESPACE pelo namespace em que você criou seu repositório de namespace.

Você também pode usar o nomos status.

Se as mensagens a seguir aparecerem no status, significa que o reconciliação em NAMESPACE não tem a permissão necessária para aplicar o recurso:

errors:
  - code: "2009"
    errorMessage: |-
      KNV2009: deployments.apps "nginx-deployment" is forbidden: User "system:serviceaccount:config-management-system:ns-reconciler-     default" cannot get resource "deployments" in API group "apps" in the namespace "default"

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

Para corrigir esse problema, é preciso declarar uma configuração RoleBinding que concede à conta de serviço ns-reconciler-NAMESPACE permissão para gerenciar o recurso com falha nesse namespace. Detalhes sobre como adicionar um RoleBinding estão incluídos na seção Como configurar a sincronização de repositórios de namespace.

Grande número de recursos no repositório Git

Quando o repositório Git sincronizado pelos objetos RepoSync ou RootSync contém configuração para mais de alguns milhares de recursos, ele pode fazer com que o ResourceGroup exceda o limite de tamanho de objeto etcd. Quando isso acontece, não é possível visualizar o status agregado dos recursos no seu repositório Git. Embora não seja possível visualizar o status agregado, seu repositório ainda está sincronizado. Se não houver erros nos objetos RepoSync ou RootSync, isso significa que o repositório Git foi sincronizado com o cluster.

Para verificar se o recurso ResourceGroup excede o limite de tamanho de objeto etcd, é necessário verificar o status do recurso ResourceGroup e o registro do controlador ResourceGroup:

1. Verifique o status de "GroupGroup" com o seguinte comando:

   • Para verificar o status do RootSync, execute o comando a seguir:

    kubectl get resourcegroup.kpt.dev root-sync -n config-management-system
   

   • Para verificar o status do RootSync, execute o comando a seguir:

   # For the RepoSync:
   kubectl get resourcegroup.kpt.dev repo-sync -n NAMESPACE
   

   O resultado será semelhante a:

   NAME        RECONCILING   STALLED   AGE
   root-sync   True          False     35m
   

   Se o valor da coluna RECONCILING for True, significa que o recurso ResourceGroup ainda está fazendo a reconciliação.

2. Verifique os registros do controlador ResourceGroup com o seguinte comando:

   kubectl logs deployment/resource-group-controller-manager -c manager -n resource-group-system
   

   Se você vir o seguinte erro na saída, o recurso ResourceGroup é muito grande e excede o limite de tamanho de objeto etcd:

   "error":"etcdserver: request is too large"
   

Para evitar que o ResourceGroup seja muito grande, reduza o número de recursos no seu repositório Git. Por exemplo, divida o repositório e use um objeto RootSync com vários objetos RepoSync em vez de usar apenas um objeto RootSync para sincronizar todos os recursos.

Fora de sincronia do repositório Git

Se novas confirmações forem enviadas para seu repositório do Git, mas o status do Config Sync do cluster ainda for Synced para uma confirmação antiga por muito tempo (mais que spec.git.period), você precisará verificar os registros do contêiner git-sync:

# check git-sync logs for a root reconciler
kubectl logs -n config-management-system deployment/root-reconciler -c git-sync

# check git-sync logs for a namespace reconciler
kubectl logs -n config-management-system deployment/ns-reconciler-NAMESPACE -c git-sync

É provável que git-sync não sincronize do repositório do Git, mas o reconciliador continuará a sincronização da confirmação realizada anteriormente. O exemplo de saída a seguir indica que você está com um problema de git-sync:

"msg"="unexpected error syncing repo, will retry" "error"="Run(git fetch -f --tags --depth 1 origin develop): exit status 128: { stdout: "", stderr: "fatal: couldn't find remote ref develop\n" }"

Esse é um problema conhecido do Config Sync versão 1.8.1 e versões anteriores. Para corrigi-lo, é necessário seguir a mensagem de erro no registro. Talvez seja necessário atualizar o repositório Git ou os campos spec.git no objeto RootSync ou RepoSync.

admission-webhook.configsync.gke.io nega a solicitação para atualizar/excluir um recurso que foi gerenciado por um RootSync/RepoSync já excluído

A exclusão de um objeto RootSync ou RepoSync não limpa as anotações e rótulos do Config Sync, e o webhook de admissão do Config Sync negará solicitações tentando modificar ou excluir esses recursos se o Config Sync ainda estiver ativado no cluster.

Se você quiser manter esses recursos gerenciados, primeiro é possível remover o gerenciamento desses recursos definindo a anotação configmanagement.gke.io/managed como disabled em cada recurso gerenciado declarado no repositório Git. Isso removeria as anotações e os rótulos do Config Sync dos recursos gerenciados, mas não excluiria esses recursos. Quando a sincronização for concluída, é possível remover o objeto RootSync ou RepoSync.

Se você quiser excluir esses recursos gerenciados, primeiro exclua os recursos gerenciados modificando o objeto RootSync ou RepoSync para sincronizar de um diretório Git vazio. Quando a sincronização for concluída, é possível remover o objeto RootSync ou RepoSync.

Se o objeto RootSync ou RepoSync foi excluído antes de remover o gerenciamento ou de excluir os recursos gerenciados, é possível adicionar o objeto RootSync ou RepoSync novamente, remover o gerenciamento ou excluir recursos gerenciados e, em seguida, excluir o objeto RootSync ou RepoSync novamente.

Como solucionar mensagens de erro

Erro: permissão recusada

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, consulte Como preparar permissões.

Erro: 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.

Erro: tempo limite de E/S da solicitação de webhook de admissão

Se você receber o seguinte erro quando o regulador tentar 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.1.1.186:8676: i/o timeout

Isso pode ocorrer devido ao bloqueio da porta 8676 do webhook de admissão pelo firewall para a rede do plano de controle. 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.

Erro: conexão do webhook de admissão recusada

Se você receber o seguinte erro quando o regulador tentar 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

Erro: não é possível montar o Git Secret

Se você receber o seguinte erro quando o contêiner git-sync tentar sincronizar um repo com um Secret:

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

Isso significa que o secret Git não é montado com êxito no contêiner git-sync. Isso 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

Os contêineres reconciler e/ou git-sync são OOMKilled

No Anthos Config Management versão 1.8.2 e posterior, ao configurar a sincronização de vários repositórios usando kubectl, é possível modificar os limites da CPU e/ou da memória de uma raiz repositório de namespace. Para substituir esses valores, use o campo spec.override.resources de um objeto RootSync ou RepoSync.

O exemplo a seguir mostra como substituir os limites de CPU e memória do contêiner reconciler e o limite de memória do contêiner git-sync de um reconciliador raiz. Ele só pode substituir os contêineres git-sync e reconciler. A substituição parcial é permitida: quando um valor de modificação para um limite de recurso não é fornecido, o limite de recurso padrão é usado.

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync
  namespace: config-management-system
spec:
  sourceFormat: "unstructured"
  override:
    resources:
    - containerName: "reconciler"
      cpuLimit: "888m"
      memoryLimit: "444Mi"
    - containerName: "git-sync"
      memoryLimit: "333Mi"
  git:
     ...

Execute o seguinte comando para verificar se os novos limites de recursos entram em vigor:

kubectl get deployment.apps/root-reconciler -n config-management-system -o yaml

É possível substituir os limites de recursos de um reconciliador de namespace da mesma forma.

KNV2004: não é possível sincronizar o erro de repositório no contêiner do git-sync (git fetch falhou 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, talvez não seja possível encontrar a confirmação no clone superficial e exigir um aumento no número de confirmações do Git para buscar.

No Anthos Config Management versão 1.8.2 e posterior, é possível definir o número de confirmações do Git para busca configurando 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 faria um clone completo se esse campo fosse 0, e um clone superficial se este campo fosse maior que 0.
• Não é permitido definir esse campo como um valor negativo.

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.

Erro: falha no upgrade das implantações de reconciliação

Ao fazer upgrade do Config Sync das versões entre 1.6.2 e 1.7.0 para as versões entre 1.7.x e 1.8.x, a versão da imagem da implantação do reconciliação pode não ser atualizada. Isso é causado por alterações no campo .spec.selector.labels do modelo de implantação. Um novo matchLabel foi adicionado na versão 1.6.2 e removido na versão 1.7.0. O seletor de rótulos é imutável, portanto, o gerenciador de reconciliação não consegue fazer upgrade dos reconciliadores.

É possível verificar o erro verificando os registros do gerenciador de reconciliação:

kubectl logs -n config-management-system deployment/reconciler-manager -c reconciler-manager

Veja um exemplo de erro no registro:

Deployment.apps "root-reconciler" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app":"reconciler"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable

Para resolver o problema, exclua os reconciliadores atuais:

kubectl delete deployment -n config-management-system -l app=reconciler

Erro: um namespace fica preso na fase Terminating

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

Isso 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.

A solução é excluir o webhook de admissão do Config Sync:

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

O Config Management Operator recriará 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 o erro novamente, verifique se o repositório de namespace foi removido (aqui as instruções sobre como remover um repositório de namespace) antes de remover o namespace.

Erro: o campo webhooks não foi encontrado na configuração do webhook de validação

Se você encontrar os seguintes erros nos registros de webhook de admissão do Config Sync ao executar kubectl logs -n config-management-system -l app=admission-webhook:

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"

Isso significa que o root-reconciler não sincroniza nenhum recurso com o cluster. Pode ser que a root-reconciler ainda não esteja pronta ou não haja 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 dos recursos.