**Ajudar a melhorar esta página** Para contribuir com este guia de usuário, escolha o link **Editar esta página no GitHub**, disponível no painel direito de cada página. # Solução de problemas em funcionalidades do Argo CD **nota** As funcionalidades do EKS são totalmente gerenciadas e executadas de forma externa ao cluster. Você não tem acesso direto aos namespaces do controlador. Você pode configurar a entrega de log do controlador para ter visibilidade do comportamento dele. Consulte [Acessar logs do controlador de Funcionalidades do EKS](capabilities-controller-logs.md). A solução de problemas se concentra na integridade da funcionalidade, no status das aplicações e na configuração. ## Funcionalidade com o status ACTIVE, mas as aplicações não estão sendo sincronizadas Se a funcionalidade do Argo CD apresentar o status `ACTIVE`, mas as aplicações não estiverem sendo sincronizadas, verifique a integridade da funcionalidade e o status das aplicações. **Verifique a integridade da funcionalidade**: É possível visualizar problemas de integridade e de status da funcionalidade no console do EKS ou usando a AWS CLI. **Console da**: 1. Abra o console do Amazon EKS em https://console.aws.amazon.com/eks/home\#/clusters. 1. Selecione o nome do seu cluster. 1. Escolha a guia **Observabilidade**. 1. Escolha **Monitorar cluster**. 1. Escolha a guia **Funcionalidades** para visualizar a integridade e o status de todas as funcionalidades. ** AWS CLI**: ``` # View capability status and health aws eks describe-capability \ --region {{region-code}} \ --cluster-name {{my-cluster}} \ --capability-name {{my-argocd}} # Look for issues in the health section ``` **Causas comuns**: + **Repositório não configurado**: o repositório do Git não foi adicionado ao Argo CD + **Falha na autenticação**: a chave SSH, o token ou as credenciais do CodeCommit estão inválidos + **Aplicação não criada**: não existem recursos de Application no cluster + **Política de sincronização**: a sincronização manual é necessária (sincronização automática não habilitada) + **Permissões do IAM**: as permissões estão ausentes para o CodeCommit ou o Secrets Manager **Verifique o status da aplicação**: ``` # List applications kubectl get application -n argocd # View sync status kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.sync.status}' # View application health kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.health}' ``` **Verifique as condições da aplicação**: ``` # Describe application to see detailed status kubectl describe application {{my-app}} -n argocd # View application health kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.health}' ``` ## Aplicações travadas no estado “Progressing” Se uma aplicação estiver em `Progressing` mas nunca atingir `Healthy`, verifique o status dos recursos da aplicação e os eventos. **Verifique a integridade do recurso**: ``` # View application resources kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.resources}' # Check for unhealthy resources kubectl describe application {{my-app}} -n argocd | grep -A 10 "Health Status" ``` **Causas comuns**: + **Implantação não está pronta**: os pods não conseguem iniciar ou as sondagens de prontidão apresentam falhas + **Dependências entre recursos**: existem recursos esperando que outros recursos fiquem prontos + **Erros ao obter imagens**: as imagens de contêiner não estão acessíveis + **Recursos insuficientes**: o cluster não tem CPU ou memória suficiente para os pods **Verifique a configuração do cluster de destino** (para configurações com vários clusters): ``` # List registered clusters kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster # View cluster secret details kubectl get secret {{cluster-secret-name}} -n argocd -o yaml ``` ## Falhas na autenticação do repositório Se o Argo CD não conseguir acessar seus repositórios do Git, verifique a configuração de autenticação. **Para repositórios do CodeCommit**: Verifique se o perfil de funcionalidade do IAM tem as permissões necessárias para o CodeCommit: ``` # View IAM policies aws iam list-attached-role-policies --role-name {{my-argocd-capability-role}} aws iam list-role-policies --role-name {{my-argocd-capability-role}} # Get specific policy details aws iam get-role-policy --role-name {{my-argocd-capability-role}} --policy-name {{policy-name}} ``` É necessário que o perfil conte com a permissão `codecommit:GitPull` para os repositórios. **Para repositórios do Git privados**: Verifique se as credenciais do repositório estão configuradas corretamente: ``` # Check repository secret exists kubectl get secret -n argocd {{repo-secret-name}} -o yaml ``` Certifique-se de que o segredo contenha as credenciais de autenticação adequadas (por exemplo, chave SSH, token ou usuário/senha). **Para repositórios que usam o Secrets Manager**: ``` # Verify IAM Capability Role has Secrets Manager permissions aws iam list-attached-role-policies --role-name {{my-argocd-capability-role}} # Test secret retrieval aws secretsmanager get-secret-value --secret-id {{arn:aws:secretsmanager:region-code:111122223333:secret:my-secret}} ``` ## Problemas relacionados à implantação em vários clusters Se as aplicações não estiverem sendo implantadas em clusters remotos, verifique o registro do cluster e a configuração de acesso. **Verifique o registro do cluster**: ``` # List registered clusters kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster # Verify cluster secret format kubectl get secret {{CLUSTER_SECRET_NAME}} -n argocd -o yaml ``` Certifique-se de que o campo `server` contenha o ARN do cluster EKS, e não o URL da API do Kubernetes. **Verifique a entrada de acesso do cluster de destino**: No cluster de destino, confirme que o perfil da funcionalidade do IAM destinado ao Argo CD conta com uma entrada de acesso: ``` # List access entries (run on target cluster or use AWS CLI) aws eks list-access-entries --cluster-name {{target-cluster}} # Describe specific access entry aws eks describe-access-entry \ --cluster-name {{target-cluster}} \ --principal-arn {{arn:aws:iam::111122223333:role/my-argocd-capability-role}} ``` **Verifique as permissões do IAM para várias contas**: Para implantações entre contas, confirme que o perfil da funcionalidade do IAM destinado ao Argo CD conta com uma entrada de acesso no cluster de destino. A funcionalidade gerenciada emprega entradas de acesso do EKS para o acesso entre contas, e não a suposição do perfil do IAM. Para obter mais informações sobre configuração de vários clusters, consulte [Registro de clusters de destino](argocd-register-clusters.md). ## Aumento do tempo de sincronização da aplicação Se suas aplicações estiverem sincronizando, mas demorando mais do que o esperado, use as etapas de diagnóstico a seguir para identificar a causa. ### Verificar a hora da última sincronização Confirme o atraso analisando quando as aplicações foram sincronizadas pela última vez: ``` # View last sync time for all applications kubectl get application -n argocd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.operationState.finishedAt}{"\n"}{end}' # View last sync time for a specific application kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.operationState.finishedAt}' ``` ### Verificar as condições da aplicação Analise as condições da aplicação quanto a atrasos na fila de reconciliação: ``` # Check conditions on an application kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.conditions}' ``` ### Verificar a configuração de targetRevision As aplicações que usam `targetRevision: HEAD` invalidam o cache do manifesto em cada confirmação no repositório, o que reduz a velocidade de sincronização: ``` # List applications using HEAD as targetRevision kubectl get application -n argocd -o jsonpath='{range .items[?(@.spec.source.targetRevision=="HEAD")]}{.metadata.name}{"\n"}{end}' ``` ### Causas comuns + **Nenhuma configuração de webhook**: sem webhooks, o Argo CD sonda os repositórios no intervalo padrão de seis minutos. Isso atrasa a detecção de novas confirmações. + **targetRevision definido como HEAD**: cada confirmação no repositório invalida o cache do manifesto. O Argo CD então regenera os manifestos em cada reconciliação. + **Repositórios Git grandes ou complexos**: monorepos ou charts do Helm complexos causam lentidão na geração de manifestos devido ao volume de arquivos e modelos a serem processados. + **Muitos recursos do Kubernetes em uma única aplicação**: aplicações que gerenciam muitos recursos causam lentidão na sincronização do cache do cluster porque o Argo CD precisa rastrear o estado de cada recurso. ### Mitigações + **Configure webhooks do Git**: os webhooks notificam o Argo CD imediatamente quando as alterações são enviadas, ignorando o intervalo de sondagem padrão. Para conferir as etapas de configuração, consulte [Considerações sobre o Argo CD](argocd-considerations.md). + **Use nomes de ramificações específicos ou SHAs de confirmação**: defina `targetRevision` como um nome de ramificação ou SHA de confirmação em vez de `HEAD` para preservar o cache do manifesto entre as sincronizações. + **Divida grandes monorepos**: divida grandes repositórios em repositórios menores e focados para reduzir o tempo de geração do manifesto. + **Reduza os recursos por aplicação**: divida as aplicações com muitos recursos do Kubernetes em várias aplicações menores para reduzir o tempo de sincronização do cache do cluster. + **Habilite a entrega de logs do controlador**: os logs do controlador fornecem visibilidade do comportamento de reconciliação e do processamento de filas. Para conferir as etapas de configuração, consulte [Acessar logs do controlador de Funcionalidades do EKS](capabilities-controller-logs.md). ## Aplicações em sincronização contínua ou travadas sem sincronizar Se sua aplicação sincroniza e depois fica imediatamente como `OutOfSync`, ou se ela permanece travada em um loop de sincronização, a causa geralmente é uma desvio entre o que o Git define e o que existe no cluster. Comece com o diagnóstico da linha de base. ### Coletar informações de diagnóstico ``` # View current sync and health status argocd app get {{my-app}} # Show exact fields that differ between Git and live state argocd app diff {{my-app}} # Check whether the app has ever reached a stable state argocd app history {{my-app}} ``` O comando `argocd app diff` é o ponto de partida mais útil. Ele mostra exatamente quais campos fazem com que a aplicação pareça fora de sincronia. ### Certificados autogerenciados causam desvios Controladores como cert-manager, OPA Gatekeeper e KEDA geram certificados no runtime. Esses valores do runtime não estão no Git, então o Argo CD detecta desvios em cada reconciliação. Os sintomas são: + A aplicação é sincronizada e exibe imediatamente `OutOfSync` + O diff mostra alterações em um campo `caBundle` do webhook ou em um campo de `data` do Secret TLS Para resolver isso, adicione `ignoreDifferences` para os campos afetados e habilite `RespectIgnoreDifferences` em suas opções de sincronização: ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: ignoreDifferences: - group: admissionregistration.k8s.io kind: ValidatingWebhookConfiguration jsonPointers: - /webhooks/0/clientConfig/caBundle - group: "" kind: Secret jsonPointers: - /data/tls.crt - /data/tls.key syncPolicy: syncOptions: - RespectIgnoreDifferences=true ``` ### A autorrecuperação interrompe workloads de início lento Quando `selfHeal` está habilitado, o Argo CD sincroniza novamente a aplicação quando detecta um desvio. Se sua workload levar de 30 a 60 segundos para começar, a autorrecuperação será acionada antes que a workload fique `Healthy`. Se `prune` estiver habilitado, isso pode destruir recursos que foram iniciados apenas parcialmente. Para resolver esse problema, primeiro corrija o desvio subjacente (consulte o cenário do certificado). Se o desvio não for a causa, considere desabilitar a autorrecuperação das workloads que você gerencia exclusivamente por meio do Git: ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: syncPolicy: automated: selfHeal: false prune: false ``` **nota** O tempo de recuo de autorrecuperação é uma configuração do controlador em nível de instância. Se você precisar ajustar o tempo de autorrecuperação em vez de desabilitá-lo, abra um caso no AWS Support. ### Colisões de propriedade de recursos ou ApplicationSets Se duas aplicações ou ApplicationSets gerenciarem o mesmo recurso do Kubernetes, o Argo CD mostrará um `SharedResourceWarning`. O recurso nunca atinge um estado estável. Isso geralmente acontece quando um nome de recurso compartilhado não tem escopo definido por ambiente ou cluster. Para resolver esse problema: + Torne o recurso disputado exclusivo por proprietário. Adicione um sufixo de ambiente ou cluster ao nome do recurso. + Ao renomear um ApplicationSet, defina `preserveResourcesOnDeletion: true` primeiro para evitar a destruição dos recursos existentes: ``` apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: my-appset spec: syncPolicy: preserveResourcesOnDeletion: true ``` ### Exclusão travada devido a finalizadores de recursos Se uma aplicação estiver travada no estado `Terminating` ou mostrar "N objetos restantes para exclusão", o finalizador `resources-finalizer.argocd.argoproj.io` bloqueará a remoção até que todos os recursos gerenciados sejam excluídos. Um recurso gerenciado com seu próprio finalizador não processável bloqueia a exclusão indefinidamente. Para confirmar, liste os recursos que têm um carimbo de data e hora de exclusão, mas que não foram removidos: ``` kubectl get all -n {{my-namespace}} -o json | \ jq '.items[] | select(.metadata.deletionTimestamp != null) | {name: .metadata.name, kind: .kind, finalizers: .metadata.finalizers}' ``` Para resolver esse problema: + Certifique-se de que o controlador que possui o finalizador de bloqueio esteja íntegro e em execução. + Se o controlador proprietário estiver íntegro, mas o finalizador não estiver sendo processado, remova o finalizador de bloqueio do recurso travado: Usando a lista de finalizadores que o comando anterior imprimiu, defina a lista para os finalizadores que você deseja manter e omita apenas o de bloqueio. Substitua `finalizer-a` e `finalizer-b` por estes nomes: ``` kubectl patch {{resource-kind}} {{resource-name}} -n {{my-namespace}} \ --type merge -p '{"metadata":{"finalizers":["finalizer-a","finalizer-b"]}}' ``` Se o finalizador de bloqueio for o único no recurso, passe uma lista vazia: `--type merge -p '{"metadata":{"finalizers":[]}}'`. **Atenção** Defina a lista de finalizadores explicitamente em vez de remover uma entrada por posição. Um recurso pode transportar finalizadores de mais de um controlador. Os finalizadores não estão em uma ordem garantida. Remover a primeira entrada pode excluir o finalizador errado, o que deixa o de bloqueio no lugar e o recurso ainda preso. A remoção de um finalizador também ignora qualquer limpeza que o controlador proprietário teria realizado, o que pode deixar recursos da AWS para trás sem nenhum registro deles em seu cluster. Só faça isso depois de confirmar que o controlador proprietário não pode processar o finalizador. ### Uma sincronização com falha não é repetida automaticamente para a mesma revisão Após a falha de sincronização para uma revisão específica, o Argo CD não tenta novamente essa mesma revisão de forma automática. Isso geralmente acontece devido a um defeito de manifesto, como uma `ComparisonError` de uma chave de variável de ambiente duplicada. Confirme verificando o status da aplicação: ``` argocd app get {{my-app}} # Look for: Operation: Sync Phase: Failed Revision: ``` Para resolver esse problema, corrija o defeito do manifesto no seu repositório Git e envie uma nova confirmação. Como alternativa, acione uma sincronização manual: ``` argocd app sync {{my-app}} ``` ### Excesso de confirmações em um monorepo aciona uma regeneração ampla Se muitas aplicações rastrearem o `HEAD` no mesmo repositório, qualquer confirmação nesse repositório alterará o `HEAD` para todas as aplicações. Isso aciona a regeneração do manifesto para cada aplicação, mesmo aquelas cujos arquivos não foram alterados. Para obter mais informações sobre `targetRevision` e armazenamento em cache, consulte a seção “Aumento do tempo de sincronização da aplicação” nesta página. Para definir o escopo da regeneração para somente aos arquivos que cada aplicação usa, adicione a anotação `manifest-generate-paths`: ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app annotations: argocd.argoproj.io/manifest-generate-paths: /apps/my-app spec: source: repoURL: https://github.com/my-org/my-monorepo.git targetRevision: HEAD path: apps/my-app ``` Com essa anotação, o Argo CD só regenera os manifestos quando os arquivos no caminho especificado são alterados. Para bibliotecas compartilhadas usadas entre aplicações, você pode especificar vários caminhos separados por ponto e vírgula (`;`). Sempre que possível, fixe `targetRevision` em um nome de ramificação ou tag em vez de `HEAD`. ### Webhooks de atribuição de valores padrão e mutação do Kubernetes causam diffs fantasmas Se sua aplicação mostrar `OutOfSync` imediatamente após uma sincronização, verifique o diff nos campos que você nunca definiu (como `terminationGracePeriodSeconds`, `dnsPolicy` ou `/spec/replicas`). O servidor da API do Kubernetes ou um webhook de mutação adicionou esses campos no momento da aplicação. Para resolver esse problema em campos gerenciados por outro controlador (como `/spec/replicas` quando um HPA gerencia a escalabilidade), adicione `ignoreDifferences`: ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: ignoreDifferences: - group: apps kind: Deployment jsonPointers: - /spec/replicas syncPolicy: syncOptions: - RespectIgnoreDifferences=true ``` Para campos adicionados por webhooks de atribuição de valores padrão ou mutação do Kubernetes, você pode habilitar o diff do lado do servidor na aplicação: ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app annotations: argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true ``` O diff do lado do servidor executa uma aplicação dry-run por recurso, o que aumenta a carga no servidor da API do Kubernetes. Teste isso em um pequeno número de aplicações antes de habilitá-lo amplamente. ### Recursos gerenciados por controlador de alta rotatividade Alguns controladores geram um grande número de recursos de curta duração ou atualizados com frequência. Os exemplos incluem objetos de nó do Karpenter, objetos de identidade e endpoint do Cilium e relatórios de políticas do Kyverno. Se esses recursos gerarem um grande volume de eventos de monitoramento e causarem fragmentação de sincronização, você poderá reduzir a carga excluindo esses tipos de recursos ou filtrando os eventos de observação. Essas alterações exigem a configuração do controlador no nível da instância. Na capacidade gerenciada, abra um caso no AWS Support para solicitar exclusões de recursos ou filtragem de eventos de monitoramento para esses tipos de recursos. ### Práticas recomendadas + **Use o diff de aplicação primeiro**: execute `argocd app diff` como a primeira etapa de diagnóstico para qualquer problema recorrente de sincronização. Isso mostra a causa exata do desvio. + **Dê preferência a um ignoreDifferences restrito**: direciona a campos específicos em determinados tipos de recursos. Evite regras de ignorar amplas que possam mascarar o desvio real da configuração. + **Combine o ignoreDifferences com o RespectIgnoreDifferences**: sempre adicione a opção de sincronização `RespectIgnoreDifferences=true`. Sem isso, as sincronizações ainda sobrescrevem os campos ignorados. + **Mantenha os nomes dos recursos exclusivos**: defina o escopo dos nomes dos recursos por ambiente e cluster para evitar colisões de propriedade entre aplicações ou ApplicationSets. + **Tenha cuidado ao usar o prune e o selfHeal**: não habilite ambos em workloads que demoram muito para serem iniciadas. A autorreparação pode destruir recursos antes que eles se tornem íntegros. + **Fixe o targetRevision e delimite o escopo dos caminhos dos manifestos**: para aplicações em grandes repositórios compartilhados, use uma ramificação ou tag em vez do `HEAD` e adicione a anotação `manifest-generate-paths`. ### Quando entrar em contato com o AWS Support Abra um caso no AWS Support nas seguintes situações: + O ajuste do controlador no nível da instância parece necessário (contagem de processadores, tempo de autorreparação ou exclusões de recursos). + A capacidade do repo-server ou do controlador parece insuficiente para a sua quantidade de aplicações. + A configuração, o desvio, a propriedade ou os finalizadores da workload não explicam o comportamento. Inclua a saída de `argocd app get` e `argocd app diff` para as aplicações afetadas em seu caso de suporte. ## Próximas etapas + [Considerações sobre o Argo CD](argocd-considerations.md): acesse considerações e práticas recomendadas do Argo CD + [Como trabalhar com o Argo CD](working-with-argocd.md): crie e gerencie Applications do Argo CD + [Registro de clusters de destino](argocd-register-clusters.md): configure implantações em vários clusters + [Solução de problemas das funcionalidades do EKS](capabilities-troubleshooting.md): acesse orientações gerais para solução de problemas de funcionalidades