Solucionar problemas do Config Sync

Nesta página, mostramos como resolver problemas com o 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 apresenta orientações sobre alguns mecanismos comuns que podem ajudar a resolver problemas.

Práticas recomendadas gerais

Ver o status do Config Sync

O comando nomos status exibe 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)

Para usar nomos status, instale o comando nomos.

Também é possível usar o comando gcloud alpha anthos config sync repo para receber o status do Config Sync por repositório. Para saber mais, consulte Visualizar o status do Config Sync em vários clusters.

Usar o kubectl para examinar recursos

O Config Sync é composto de vários recursos personalizados que podem ser consultados usando comandos kubectl. Esses comandos ajudam você a entender o status de cada um dos objetos do Config Sync.

Você precisa conhecer as seguintes informações 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, a saída do comando a seguir permite verificar o status de um objeto RootSync:

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

Também é possível usar o comando gcloud alpha anthos config sync resources para receber os recursos gerenciados do Config Sync. Para saber mais, consulte Ver os recursos gerenciados do Config Sync.

Ver os objetos RootSync e RepoSync

Ao instalar o Config Sync usando kubectl, você cria um objeto RootSync que contém detalhes sobre a configuração do seu repositório raiz. Ao instalar o Config Sync usando o Console do Google Cloud ou a Google Cloud CLI, o Config Sync cria automaticamente um objeto RootSync para você. Ao configurar a sincronização de vários repositórios, você cria objetos RepoSync que contêm informações de configuração sobre os repositórios de namespace.

A análise desses objetos pode revelar informações valiosas sobre o estado do Config Sync. Para saber mais, consulte Monitorar objetos RootSync e RepoSync.

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 Google Cloud CLI, 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.

Evento com FailedScheduling

A saída de kubectl get events pode incluir um evento com o tipo FailedScheduling. O evento é semelhante ao seguinte exemplo:

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

Esse evento pode acontecer porque os pods não podem ser programados nos nós, o que geralmente significa que não há CPU ou memória suficiente nos nós. 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

Observação: esta seção só se aplicará se você tiver criado um objeto ConfigManagement. Se você criar um arquivo apply-spec.yaml incorreto e tentar aplicá-lo, o comando falhará instantaneamente com uma mensagem de erro explicando quais campos no arquivo apply-spec.yaml estão incorretas.

Se você instalar o Config Sync usando comandos kubectl e a instalação falhar devido a um problema com o objeto ConfigManagement que não seja devido a um erro de sintaxe YAML ou JSON, o objeto poderá ser instanciado em cluster, mas talvez não funcione corretamente. Nessa situação, use o comando nomos status para verificar se há erros no objeto.

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 cada 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, significa que alguns dos recursos nos repositórios do 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. Os detalhes sobre como adicionar um RoleBinding estão incluídos em Configurar a sincronização de vários repositórios.

Grande número de recursos no repositório Git

Quando o repositório Git é sincronizado com um cluster por um objeto RepoSync ou RootSync contém configuração para mais de alguns milhares de recursos, ele pode fazer com que ResourceGroup exceda o limite de tamanho do 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 você vir o seguinte erro do objeto RootSync, RepoSync ou dos registros de reconciliação, isso significa que o recurso ResourceGroup excede o limite de tamanho do objeto etcd.

KNV2009: etcdserver: request is too large

A solução recomendada é dividir o repositório Git em vários repositórios seguindo as instruções. Se não for possível dividir o repositório Git, no Config Sync v1.11.0 e versões posteriores, é possível atenuá-lo 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.

Se você não vir nenhum erro do objeto RootSync ou RepoSync, isso significa que seu repositório Git está sincronizado com o cluster. Para verificar se o recurso ResourceGroup excede o limite de tamanho do objeto etcd, verifique o status do recurso ResourceGroup e o registro do controlador ResourceGroup:

1. Verifique o status do ResourceGroup:

   • 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:

   kubectl get resourcegroup.kpt.dev repo-sync -n NAMESPACE
   

   A resposta 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:

   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. Siga as instruções para dividir um repositório raiz em vários repositórios raiz.

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.

O webhook nega a solicitação de atualização/exclusão de um recurso gerenciado por um RootSync/RepoSync 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 nega 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.

Resolver problemas de 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, verifique se concedeu os papéis do IAM necessários.

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

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

Se você receber o seguinte erro quando o reconciliador tentar aplicar uma configuração ao cluster, o webhook de admissão ainda não estará pronto:

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

É um erro temporário que 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 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

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

No Anthos Config Management versão 1.8.2 e posterior, é possível modificar os limites de CPU e/ou memória de um repositório raiz ou de namespace. No Anthos Config Management versão 1.11.0 e posterior, também é possível modificar as solicitações de CPU e/ou memória de um repositório raiz ou de namespace. Para substituir esses valores, use o campo spec.override.resources de um objeto RootSync ou RepoSync.

O exemplo a seguir mostra como modificar os limites de CPU e memória do contêiner reconciler e a solicitação de CPU 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 uma solicitação ou limite de recurso não é fornecido, o valor do recurso padrão é usado para a solicitação ou o limite.

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync
  namespace: config-management-system
spec:
  sourceFormat: "unstructured"
  override:
    resources:
    - containerName: "reconciler"
      cpuLimit: "800m"
      memoryLimit: "500Mi"
    - containerName: "git-sync"
      cpuRequest: "100m"
      memoryLimit: "400Mi"
  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, 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.

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. Esse erro é 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

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.

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

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 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 de recursos.

Erro: não foi possível criar o exportador do Stackdriver/GoogleCloud

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 está no status CrashLoopBackoff ou Você poderá ver uma mensagem de erro semelhante a esta:

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.

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.