Ayude a mejorar esta página

Para contribuir a esta guía del usuario, elija el enlace Edit this page on GitHub que se encuentra en el panel derecho de cada página.

Solución de problemas con capacidades de Argo CD

La capacidad está ACTIVA, pero las aplicaciones no se sincronizan

Si la capacidad de Argo CD muestra el estado ACTIVE, pero las aplicaciones no se están sincronizando, compruebe el estado de la capacidad y de la aplicación.

Compruebe el estado de la capacidad:

Puede ver los problemas de estado de la capacidad en la consola de EKS o mediante la AWS CLI.

Consola:

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

Compruebe el estado de la aplicación:

# 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}'

Compruebe las condiciones de la aplicación:

# 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}'

Aplicaciones bloqueadas en el estado “En curso”

Si una aplicación muestra Progressing, pero nunca aparece Healthy, compruebe el estado de los recursos y los eventos de la aplicación.

Compruebe el estado de los recursos:

# 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 habituales:

Verifique la configuración del clúster de destino (para configuraciones de varios clústeres):

# 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

Errores de autenticación de repositorios

Si Argo CD no puede acceder a los repositorios de Git, compruebe la configuración de autenticación.

Para repositorios de CodeCommit:

Compruebe que el rol de capacidad de IAM tenga permisos de 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
      

El rol necesita el permiso codecommit:GitPull para los repositorios.

Para repositorios de Git privados:

Compruebe que las credenciales del repositorio estén configuradas correctamente:

# Check repository secret exists
kubectl get secret -n argocd repo-secret-name -o yaml

Asegúrese de que el secreto contenga las credenciales de autenticación correctas (clave SSH, token o nombre de usuario y contraseña).

Para los repositorios que utilizan 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 en implementaciones de varios clústeres

Si las aplicaciones no se implementan en clústeres remotos, compruebe la configuración de acceso y el registro del clúster.

Compruebe el registro del clúster:

# 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

Asegúrese de que el campo server contenga el ARN del clúster de EKS, no la URL de la API de Kubernetes.

Compruebe la entrada de acceso del clúster de destino:

En el clúster de destino, compruebe que el rol de capacidad de Argo CD tenga una entrada de acceso:

# 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
      

Compruebe los permisos de IAM para varias cuentas:

Para las implementaciones entre cuentas, compruebe que el rol de capacidad de Argo CD tenga una entrada de acceso en el clúster de destino. La capacidad administrada utiliza las entradas de acceso de EKS para el acceso entre cuentas, no para asumir el rol de IAM.

Para obtener más información sobre la configuración de varios clústeres, consulte Registro de clústeres de destino.

Aumento del tiempo de sincronización de las aplicaciones

Si las aplicaciones se sincronizan, pero tardan más de lo esperado, siga estos pasos de diagnóstico para identificar la causa.

Comprobación de la última sincronización

Para confirmar el retraso, revise cuándo se sincronizaron las aplicaciones por ú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}'

Comprobación de las condiciones de la aplicación

Revise las condiciones de las aplicaciones sobre los retrasos en las colas de conciliación:

# Check conditions on an application
kubectl get application my-app -n argocd -o jsonpath='{.status.conditions}'

Comprobación de la configuración de targetRevision

Las aplicaciones que utilizan targetRevision: HEAD invalidan la caché de manifiestos en cada confirmación al repositorio, lo que ralentiza los tiempos de sincronización:

# List applications using HEAD as targetRevision
kubectl get application -n argocd -o jsonpath='{range .items[?(@.spec.source.targetRevision=="HEAD")]}{.metadata.name}{"\n"}{end}'

Causas habituales

Mitigaciones

Aplicaciones que se sincronizan repetidamente o se quedan sin sincronizar

Si la aplicación se sincroniza y luego pasa inmediatamente a OutOfSync, o si se atasca en un bucle de sincronización, la causa suele ser una desviación entre lo que Git define y lo que existe en el clúster. Comience con un diagnóstico de línea de base.

Recopilación de información 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
         

El comando argocd app diff es el punto de partida más útil. Muestra exactamente qué campos hacen que la aplicación no parezca sincronizada.

Certificados autoadministrados que provocan desviaciones

Los controladores como cert-manager, OPA Gatekeeper y KEDA generan certificados en tiempo de ejecución. Estos valores en tiempo de ejecución no están en Git, por lo que Argo CD detecta desviaciones en cada conciliación.

Los síntomas son los siguientes:

Para resolver este problema, agregue ignoreDifferences para los campos afectados y habilite RespectIgnoreDifferences en las opciones de sincronización:

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

La función de recuperación automática interrumpe cargas de trabajo que se inician lentamente

Cuando la función selfHeal está habilitada, Argo CD vuelve a sincronizar la aplicación cuando detecta una desviación. Si la carga de trabajo tarda entre 30 y 60 segundos en iniciarse, la reparación automática se activa antes de que la carga de trabajo pase a Healthy. Si se ha habilitado prune, es posible que se eliminen los recursos que se hayan iniciado parcialmente.

Para resolver este problema, corrija antes la desviación subyacente (consulte la situación para certificados). Si la causa no es la desviación, plantéese deshabilitar la reparación automática para las cargas de trabajo que administra exclusivamente a través de Git:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  syncPolicy:
    automated:
      selfHeal: false
      prune: false

Colisiones de propiedad de recursos o ApplicationSet

Si dos aplicaciones o ApplicationSets administran el mismo recurso de Kubernetes, Argo CD muestra SharedResourceWarning. El recurso nunca alcanza un estado estable. Esto suele ocurrir cuando el nombre de un recurso compartido no está delimitado por entorno o clúster.

Para resolverlo:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-appset
spec:
  syncPolicy:
    preserveResourcesOnDeletion: true

Eliminación de los finalizadores de recursos atascada

Si una aplicación se queda atascada en el estado Terminating o muestra “Quedan N objetos por eliminar”, el finalizador resources-finalizer.argocd.argoproj.io bloquea la eliminación hasta que se eliminen todos los recursos administrados. Un recurso administrado con su propio finalizador no procesable bloquea la eliminación indefinidamente.

Para confirmarlo, enumere los recursos que tienen una marca de tiempo de eliminación, pero que no se han eliminado:

kubectl get all -n my-namespace -o json | \
  jq '.items[] | select(.metadata.deletionTimestamp != null) | {name: .metadata.name, kind: .kind, finalizers: .metadata.finalizers}'

Para resolverlo:

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

La sincronización fallida no se reintenta automáticamente con la misma revisión

Después que falle la sincronización con una revisión específica, Argo CD no reintenta automáticamente la misma revisión. Esto suele ocurrir a causa de un defecto del manifiesto, como ComparisonError de una clave de variable de entorno duplicada.

Para confirmarlo, compruebe el estado de la aplicación:

argocd app get my-app
# Look for: Operation: Sync  Phase: Failed  Revision: <sha>

Para resolverlo, corrija el defecto del manifiesto en el repositorio de Git y envíe una nueva confirmación. Como alternativa, active una sincronización manual:

argocd app sync my-app
         

La rotación de confirmaciones en monorrepositorios activa una regeneración amplia

Si muchas aplicaciones hacen un seguimiento de HEAD en el mismo repositorio, cualquier confirmación en ese repositorio cambiará HEAD para todas las aplicaciones. Esto activa la regeneración del manifiesto de todas las aplicaciones, incluso de aquellas cuyos archivos no se han modificado. Para obtener más información sobre targetRevision y el almacenamiento en caché, consulte la sección “Aumento del tiempo de sincronización de las aplicaciones” de esta página.

Para limitar la regeneración solo a los archivos que utiliza cada aplicación, agregue la anotación 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

Con esta anotación, Argo CD solo regenera los manifiestos cuando los archivos que se encuentran en la ruta especificada cambian. Para las bibliotecas compartidas que se utilizan en todas las aplicaciones, puede especificar varias rutas separadas por punto y coma (;).

Siempre que sea posible, fije targetRevision en el nombre de una ramificación o etiqueta en lugar de HEAD.

Los webhooks predeterminados y mutantes de Kubernetes provocan diferencias fantasma

Si la aplicación muestra OutOfSync inmediatamente después de una sincronización, compruebe las diferencias para los campos que nunca estableció (como terminationGracePeriodSeconds, dnsPolicy o /spec/replicas). El servidor de API de Kubernetes o un webhook mutante agregó esos campos en el momento de la aplicación.

Para resolverlo en campos administrados por otro controlador (por ejemplo, /spec/replicas cuando un HPA administra el escalado), agregue 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 los campos agregados mediante webhooks predeterminados o mutantes de Kubernetes, puede habilitar las diferencias del servidor en la aplicación:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true

La diferencia del servidor lleva a cabo una aplicación de prueba por recurso, lo que aumenta la carga en el servidor de la API de Kubernetes. Pruébelo en un número reducido de aplicaciones antes de habilitarlo de forma generalizada.

Recursos propiedad del controlador de alta rotación

Algunos controladores generan una gran cantidad de recursos de corta duración o que se actualizan con frecuencia. Algunos ejemplos son los objetos de nodo de Karpenter, los objetos de punto de conexión e identidad de Cilium y los informes de políticas de Kyverno. Si estos recursos generan un gran volumen de eventos de observación y causan la rotación de la sincronización, puede reducir la carga si se excluyen esos tipos de recursos o se filtran los eventos de observación. Estos cambios requieren una configuración del controlador de instancia.

En la capacidad administrada, abra un caso de AWS Support para solicitar exclusiones de recursos o un filtrado de eventos de observación para estos tipos de recursos.

Prácticas recomendadas

Cuándo ponerse en contacto con AWS Support

Abra un caso de AWS Support en las siguientes situaciones:

Incluya la salida de argocd app get y argocd app diff para las aplicaciones afectadas en el caso de soporte.

Siguientes pasos