**Aidez à améliorer cette page** Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. Pour contribuer à ce guide de l'utilisateur, cliquez sur le GitHub lien **Modifier cette page sur** qui se trouve dans le volet droit de chaque page. Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Résoudre les problèmes liés aux fonctionnalités d'Argo CD **Note** Les fonctionnalités EKS sont entièrement gérées et exécutées en dehors de votre cluster. Vous n'avez pas d'accès direct aux espaces de noms des contrôleurs. Vous pouvez configurer la diffusion du journal du contrôleur pour avoir une visibilité sur le comportement du contrôleur. Consultez [Accédez aux journaux du contrôleur EKS Capabilities](capabilities-controller-logs.md). Le dépannage se concentre sur l'état des fonctionnalités, l'état des applications et la configuration. ## La fonctionnalité est ACTIVE mais les applications ne se synchronisent pas Si la fonctionnalité de votre Argo CD affiche l'`ACTIVE`état mais que les applications ne se synchronisent pas, vérifiez l'état de la fonctionnalité et l'état de l'application. **Vérifiez l'état des capacités** : Vous pouvez consulter les problèmes liés à l'état et à l'état des fonctionnalités dans la console EKS ou à l'aide de la AWS CLI. **Console** : 1. Ouvrez la console Amazon EKS à l'adresse https://console.aws.amazon.com/eks/home \#/clusters. 1. Sélectionnez le nom de votre cluster. 1. Sélectionnez l’onglet **Observabilité**. 1. Sélectionnez **Surveiller le cluster**. 1. Choisissez l'onglet **Fonctionnalités** pour afficher l'état et l'état de toutes les fonctionnalités. ** 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 ``` **Causes courantes :** + **Référentiel non configuré** : dépôt Git non ajouté à Argo CD + **Échec de l'authentification** : clé SSH, jeton ou CodeCommit informations d'identification non valides + **Application non créée** : aucune ressource d'application n'existe dans le cluster + **Politique de synchronisation** : synchronisation manuelle requise (synchronisation automatique non activée) + Autorisations **IAM : autorisations** manquantes pour CodeCommit ou Secrets Manager **Vérifiez l'état de la demande** : ``` # 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}' ``` **Vérifiez les conditions de candidature** : ``` # 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}' ``` ## Applications bloquées dans l'état « En cours » Si une application s'affiche `Progressing` mais n'atteint jamais les `Healthy` objectifs, vérifiez l'état des ressources et les événements de l'application. **Vérifiez l'état des ressources** : ``` # 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" ``` **Causes courantes :** + **Le déploiement n'est pas prêt** : les pods ne démarrent pas ou les sondes de disponibilité échouent + **Dépendances** des ressources : ressources attendant que d'autres ressources soient prêtes + **Erreurs d'extraction d'image : les** images du conteneur ne sont pas accessibles + **Ressources insuffisantes** : le cluster ne dispose pas de processeur ou de mémoire pour les pods **Vérifiez la configuration du cluster cible** (pour les configurations multi-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 ``` ## Défaillances d'authentification du référentiel Si Argo CD ne peut pas accéder à vos référentiels Git, vérifiez la configuration de l'authentification. **Pour les CodeCommit référentiels** : Vérifiez que le rôle de capacité IAM dispose d' CodeCommit autorisations : ``` # 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}} ``` Le rôle nécessite une `codecommit:GitPull` autorisation pour accéder aux référentiels. **Pour les dépôts Git privés** : Vérifiez que les informations d'identification du référentiel sont correctement configurées : ``` # Check repository secret exists kubectl get secret -n argocd {{repo-secret-name}} -o yaml ``` Assurez-vous que le secret contient les informations d'authentification correctes (clé SSH, jeton ou username/password). **Pour les référentiels utilisant 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}} ``` ## Multi-cluster problèmes de déploiement Si les applications ne sont pas déployées sur des clusters distants, vérifiez l'enregistrement du cluster et la configuration des accès. **Vérifiez l'enregistrement du 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 ``` Assurez-vous que le `server` champ contient l'ARN du cluster EKS, et non l'URL de l'API Kubernetes. **Vérifiez l'entrée d'accès au cluster cible** : Sur le cluster cible, vérifiez que le rôle Argo CD Capability possède une entrée d'accès : ``` # 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}} ``` **Vérifiez les autorisations IAM pour les comptes multiples :** Pour les déploiements entre comptes, vérifiez que le rôle Argo CD Capability possède une entrée d'accès sur le cluster cible. La fonctionnalité gérée utilise les entrées d'accès EKS pour l'accès entre comptes, et non l'hypothèse du rôle IAM. Pour en savoir plus sur la configuration multi-clusters, consultez[Enregistrer les clusters cibles](argocd-register-clusters.md). ## Temps de synchronisation des applications accru Si la synchronisation de vos applications prend plus de temps que prévu, suivez les étapes de diagnostic suivantes pour en identifier la cause. ### Vérifiez l'heure de la dernière synchronisation Confirmez le délai en vérifiant la date de dernière synchronisation des applications : ``` # 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}' ``` ### Vérifiez les conditions d'application Vérifiez les conditions d'application pour connaître les retards dans les files d'attente de rapprochement : ``` # Check conditions on an application kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.conditions}' ``` ### Vérifiez la configuration de TargetRevision Applications qui `targetRevision: HEAD` invalident le cache du manifeste à chaque validation dans le référentiel, ce qui ralentit les temps de synchronisation : ``` # List applications using HEAD as targetRevision kubectl get application -n argocd -o jsonpath='{range .items[?(@.spec.source.targetRevision=="HEAD")]}{.metadata.name}{"\n"}{end}' ``` ### Causes courantes + **Aucune configuration de webhook** : sans webhooks, Argo CD interroge les référentiels à l'intervalle par défaut de 6 minutes. Cela retarde la détection de nouveaux commits. + **TargetRevision défini sur HEAD** : chaque validation dans le référentiel invalide le cache du manifeste. Argo CD régénère ensuite les manifestes à chaque réconciliation. + **Dépôts Git volumineux ou complexes : les** graphiques monorepos ou complexes ralentissent la génération de manifestes en raison du volume de fichiers et de modèles à traiter. + **Nombre élevé de ressources Kubernetes dans une seule application** : les applications gérant de nombreuses ressources ralentissent la synchronisation du cache du cluster, car Argo CD doit suivre l'état de chaque ressource. ### Atténuations + **Configurer les webhooks Git** : les webhooks informent Argo CD immédiatement lorsque des modifications sont apportées, en contournant l'intervalle d'interrogation par défaut. Pour les étapes de configuration, voir[Considérations relatives à Argo CD](argocd-considerations.md). + **Utilisez des noms de branche spécifiques ou validez des SHA : définissez** `targetRevision` un nom de branche ou un SHA de validation au lieu de `HEAD` conserver le cache du manifeste entre les synchronisations. + **Divisez les grands monorepos** : divisez les grands référentiels en référentiels plus petits et ciblés afin de réduire le temps de génération des manifestes. + **Réduction des ressources par application** : divisez les applications contenant de nombreuses ressources Kubernetes en plusieurs applications plus petites afin de réduire le temps de synchronisation du cache du cluster. + **Activez la livraison des journaux du** contrôleur : les journaux du contrôleur fournissent une visibilité sur le comportement de réconciliation et le traitement des files d'attente. Pour les étapes de configuration, voir[Accédez aux journaux du contrôleur EKS Capabilities](capabilities-controller-logs.md). ## Applications synchronisées à plusieurs reprises ou désynchronisées Si votre application se synchronise puis s'arrête immédiatement`OutOfSync`, ou si elle reste bloquée dans une boucle de synchronisation, cela est généralement dû à une dérive entre ce que définit Git et ce qui existe dans le cluster. Commencez par les diagnostics de base. ### Recueillir des informations de diagnostic ``` # 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}} ``` La `argocd app diff` commande est le point de départ le plus utile. Il vous indique exactement quels champs font apparaître l'application désynchronisée. ### Self-managed les certificats provoquent une dérive Les contrôleurs tels que cert-manager, OPA Gatekeeper et KEDA génèrent des certificats lors de l'exécution. Ces valeurs d'exécution ne se trouvant pas dans Git, Argo CD détecte les dérives à chaque réconciliation. Les symptômes sont les suivants : + L'application se synchronise, puis s'affiche immédiatement `OutOfSync` + Le diff montre les modifications apportées à un champ webhook ou à un `caBundle` champ secret TLS `data` Pour résoudre ce problème, ajoutez `ignoreDifferences` les champs concernés et activez `RespectIgnoreDifferences` dans vos options de synchronisation : ``` 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 ``` ### Self-heal interrompt les charges de travail qui démarrent lentement Lorsque cette option `selfHeal` est activée, Argo CD resynchronise l'application lorsqu'elle détecte une dérive. Si votre charge de travail met 30 à 60 secondes à démarrer, l'auto-guérison se déclenche avant que la charge de travail ne devienne normale. `Healthy` Lorsque cette `prune` option est activée, cela peut entraîner la destruction de ressources partiellement démarrées. Pour résoudre ce problème, corrigez d'abord la dérive sous-jacente (voir le scénario du certificat). Si la dérive n'en est pas la cause, pensez à désactiver l'auto-guérison pour les charges de travail que vous gérez exclusivement via Git : ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: syncPolicy: automated: selfHeal: false prune: false ``` **Note** Self-heal le temps d'arrêt est un paramètre du contrôleur au niveau de l'instance. Si vous devez ajuster le délai d'auto-guérison plutôt que de le désactiver, ouvrez un dossier de AWS Support. ### ApplicationSet ou des collisions entre propriétaires de ressources S'il s'agit de deux applications ou de la ApplicationSets gestion de la même ressource Kubernetes, Argo CD affiche un. `SharedResourceWarning` La ressource n'atteint jamais un état stable. Cela se produit généralement lorsqu'un nom de ressource partagée n'est pas défini par environnement ou par cluster. Pour résoudre ce problème : + Rendez la ressource contestée unique par propriétaire. Ajoutez un suffixe d'environnement ou de cluster au nom de la ressource. + Lorsque vous renommez un ApplicationSet, configurez d'`preserveResourcesOnDeletion: true`abord pour éviter le démantèlement destructeur des ressources existantes : ``` apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: my-appset spec: syncPolicy: preserveResourcesOnDeletion: true ``` ### Suppression bloquée dans les finaliseurs de ressources Si une application est bloquée ou affiche « N objets restant à `Terminating` supprimer », le `resources-finalizer.argocd.argoproj.io` finaliseur bloque la suppression jusqu'à ce que toutes les ressources gérées soient supprimées. Une ressource gérée dotée de son propre finaliseur non traitable bloque la suppression indéfiniment. Pour confirmer, listez les ressources qui ont un horodatage de suppression mais qui n'ont pas été supprimées : ``` kubectl get all -n {{my-namespace}} -o json | \ jq '.items[] | select(.metadata.deletionTimestamp != null) | {name: .metadata.name, kind: .kind, finalizers: .metadata.finalizers}' ``` Pour résoudre ce problème : + Assurez-vous que le contrôleur qui possède le finaliseur de blocage est en bon état et fonctionne. + Si le contrôleur propriétaire est sain mais que le finaliseur n'est pas en cours de traitement, supprimez le finaliseur bloquant de la ressource bloquée : ``` kubectl patch {{resource-kind}} {{resource-name}} -n {{my-namespace}} \ --type json -p '[{"op": "remove", "path": "/metadata/finalizers/0"}]' ``` ### L'échec de la synchronisation n'entraîne pas de nouvelle tentative automatique pour la même révision Après l'échec de la synchronisation avec une révision spécifique, Argo CD ne réessaie pas automatiquement la même révision. Cela se produit généralement en raison d'un défaut manifeste tel qu'une clé `ComparisonError` de variable d'environnement dupliquée. Confirmez en vérifiant le statut de la demande : ``` argocd app get {{my-app}} # Look for: Operation: Sync Phase: Failed Revision: ``` Pour résoudre ce problème, corrigez le défaut manifeste dans votre dépôt Git et envoyez un nouveau commit. Vous pouvez également déclencher une synchronisation manuelle : ``` argocd app sync {{my-app}} ``` ### Le taux de désabonnement de Monorepo déclenche une large régénération Si de nombreuses applications effectuent le suivi `HEAD` sur le même référentiel, toute validation dans ce référentiel change `HEAD` pour toutes les applications. Cela déclenche la régénération du manifeste pour toutes les applications, même celles dont les fichiers n'ont pas été modifiés. Pour plus d'informations sur la mise en cache `targetRevision` et la mise en cache, consultez la section « Augmentation du temps de synchronisation des applications » de cette page. Pour étendre la régénération aux seuls fichiers utilisés par chaque application, ajoutez l'`manifest-generate-paths`annotation suivante : ``` 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 ``` Avec cette annotation, Argo CD ne régénère les manifestes que lorsque les fichiers situés sous le chemin spécifié changent. Pour les bibliothèques partagées utilisées dans les applications, vous pouvez spécifier plusieurs chemins séparés par des points-virgules (). `;` Dans la mesure du possible, épinglez `targetRevision` le nom ou le tag d'une succursale au lieu de`HEAD`. ### Les webhooks par défaut et mutants de Kubernetes provoquent des différences fantômes Si votre application s'affiche `OutOfSync` immédiatement après une synchronisation, cochez la case de différence pour les champs que vous n'avez jamais définis (tels que `terminationGracePeriodSeconds``dnsPolicy`, ou`/spec/replicas`). Le serveur d'API Kubernetes ou un webhook en mutation ont ajouté ces champs au moment de l'application. Pour résoudre ce problème pour les champs gérés par un autre contrôleur (par exemple `/spec/replicas` lorsqu'un HPA gère le dimensionnement), ajoutez `ignoreDifferences` : ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: ignoreDifferences: - group: apps kind: Deployment jsonPointers: - /spec/replicas syncPolicy: syncOptions: - RespectIgnoreDifferences=true ``` Pour les champs ajoutés par des webhooks par défaut ou mutants de Kubernetes, vous pouvez activer le diff côté serveur sur l'application : ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app annotations: argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true ``` Server-side diff effectue une application à sec par ressource, ce qui augmente la charge sur le serveur d'API Kubernetes. Testez cette option sur un petit nombre d'applications avant de l'activer à grande échelle. ### High-churn ressources appartenant au contrôleur Certains contrôleurs génèrent un grand nombre de ressources éphémères ou fréquemment mises à jour. Les exemples incluent les objets de nœud Karpenter, les objets d'identité et de point de terminaison Cilium, ainsi que les rapports de politique Kyverno. Si ces ressources génèrent un volume élevé d'événements de surveillance et entraînent une perte de synchronisation, vous pouvez réduire la charge en excluant ces types de ressources ou en filtrant les événements de surveillance. Ces modifications nécessitent une configuration du contrôleur au niveau de l'instance. Sur la fonctionnalité gérée, ouvrez un dossier AWS Support pour demander des exclusions de ressources ou un filtrage des événements de surveillance pour ces types de ressources. ### Bonnes pratiques + **Utilisez d'abord le diff de l'application** : Exécuter `argocd app diff` comme première étape de diagnostic pour tout problème de synchronisation répétée. Il vous indique la cause exacte de la dérive. + **Préférez l'option IgnoreDifferences étroite** : ciblez des champs spécifiques sur des types de ressources spécifiques. Évitez les règles d'ignorance générales qui peuvent masquer une véritable dérive de configuration. + **Associez IgnoreDifferences à RespectIgnoreDifferences** : Ajoutez toujours l'option de `RespectIgnoreDifferences=true` synchronisation. Sans cela, les synchronisations remplacent toujours les champs ignorés. + **Conservez des noms de ressources uniques** : définissez le champ d'application des noms de ressources par environnement et par cluster afin d'éviter les collisions de propriété entre les applications ou ApplicationSets. + **Soyez prudent avec prune et SelfHeal** : n'activez pas les deux sur des charges de travail dont le démarrage prend du temps. L'auto-guérison peut détruire les ressources avant qu'elles ne deviennent saines. + **Épinglez les chemins du manifeste de TargetRevision et de scope** : pour les applications situées dans de grands référentiels partagés, utilisez une branche ou une balise à la place de l'annotation `HEAD` et ajoutez-y l'annotation. `manifest-generate-paths` ### Quand contacter AWS Support Ouvrez un dossier de AWS Support dans les situations suivantes : + Instance-level le réglage du contrôleur semble nécessaire (nombre de processeurs, chronométrage de l'auto-guérison ou exclusions de ressources). + Repo-server ou la capacité du contrôleur semble insuffisante par rapport au nombre de vos applications. + La configuration, la dérive, la propriété ou les finaliseurs de la charge de travail n'expliquent pas le comportement. Incluez le résultat de `argocd app get` et `argocd app diff` pour les applications concernées dans votre dossier d'assistance. ## Étapes suivantes + [Considérations relatives à Argo CD](argocd-considerations.md)- Considérations et meilleures pratiques relatives à Argo CD + [Travailler avec Argo CD](working-with-argocd.md)- Création et gestion des applications Argo CD + [Enregistrer les clusters cibles](argocd-register-clusters.md)- Configurer des déploiements multi-clusters + [Dépannage des fonctionnalités EKS](capabilities-troubleshooting.md)- Conseils généraux de résolution des problèmes liés aux fonctionnalités