Esercitazione: Distribuire applicazioni usando GitOps con Argo CD

Questa esercitazione descrive come usare GitOps con Argo CD nei cluster Kubernetes abilitati per Azure Arc o nei cluster del servizio Azure Kubernetes. GitOps con Argo CD è abilitato come estensione del cluster che consente di utilizzare il repository Git come fonte autorevole per la configurazione del cluster e la distribuzione delle applicazioni. Argo CD supporta anche altre origini di file comuni, ad esempio repository Helm e Open Container Initiative (OCI).

Prerequisiti

Per distribuire applicazioni con GitOps, ti serve un cluster Kubernetes abilitato per Azure Arc o un cluster AKS.

Cluster Kubernetes abilitato per Azure Arc

• Un cluster Kubernetes abilitato per Azure Arc in esecuzione.

  Informazioni su come connettere un cluster Kubernetes ad Azure Arc. Se è necessario connettersi tramite un proxy in uscita, assicurarsi di installare gli agenti Arc con le impostazioni proxy.

• Autorizzazioni di lettura e scrittura per il tipo di risorsa Microsoft.Kubernetes/connectedClusters.

Cluster del servizio Azure Kubernetes

• Un cluster del servizio Azure Kubernetes basato su MSI in esecuzione.

  Importante

  Per il funzionamento di questa estensione, è necessario creare il cluster AKS con Managed Service Identity (MSI), non con Service Principal Name (SPN). Per i nuovi cluster del servizio Azure Kubernetes creati con az aks create, il cluster è basato su MSI per impostazione predefinita. Per convertire cluster basati su SPN in MSI, eseguire az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-managed-identity. Per ulteriori informazioni, vedere Utilizzare un'identità gestita in AKS.

• Autorizzazioni di lettura e scrittura per il tipo di risorsa Microsoft.ContainerService/managedClusters.

Comune a entrambi i tipi di cluster

• Autorizzazioni di lettura e scrittura per questi tipi di risorsa:

  • Microsoft.KubernetesConfiguration/extensions

• Interfaccia della riga di comando di Azure 2.15 o versione successiva. Installare l'interfaccia della riga di comando di Azure o usare i comandi seguenti per eseguire l'aggiornamento alla versione più recente:

  az version
  az upgrade
  

• Il client da riga di comando Kubernetes, kubectl. kubectl è già installato se si usa Azure Cloud Shell.

  Eseguire l'installazione kubectl in locale usando il comando az aks install-cli:

  az aks install-cli
  

• Registrazione dei seguenti provider di risorse di Azure:

  az provider register --namespace Microsoft.Kubernetes
  az provider register --namespace Microsoft.ContainerService
  az provider register --namespace Microsoft.KubernetesConfiguration
  

  La registrazione è un processo asincrono e terminerà entro 10 minuti. Usare il comando seguente per monitorare il processo di registrazione:

  az provider show -n Microsoft.KubernetesConfiguration -o table
  
  Namespace                          RegistrationPolicy    RegistrationState
  ---------------------------------  --------------------  -------------------
  Microsoft.KubernetesConfiguration  RegistrationRequired  Registered
  

Supporto di versione e area geografica

GitOps è attualmente supportato nelle aree pubbliche.

Requisiti di rete

Gli agenti GitOps richiedono TCP in uscita all'origine del repository sulla porta 22 (SSH) o sulla porta 443 (HTTPS) per funzionare. Richiedono anche l'accesso agli URL in uscita seguenti:

Abilitare le estensioni CLI

Installare i pacchetti di estensione dell'interfaccia della riga di comando di k8s-configuration e k8s-extension più recenti:

az extension add -n k8s-configuration
az extension add -n k8s-extension

Per aggiornare questi pacchetti alle versioni più recenti:

az extension update -n k8s-configuration
az extension update -n k8s-extension

Per visualizzare un elenco di tutte le estensioni dell'interfaccia della riga di comando di Azure installate e le relative versioni, usare il comando seguente:

az extension list -o table

Experimental   ExtensionType   Name                   Path                                                       Preview   Version
-------------  --------------  -----------------      -----------------------------------------------------      --------  --------
False          whl             connectedk8s           C:\Users\somename\.azure\cliextensions\connectedk8s         False     1.10.7
False          whl             k8s-configuration      C:\Users\somename\.azure\cliextensions\k8s-configuration    False     2.2.0
False          whl             k8s-extension          C:\Users\somename\.azure\cliextensions\k8s-extension        False     1.6.4

Creare l'estensione GitOps (Argo CD) (installazione semplice)

L'installazione di GitOps Argo CD supporta la multi-tenancy in modalità a disponibilità elevata e supporta l'identità del carico di lavoro.

Questo comando crea la configurazione più semplice installando i componenti argo CD in un nuovo argocd spazio dei nomi con accesso a livello di cluster. L'accesso a livello di cluster consente di rilevare le definizioni di app Argo CD in qualsiasi spazio dei nomi elencato nella configurazione configmap di Argo CD nel cluster. Ad esempio: namespace1,namespace2

az k8s-extension create --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --cluster-type managedClusters \
  --name argocd \
  --extension-type Microsoft.ArgoCD \
  --config "redis-ha.enabled=false" \
  --config "configs.params.application\.namespaces=namespace1,namespace2"

Questo comando di installazione crea un nuovo <namespace> cluster e installa i componenti di Argo CD in <namespace>. Le definizioni di applicazione Argo CD in questa configurazione funzionano solo nel namespace <namespace>.

Creare l'estensione GitOps (Argo CD) con l'identità del carico di lavoro

Un metodo di installazione alternativo consigliato per l'uso in produzione è identità del carico di lavoro. Questo metodo usa identità Microsoft Entra ID per eseguire l'autenticazione per Azure risorse, quindi non è necessario gestire segreti o credenziali nel repository Git. Questa installazione utilizza l'autenticazione tramite identità del carico di lavoro, disponibile a partire dalla versione OSS 3.0.0-rc2 di Argo CD.

Per creare l'estensione con l'identità del carico di lavoro, sostituire prima di tutto le variabili seguenti con i propri valori in questo modello Bicep:

var clusterName = '<aks-or-arc-cluster-name>'

var workloadIdentityClientId = 'replace-me##-##-###-###'
var ssoApplicationClientId = 'replace-me##-##-###-###'

var url = 'https://<public-ip-for-argocd-ui>/'
var oidcConfig = '''
name: Azure
issuer: https://login.microsoftonline.com/<your-tenant-id>/v2.0
clientID: <same-value-as-ssoApplicationClientId>
azure:
  useWorkloadIdentity: true
requestedIDTokenClaims:
  groups:
    essential: true
requestedScopes:
  - openid
  - profile
  - email
'''

var defaultPolicy = 'role:readonly'
var policy = '''
p, role:org-admin, applications, *, */*, allow
p, role:org-admin, clusters, get, *, allow
p, role:org-admin, repositories, get, *, allow
p, role:org-admin, repositories, create, *, allow
p, role:org-admin, repositories, update, *, allow
p, role:org-admin, repositories, delete, *, allow
g, replace-me##-argocd-ui-entra-group-admin-id, role:org-admin
'''

resource cluster 'Microsoft.ContainerService/managedClusters@2024-10-01' existing = {
  name: clusterName
}

resource extension 'Microsoft.KubernetesConfiguration/extensions@2023-05-01' = {
  name: 'argocd'
  scope: cluster
  properties: {
    extensionType: 'Microsoft.ArgoCD'
    configurationSettings: {
      'redis-ha.enabled': 'true'
      'azure.workloadIdentity.enabled': 'true'
      'azure.workloadIdentity.clientId': workloadIdentityClientId
      'azure.workloadIdentity.entraSSOClientId': ssoApplicationClientId
      'configs.cm.oidc\\.config': oidcConfig
      'configs.cm.url': url
      'configs.rbac.policy\\.default': defaultPolicy
      'configs.rbac.policy\\.csv': policy
      'configs.params.application\\.namespaces': 'default, argocd'
   }
  }
}

Creare il modello di Bicep usando il comando seguente:

az deployment group create --resource-group <resource-group> --template-file <bicep-file>

Parametri

clusterName è il nome del cluster Kubernetes abilitato per Arc o del cluster del servizio Azure Kubernetes.

workloadIdentityClientId è l'ID client dell'identità gestita assegnata dall'utente usata per l'identità del carico di lavoro dai componenti di Argo CD.

ssoApplicationClientId è l'ID applicazione (client) della registrazione dell'app Microsoft Entra usata per l'autenticazione SSO OIDC all'interfaccia utente di Argo CD. Per altre informazioni sulla configurazione e le impostazioni generali di ssoApplicationClientId, vedere Autenticazione della registrazione dell'app Microsoft Entra ID tramite OIDC.

url è l'INDIRIZZO IP pubblico dell'interfaccia utente di Argo CD. Non esiste alcun nome di dominio o IP pubblico a meno che il cluster non abbia già un controller di ingresso fornito dal cliente. In tal caso, è necessario aggiungere la regola di ingresso all'interfaccia utente di Argo CD dopo la distribuzione. La funzionalità Ingress richiede il componente aggiuntivo per il routing dell'applicazione ed è supportata solo nei cluster AKS.

oidcConfig - sostituire <your-tenant-id> con l'ID tenant dell'ID Microsoft Entra. Sostituire <same-value-as-ssoApplicationClientId-above> con lo stesso valore di ssoApplicationClientId.

La variabile policy è data dalle impostazioni argocd-rbac-cm configmap di Argo CD. g, replace-me##-argocd-ui-entra-group-admin-id è l'ID del gruppo Microsoft Entra che consente all'amministratore di accedere all'interfaccia utente di Argo CD. È possibile trovare l'ID gruppo di Microsoft Entra nel portale di Azure in Microsoft Entra ID > Gruppi >proprietà nome-gruppo>. È possibile usare l'ID utente di Microsoft Entra anziché un ID gruppo di Microsoft Entra. È possibile trovare l'ID utente Microsoft Entra nel portale di Azure in Microsoft Entra ID > Utenti >proprietà nomeutente>.

Creare credenziali dell'identità del carico di lavoro

Per configurare nuove credenziali di identità per il carico di lavoro, segui questa procedura:

1. Recuperare l'URL dell'emittente OIDC per il cluster AKS o il cluster Kubernetes abilitato per Arc.

2. Creare un'identità gestita e prendere nota dell'ID client e dell'ID tenant.

3. Stabilisci una credenziale di identità federata per il cluster AKS o il cluster Kubernetes abilitato per Arc. Per esempio:

   # For source-controller
   az identity federated-credential create \
     --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} \
     --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
     --resource-group "${RESOURCE_GROUP}" \
     --issuer "${OIDC_ISSUER}" \
     --subject
   

4. Assicurarsi di fornire autorizzazioni appropriate per l'identità del carico di lavoro per la risorsa da cui si desidera che il controller argocd o image-reflector o argocd-repo-server esegua il pull. Ad esempio, se si utilizza Registro Azure Container, assicurarsi che Container Registry Repository Reader (per i registri con ABAC abilitato) o AcrPull (per i registri non ABAC) sia applicato.

Connettersi ai registri privati di Azure Container Registry o ai repository di Azure Container Registry utilizzando l'identità del carico di lavoro

Per utilizzare il registro ACR privato o i repository ACR, seguire le istruzioni nella documentazione ufficiale di Argo CD per connettersi ai registri ACR privati. I passaggi Etichettare i pod, Creare credenziali dell'identità federata e Aggiungere un'annotazione all'account del servizio in questa guida sono stati completati dall'estensione con la distribuzione Bicep e possono essere ignorati.

Eseguire la migrazione da Argo CD OSS all'estensione Cd di Argo gestita

Seguire questa procedura per eseguire la migrazione da un'installazione di Argo CD autogestito all'estensione Argo CD gestita Azure.

Percorso di migrazione

Usare la sequenza seguente per evitare conflitti di controller e ridurre i rischi di migrazione.

1. Esaminare la configurazione e l'inventario corrente di Argo CD:

   • Applications
   • Set di applicazioni
   • AppProjects
   • Credenziali e modelli del repository (repocreds)
   • Segreti del cluster

2. Impostare su zero repliche la scalabilità dei controller Argo CD autogestiti per evitare il comportamento con due controller.

3. Installare l'estensione Argo CD nel cluster usando le impostazioni che corrispondono alla distribuzione esistente.

4. La funzionalità Applicazioni in qualsiasi namespace consente ad Argo CD di gestire le risorse situate al di fuori del suo namespace principale. Se il cluster usa già questa impostazione, non è necessario spostare le risorse in un nuovo spazio dei nomi. Devi solo configurare la nuova estensione per monitorare i namespace dell'applicazione esistente.

   Caso A: se utilizzi già la funzionalità Applicazioni in qualsiasi spazio dei nomi:

   1. Lasciare tutte le risorse Application, ApplicationSet e AppProject nei namespace attuali.
   2. Configurare la nuova estensione gestita per monitorare i namespace esterni tramite le impostazioni della stessa estensione.

   Caso B: se si spostano le risorse nello spazio dei nomi della nuova estensione:

   • Migrare Applications, ApplicationSets e AppProjects nel namespace dell'estensione, se necessario.

5. Migra le credenziali del repository, i segreti del cluster e i repocreds nel namespace dell'estensione.

6. Verificare che le applicazioni si sincronizzino e raggiungano lo stato integro previsto.

7. Rimuovere la vecchia installazione di Argo CD gestita autonomamente dopo aver completato la convalida.

L'estensione gestita usa le stesse API CD Argo e le definizioni di risorse personalizzate (CRD), in modo da poter riutilizzare la maggior parte dei manifesti esistenti con modifiche minime.

Limitazioni correnti

• Gli aggiornamenti diretti a Argo CD ConfigMaps non sono supportati.
• Usare l'API di configurazione dell'estensione e le impostazioni per applicare le modifiche di configurazione di Argo CD.

Configurare il monitoraggio con Azure Prometheus gestito e Grafana con gestione Azure

È possibile pubblicare le metriche di Argo CD in Azure Prometheus gestito e visualizzarle in Grafana con gestione Azure.

1. Abilitare Azure Prometheus gestito per il cluster. Vedere Abilitare il monitoraggio per i cluster Servizio Azure Kubernetes (AKS).

2. Aggiornare la configurazione dell'estensione per abilitare le metriche e ServiceMonitors.

   var clusterName = '<aks-or-arc-cluster-name>'
   
   resource cluster 'Microsoft.ContainerService/managedClusters@2024-10-01' existing = {
     name: clusterName
   }
   
   resource extension 'Microsoft.KubernetesConfiguration/extensions@2023-05-01' = {
     name: 'argocd'
     scope: cluster
     properties: {
       extensionType: 'Microsoft.ArgoCD'
       configurationSettings: {
         // Keep your existing settings and add these metrics flags.
         'controller.metrics.enabled': 'true'
         'controller.metrics.serviceMonitor.enabled': 'true'
         'server.metrics.enabled': 'true'
         'server.metrics.serviceMonitor.enabled': 'true'
         'repoServer.metrics.enabled': 'true'
         'repoServer.metrics.serviceMonitor.enabled': 'true'
         'applicationSet.metrics.enabled': 'true'
         'applicationSet.metrics.serviceMonitor.enabled': 'true'
         'apiVersionOverrides.monitoring': 'azmonitoring.coreos.com/v1'
       }
     }
   }
   

3. Importare il dashboard Grafana 14584 nell'istanza di Grafana con gestione Azure.

4. Se i pannelli mostrano Nessun dato, aggiornate le query dei pannelli per tenere conto della denominazione dei processi di Azure Managed Prometheus.

5. Nei pannelli di telemetria del controller (Utilizzo memoria, Utilizzo CPU, Goroutine), modificare:

   • Da job="argocd-metrics"
   • A job=~"argocd.*-metrics"

6. Nei pannelli del repo-server (Memory Used, Goroutines), modificare:

   • Da job="argocd-repo-server"
   • A job="argocd-repo-server-metrics"

7. Salvare il dashboard e verificare l'inserimento delle metriche.

Abilitare Argo CD nel portale di Azure

È possibile abilitare Argo CD nel portale di Azure per visualizzare lo stato dell'applicazione e lo stato di sincronizzazione e per accedere all'interfaccia utente di Argo CD. Per abilitare Argo CD nel portale di Azure, seguire questa procedura:

1. Vai al cluster nel portale di Azure.

2. Nel menu del servizio, in Impostazioni, selezionare GitOps.

3. Selezionare Abilita Argo CD (anteprima) .

4. Nella sezione Informazioni di base :

   1. Impostare il namespace in cui Argo CD è in esecuzione. Per impostazione predefinita, lo spazio dei nomi è argocd.
   2. Se necessario, abilitare La disponibilità elevata di Redis. Questa opzione richiede almeno 4 nodi nel cluster.
   3. Aggiungere facoltativamente eventuali namespace aggiuntivi da monitorare.
   4. Solo per i cluster AKS, abilitare facoltativamente il Single Sign-On (SSO) in modo che gli utenti possano eseguire l'accesso tramite Microsoft Entra ID, specificando un Applicazione e uno o più Gruppi per consentire l'accesso all'interfaccia utente di Argo CD.
   5. Se necessario, abilitare l'identità del carico di lavoro per consentire a Argo CD di accedere in modo sicuro ai servizi Azure senza archiviare segreti. A tale scopo, selezionare la casella Abilita identità del carico di lavoro e specificare un'identità gestita e un Registro Azure Container da cui eseguire il pull dei manifesti dell'applicazione o degli artefatti del contenitore.

   

5. Seleziona Avanti per continuare.

6. Per i cluster AKS che hanno abilitato il componente aggiuntivo per il routing delle applicazioni, la scheda Ingress consente di creare una risorsa Ingress per instradare il traffico verso un servizio. Se lo si desidera, selezionare Abilita ingresso e immettere il nome in ingresso, i dettagli del certificato e il nome di dominio. Seleziona Avanti per continuare.

7. Nella sezione Rivedi e distribuisci esaminare le impostazioni e quindi selezionare Distribuisci per abilitare Argo CD nel cluster.

Accedere all'interfaccia utente di Argo CD

Se non esiste un controller di ingresso per il cluster AKS, l'interfaccia utente di Argo CD può essere esposta direttamente usando un servizio LoadBalancer. Il comando seguente espone l'interfaccia utente di Argo CD sulla porta 80 e 443.

kubectl -n argocd expose service argocd-server --type LoadBalancer --name argocd-server-lb --port 80 --target-port 8080

Per accedere all'interfaccia utente di Argo CD dal portale di Azure, passare al cluster. Nel menu del servizio, in Impostazioni, selezionare GitOps. Selezionare quindi il collegamento visualizzato per l'interfaccia utente di Argo CD.

Distribuire l'applicazione Argo CD

Dopo aver installato l'estensione Argo CD, è possibile distribuire un'applicazione usando l'interfaccia utente di Argo CD o l'interfaccia della riga di comando. L'esempio seguente utilizza kubectl apply per distribuire AKS Store all'interno di un'applicazione Argo CD nel progetto Argo CD predefinito nel namespace argocd.

kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: aks-store-demo
  namespace: argocd
spec:
  project: default
  source:
      repoURL: https://github.com/Azure-Samples/aks-store-demo.git
      targetRevision: HEAD
      path: kustomize/overlays/dev
  syncPolicy:
      automated: {}
  destination:
      namespace: argocd
      server: https://kubernetes.default.svc
EOF

L'applicazione demo dello store di AKS è installata nel namespace argocd. Per visualizzare la pagina Web dell'applicazione, seguire queste istruzioni. Assicurarsi di visitare l'indirizzo IP usando http e non https.

Aggiornare la configurazione dell'estensione

Le configmap di Argo CD possono essere aggiornate dopo l'installazione e altre impostazioni di configurazione dell'estensione usando il comando seguente:

az k8s-extension update --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --cluster-type <cluster-type> \
  --name argocd \
  --config "configs.cm.url='https://<public-ip-for-argocd-ui>/auth/callback'"

Aggiornare la configmap di Argo CD tramite l'estensione, in modo che le impostazioni non vengano sovrascritte. L'applicazione del modello Bicep è un metodo alternativo all'uso dell'interfaccia della riga di comando di Azure per aggiornare la configurazione.

Eliminare l'estensione

Usare i comandi seguenti per eliminare l'estensione.

az k8s-extension delete -g <resource-group> -c <cluster-name> -n argocd -t managedClusters --yes

Passaggi successivi

• Segnalare problemi e richieste di funzionalità nel repository Azure/AKS. Assicurarsi di includere la parola ArgoCD nella descrizione o nel titolo.
• Esplorare l'esempio di codice di progettazione della piattaforma Azure Kubernetes che distribuisce OSS Argo CD con Backstage e Cluster API Provider (CAPZ) o Crossplane.