**Contribuisci a migliorare questa pagina** Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. Per contribuire a questa guida per l'utente, scegli il GitHub ** link ** Modifica questa pagina su che si trova nel riquadro destro di ogni pagina. Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Risolvi i problemi relativi alle funzionalità Argo CD **Nota** Le funzionalità EKS sono completamente gestite ed eseguite all'esterno del cluster. Non hai accesso diretto ai namespace dei controller. È possibile configurare la distribuzione dei log del controller per la visibilità del comportamento del controller. Consulta [Accedi ai registri del controller EKS Capabilities](capabilities-controller-logs.md). La risoluzione dei problemi si concentra sullo stato delle funzionalità, sullo stato dell'applicazione e sulla configurazione. ## La funzionalità è ATTIVA ma le applicazioni non si sincronizzano Se la funzionalità del CD Argo mostra `ACTIVE` lo stato ma le applicazioni non si sincronizzano, controllate lo stato della funzionalità e l'applicazione. **Verifica lo stato della funzionalità: ** È possibile visualizzare i problemi relativi all'integrità e allo stato delle funzionalità nella console EKS o utilizzando la AWS CLI. **Console**: 1. Apri la console Amazon EKS all'indirizzo https://console.aws.amazon.com/eks/home \#/clusters. 1. Seleziona il nome del cluster. 1. Scegli la scheda **Osservabilità**. 1. Scegli **Monitora cluster**. 1. Scegli la ** scheda ** Funzionalità per visualizzare lo stato e lo stato di tutte le funzionalità. ** 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 ``` Cause comuni: + **Repository non configurato**: repository Git non aggiunto al CD Argo + **Autenticazione non riuscita**: chiave SSH, token o credenziali non validi CodeCommit + **Applicazione non creata**: nel cluster non sono presenti risorse applicative + **Politica di sincronizzazione**: è richiesta la sincronizzazione manuale (la sincronizzazione automatica non è abilitata) + **Autorizzazioni IAM**: autorizzazioni mancanti per CodeCommit o Secrets Manager **Controlla lo stato della domanda: ** ``` # 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}' ``` **Verifica le condizioni della domanda**: ``` # 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}' ``` ## Applicazioni bloccate nello stato «In corso» Se un'applicazione viene visualizzata `Progressing` ma non viene mai visualizzata`Healthy`, controlla lo stato delle risorse e gli eventi dell'applicazione. **Controlla lo stato delle risorse**: ``` # 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" ``` Cause comuni: + **Implementazione non pronta**: i pod non si avviano o le sonde di prontezza non funzionano + **Dipendenze tra le risorse**: risorse in attesa che altre risorse siano pronte + **Errori di estrazione delle immagini**: immagini del contenitore non accessibili + **Risorse insufficienti**: il cluster non dispone di CPU o memoria per i pod **Verifica la configurazione del cluster di destinazione ** (per configurazioni multi-cluster): ``` # 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 ``` ## Errori di autenticazione del repository Se Argo CD non può accedere ai tuoi repository Git, verifica la configurazione di autenticazione. **Per CodeCommit i repository: ** Verifica che il ruolo di capacità IAM disponga delle CodeCommit autorizzazioni: ``` # 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}} ``` Il ruolo richiede l'`codecommit:GitPull`autorizzazione per i repository. **Per i repository ** Git privati: Verifica che le credenziali del repository siano configurate correttamente: ``` # Check repository secret exists kubectl get secret -n argocd {{repo-secret-name}} -o yaml ``` Assicurati che il segreto contenga le credenziali di autenticazione corrette (chiave SSH, token o). username/password **Per i repository che utilizzano 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 problemi di distribuzione Se le applicazioni non vengono distribuite su cluster remoti, verifica la registrazione del cluster e la configurazione dell'accesso. **Controlla la registrazione del 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 ``` Assicurati che il `server` campo contenga l'ARN del cluster EKS, non l'URL dell'API Kubernetes. **Verifica la voce di accesso al cluster di destinazione: ** Nel cluster di destinazione, verifica che il ruolo Argo CD Capability abbia una voce di accesso: ``` # 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}} ``` **Controlla le autorizzazioni IAM per più account: ** Per le distribuzioni su più account, verifica che il ruolo Argo CD Capability abbia una voce di accesso nel cluster di destinazione. La funzionalità gestita utilizza EKS Access Entries per l'accesso tra più account, non l'assunzione del ruolo IAM. Per ulteriori informazioni sulla configurazione multi-cluster, vedere. [Registra i cluster di destinazione](argocd-register-clusters.md) ## Maggiore tempo di sincronizzazione delle applicazioni Se la sincronizzazione delle applicazioni richiede più tempo del previsto, utilizza i seguenti passaggi diagnostici per identificare la causa. ### Controlla l'ora dell'ultima sincronizzazione Conferma il ritardo controllando l'ultima volta che le applicazioni sono state sincronizzate: ``` # 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}' ``` ### Verifica le condizioni dell'applicazione Esamina le condizioni per la presentazione delle domande relative ai ritardi nelle code di riconciliazione: ``` # Check conditions on an application kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.conditions}' ``` ### Controlla la configurazione di TargetRevision Le applicazioni che utilizzano `targetRevision: HEAD` invalidano la cache del manifesto a ogni commit nel repository, il che rallenta i tempi di sincronizzazione: ``` # List applications using HEAD as targetRevision kubectl get application -n argocd -o jsonpath='{range .items[?(@.spec.source.targetRevision=="HEAD")]}{.metadata.name}{"\n"}{end}' ``` ### Cause comuni + **Nessuna configurazione webhook**: senza webhook, Argo CD esegue il polling dei repository con l'intervallo predefinito di 6 minuti. Ciò ritarda il rilevamento di nuovi commit. + **TargetRevision impostato su HEAD**: ogni commit nel repository invalida la cache del manifesto. Argo CD rigenera quindi i manifest a ogni riconciliazione. + **Repository Git grandi o complessi**: Monorepos o grafici Helm complessi causano una generazione lenta di manifest a causa del volume di file e modelli da elaborare. + **Numero elevato di risorse Kubernetes in una singola applicazione**: le applicazioni che gestiscono molte risorse causano una lenta sincronizzazione della cache del cluster perché Argo CD deve tenere traccia dello stato di ciascuna risorsa. ### Mitigazioni + **Configura i webhook Git**: i webhook notificano immediatamente ad Argo CD quando vengono apportate modifiche, bypassando l'intervallo di polling predefinito. Per i passaggi di configurazione, consulta. [Considerazioni su Argo CD](argocd-considerations.md) + **Usa nomi di ramo specifici o esegui il commit degli SHA**: imposta `targetRevision` un nome di ramo o esegui il commit SHA invece di `HEAD` conservare la cache del manifesto tra le sincronizzazioni. + **Dividi monorepo di grandi dimensioni**: dividi i repository di grandi dimensioni in repository più piccoli e mirati per ridurre i tempi di generazione dei manifest. + **Riduci le risorse per applicazione**: suddividi le applicazioni con molte risorse Kubernetes in più applicazioni più piccole per ridurre i tempi di sincronizzazione della cache del cluster. + **Abilita la distribuzione dei log dei controller**: i log dei controller forniscono visibilità sul comportamento di riconciliazione e sull'elaborazione delle code. Per le fasi di configurazione, vedere. [Accedi ai registri del controller EKS Capabilities](capabilities-controller-logs.md) ## Applicazioni che si sincronizzano ripetutamente o non sono sincronizzate Se l'applicazione si sincronizza e poi viene eseguita immediatamente`OutOfSync`, o se rimane bloccata in un ciclo di sincronizzazione, la causa è solitamente una deriva tra ciò che Git definisce e ciò che esiste nel cluster. Inizia con la diagnostica di base. ### Raccogli informazioni diagnostiche ``` # 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}} ``` Il `argocd app diff` comando è il punto di partenza più utile. Mostra esattamente quali campi fanno apparire l'applicazione non sincronizzata. ### Self-managed i certificati causano una deriva Controller come cert-manager, OPA Gatekeeper e KEDA generano certificati in fase di esecuzione. Questi valori di runtime non sono in Git, quindi Argo CD rileva una deriva in ogni riconciliazione. I sintomi sono: + L'applicazione si sincronizza, quindi viene visualizzata immediatamente `OutOfSync` + Il diff mostra le modifiche su un campo webhook o su un `caBundle` campo segreto TLS `data` Per risolvere questo problema, aggiungi `ignoreDifferences` i campi interessati e abilita le opzioni `RespectIgnoreDifferences` di sincronizzazione: ``` 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 interrompe i carichi di lavoro ad avvio lento Quando `selfHeal` è abilitato, Argo CD risincronizza l'applicazione quando rileva una deriva. Se l'avvio del carico di lavoro impiega 30-60 secondi, l'autoriparazione si attiva prima che il carico di lavoro diventi effettivo. `Healthy` `prune`Se abilitato, questo potrebbe ridurre le risorse parzialmente avviate. Per risolvere questo problema, correggi innanzitutto la deriva sottostante (vedi lo scenario del certificato). Se la deriva non è la causa, valuta la possibilità di disabilitare la correzione automatica per i carichi di lavoro che gestisci esclusivamente tramite Git: ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: syncPolicy: automated: selfHeal: false prune: false ``` **Nota** Self-heal il backoff timing è un'impostazione del controller a livello di istanza. Se hai bisogno di regolare la tempistica di autoriparazione anziché disabilitarla, apri una richiesta di assistenza. AWS ### ApplicationSet o collisioni tra proprietà delle risorse Se due applicazioni ApplicationSets gestiscono la stessa risorsa Kubernetes, Argo CD mostra un. `SharedResourceWarning` La risorsa non raggiunge mai uno stato stabile. Ciò si verifica in genere quando il nome di una risorsa condivisa non è definito per ambiente o cluster. Per risolvere questo problema: + Rendi unica la risorsa contenuta per proprietario. Aggiungi un suffisso di ambiente o cluster al nome della risorsa. + Quando si rinomina un ApplicationSet, impostalo per `preserveResourcesOnDeletion: true` primo per evitare lo smontaggio distruttivo delle risorse esistenti: ``` apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: my-appset spec: syncPolicy: preserveResourcesOnDeletion: true ``` ### Eliminazione bloccata dai finalizzatori di risorse Se un'applicazione è bloccata o mostra «N oggetti rimanenti da eliminare», il `resources-finalizer.argocd.argoproj.io` finalizzatore blocca la rimozione fino all'eliminazione di tutte le risorse gestite. `Terminating` Una risorsa gestita con un proprio finalizzatore non elaborabile blocca l'eliminazione a tempo indeterminato. Per confermare, elenca le risorse che hanno un timestamp di eliminazione ma non sono state rimosse: ``` kubectl get all -n {{my-namespace}} -o json | \ jq '.items[] | select(.metadata.deletionTimestamp != null) | {name: .metadata.name, kind: .kind, finalizers: .metadata.finalizers}' ``` Per risolvere questo problema: + Assicurati che il controller che possiede il finalizzatore di blocco sia integro e funzionante. + Se il controller proprietario è integro ma il finalizzatore non è in fase di elaborazione, rimuovi il finalizzatore di blocco dalla risorsa bloccata. Usando l'elenco dei finalizzatori stampato con il comando precedente, imposta l'elenco sui finalizzatori che desideri conservare e tralascia solo quello di blocco. Sostituisci `finalizer-a` e con questi nomi`finalizer-b`: ``` kubectl patch {{resource-kind}} {{resource-name}} -n {{my-namespace}} \ --type merge -p '{"metadata":{"finalizers":["finalizer-a","finalizer-b"]}}' ``` Se il finalizzatore di blocco è l'unico sulla risorsa, passa un elenco vuoto:. `--type merge -p '{"metadata":{"finalizers":[]}}'` **avvertimento** Imposta l'elenco dei finalizzatori in modo esplicito anziché rimuovere una voce per posizione. Una risorsa può trasportare finalizzatori da più di un controller. I finalizzatori non sono in un ordine garantito. La rimozione della prima voce può eliminare il finalizzatore sbagliato, lasciando in posizione quello di blocco e la risorsa ancora bloccata. La rimozione di un finalizzatore consente inoltre di ignorare qualsiasi operazione di pulizia eseguita dal controller proprietario, con conseguente perdita di AWS risorse nel cluster senza alcuna registrazione. Esegui questa operazione solo dopo aver verificato che il controller proprietario non è in grado di elaborare il finalizzatore. ### La sincronizzazione non riuscita non comporta il riavvio automatico della stessa revisione Se una sincronizzazione con una revisione specifica fallisce, Argo CD non riprova automaticamente la stessa revisione. Ciò accade comunemente a causa di un difetto manifesto, ad esempio una chiave di variabile di ambiente `ComparisonError` duplicata. Conferma controllando lo stato dell'applicazione: ``` argocd app get {{my-app}} # Look for: Operation: Sync Phase: Failed Revision: ``` Per risolvere questo problema, correggi il difetto manifesto nel tuo repository Git e invia un nuovo commit. In alternativa, attiva una sincronizzazione manuale: ``` argocd app sync {{my-app}} ``` ### Il commit churn di Monorepo attiva un'ampia rigenerazione Se molte applicazioni vengono registrate `HEAD` sullo stesso repository, qualsiasi commit in quel repository cambia per tutte le applicazioni. `HEAD` Ciò attiva la rigenerazione del manifesto per ogni applicazione, anche per quelle i cui file non sono stati modificati. Per ulteriori informazioni sulla memorizzazione nella cache `targetRevision` e sulla memorizzazione nella cache, vedere la sezione «Tempo di sincronizzazione delle applicazioni aumentato» in questa pagina. Per limitare la rigenerazione solo ai file utilizzati da ciascuna applicazione, aggiungete l'`manifest-generate-paths`annotazione: ``` 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 questa annotazione, Argo CD rigenera i manifesti solo quando i file nel percorso specificato cambiano. Per le librerie condivise utilizzate tra le applicazioni, è possibile specificare più percorsi separati da punto e virgola (). `;` Ove possibile, aggiungi `targetRevision` il nome o il tag di una filiale invece di. `HEAD` ### I webhook predefiniti e mutanti di Kubernetes causano differenze fantasma Se la tua applicazione viene visualizzata `OutOfSync` subito dopo una sincronizzazione, controlla le differenze per i campi che non hai mai impostato (come,, o). `terminationGracePeriodSeconds` `dnsPolicy` `/spec/replicas` Il server API Kubernetes o un webhook mutante hanno aggiunto questi campi al momento dell'applicazione. Per risolvere questo problema per i campi gestiti da un altro controller (ad esempio `/spec/replicas` quando un HPA gestisce la scalabilità), aggiungi: `ignoreDifferences` ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: ignoreDifferences: - group: apps kind: Deployment jsonPointers: - /spec/replicas syncPolicy: syncOptions: - RespectIgnoreDifferences=true ``` Per i campi aggiunti dai webhook predefiniti o mutanti di Kubernetes, puoi abilitare la differenza lato server sull'applicazione: ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app annotations: argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true ``` Server-side diff esegue un'applicazione a secco per risorsa, il che aumenta il carico sul server API Kubernetes. Provalo su un numero limitato di applicazioni prima di abilitarlo su larga scala. ### High-churn risorse di proprietà del controller Alcuni controller generano un gran numero di risorse di breve durata o aggiornate frequentemente. Gli esempi includono gli oggetti dei nodi Karpenter, gli oggetti identificativi ed endpoint Cilium e i report sulle policy di Kyverno. Se queste risorse generano un volume elevato di eventi di monitoraggio e causano l'interruzione della sincronizzazione, puoi ridurre il carico escludendo tali tipi di risorse o filtrando gli eventi di monitoraggio. Queste modifiche richiedono una configurazione del controller a livello di istanza. Per quanto riguarda la funzionalità gestita, apri un caso di AWS supporto per richiedere l'esclusione delle risorse o il filtro degli eventi di controllo per questi tipi di risorse. ### Best practice + **Usa prima application diff**: esegui `argocd app diff` come primo passaggio diagnostico per qualsiasi problema di sincronizzazione ripetuta. Ti mostra la causa esatta della deriva. + **Preferisci le IgnoreDifferenze ristrette**: scegli come target campi specifici su tipi di risorse specifici. Evita regole generiche di ignoramento che possono mascherare una reale deriva dalla configurazione. + **Associa IgnoreDifferences a RespectIgnoreDifferences**: Aggiungi sempre l'`RespectIgnoreDifferences=true`opzione di sincronizzazione. Senza di essa, le sincronizzazioni continuano a sovrascrivere i campi ignorati. + **Mantieni univoci i nomi delle risorse**: definisci i nomi delle risorse per ambiente e cluster per evitare conflitti di proprietà tra Applicazioni o. ApplicationSets + **Fai attenzione con prune e SelfHeal**: non abilitarli entrambi su carichi di lavoro che richiedono molto tempo per essere avviati. L'autoguarigione può abbattere le risorse prima che diventino sane. + **Aggiungi i percorsi di targetRevision e scope manifest**: per le applicazioni in archivi condivisi di grandi dimensioni, utilizza un ramo o un tag anziché e aggiungi l'annotazione`HEAD`. `manifest-generate-paths` ### Quando contattare AWS Supporto Aprire una richiesta di AWS assistenza nelle seguenti situazioni: + Instance-level l'ottimizzazione del controller sembra necessaria (conteggio dei processori, tempi di riparazione automatica o esclusione delle risorse). + Repo-server oppure la capacità del controller sembra insufficiente per il numero di applicazioni. + La configurazione, la deriva, la proprietà o i finalizzatori del carico di lavoro non spiegano il comportamento. Includi l'output delle `argocd app get` e `argocd app diff` per le applicazioni interessate nel tuo caso di supporto. ## Fasi successive + [Considerazioni su Argo CD](argocd-considerations.md)- Considerazioni e best practice su Argo CD + [Lavorare con Argo CD](working-with-argocd.md)- Crea e gestisci le applicazioni Argo CD + [Registra i cluster di destinazione](argocd-register-clusters.md)- Configurazione di implementazioni multi-cluster + [Risoluzione dei problemi relativi alle funzionalità EKS](capabilities-troubleshooting.md)- Guida generale alla risoluzione dei problemi relativi alle funzionalità