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

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

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:

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:

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.

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

Mitigações

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:

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

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:

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:

kubectl patch resource-kind
            resource-name -n my-namespace \
  --type json -p '[{"op": "remove", "path": "/metadata/finalizers/0"}]'

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

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

Quando entrar em contato com o AWS Support

Abra um caso no AWS Support nas seguintes situações:

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