Esercitazione: Distribuire configurazioni usando GitOps in un cluster Kubernetes abilitato per Azure Arc

Articolo
05/09/2023

Importante

Questa esercitazione è destinata a GitOps con Flux v1. GitOps con Flux v2 è ora disponibile per i cluster Kubernetes e servizio Azure Kubernetes (AKS) abilitati per Azure Arc; passare all'esercitazione per GitOps con Flux v2. È consigliabile eseguire la migrazione a Flux v2 appena possibile.

Il supporto per le risorse di configurazione cluster basate su Flux v1 create prima del 1° gennaio 2024 terminerà il 24 maggio 2025. A partire dal 1° gennaio 2024, non sarà possibile creare nuove risorse di configurazione del cluster basate su Flux v1.

In questa esercitazione verranno applicate configurazioni usando GitOps in un cluster Kubernetes abilitato per Azure Arc. Si apprenderà come:

Creare una configurazione in un cluster Kubernetes abilitato per Azure Arc usando un repository Git di esempio.
Verificare che la configurazione sia stata creata correttamente.
Applicare la configurazione da un repository Git privato.
Convalidare la configurazione di Kubernetes.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Un cluster kubernetes abilitato per Azure Arc esistente.
- Se non è ancora stato connesso un cluster, vedere la guida introduttiva Connettere un cluster Kubernetes abilitato per Azure Arc.
Conoscenza dei vantaggi e dell'architettura di questa funzionalità. Per altre informazioni, vedere l'articolo Configurazioni e GitOps - Kubernetes con abilitazione di Azure Arc.
Installare l'estensione dell'interfaccia k8s-configuration della riga di comando di Azure della versione >= 1.0.0:
```
az extension add --name k8s-configuration
```
Suggerimento

Se l'estensione k8s-configuration è già installata, è possibile aggiornarla alla versione più recente usando il comando seguente: az extension update --name k8s-configuration

Creare una configurazione

Il repository di esempio usato in questo articolo è strutturato in base all'utente di un operatore cluster. I manifesti in questo repository effettuano il provisioning di alcuni spazi dei nomi, distribuiscono i carichi di lavoro e forniscono una configurazione specifica del team. L'uso di questo repository con GitOps crea le risorse seguenti nel cluster:

Spazi dei nomi: cluster-config, team-a, team-b
Distribuzione: arc-k8s-demo
ConfigMap: team-a/endpoints

Azure config-agent esegue il polling di configurazioni nuove o aggiornate. Questa attività richiederà fino a 5 minuti.

Se si associa un repository privato alla configurazione, completare la procedura seguente in Applicare la configurazione da un repository Git privato.

Utilizzare l'interfaccia della riga di comando di Azure

Usare l'estensione dell'interfaccia della riga di comando di Azure per per k8s-configuration collegare un cluster connesso al repository Git di esempio.

Denominare questa configurazione cluster-config.
Indicare all'agente di distribuire l'operatore nello cluster-config spazio dei nomi .

Assegnare all'operatore cluster-admin le autorizzazioni.

az k8s-configuration create --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --operator-instance-name cluster-config --operator-namespace cluster-config --repository-url https://github.com/Azure/arc-k8s-demo --scope cluster --cluster-type connectedClusters

{
  "complianceStatus": {
  "complianceState": "Pending",
  "lastConfigApplied": "0001-01-01T00:00:00",
  "message": "{\"OperatorMessage\":null,\"ClusterState\":null}",
  "messageLevel": "3"
  },
  "configurationProtectedSettings": {},
  "enableHelmOperator": false,
  "helmOperatorProperties": null,
  "id": "/subscriptions/<sub id>/resourceGroups/<group name>/providers/Microsoft.Kubernetes/connectedClusters/<cluster name>/providers/Microsoft.KubernetesConfiguration/sourceControlConfigurations/cluster-config",
  "name": "cluster-config",
  "operatorInstanceName": "cluster-config",
  "operatorNamespace": "cluster-config",
  "operatorParams": "--git-readonly",
  "operatorScope": "cluster",
  "operatorType": "Flux",
  "provisioningState": "Succeeded",
  "repositoryPublicKey": "",
  "repositoryUrl": "https://github.com/Azure/arc-k8s-demo",
  "resourceGroup": "MyRG",
  "sshKnownHostsContents": "",
  "systemData": {
    "createdAt": "2020-11-24T21:22:01.542801+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2020-11-24T21:22:01.542801+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
  },
  "type": "Microsoft.KubernetesConfiguration/sourceControlConfigurations"
}

Usare un repository Git pubblico

Parametro	Format
`--repository-url`	http[s]://server/repo[.git]

Usare un repository Git privato con chiavi SSH e create da Flux

Aggiungere la chiave pubblica generata da Flux all'account utente nel provider di servizi Git. Se la chiave viene aggiunta al repository anziché all'account utente, usare git@ al posto dell'URL user@ .

Per altri dettagli, passare alla sezione Applica configurazione da un repository Git privato .

Parametro	Format	Note
`--repository-url`	ssh://user@server/repo[.git] o user@server:repo[.git]	`git@` può sostituire `user@`

Usare un repository Git privato con chiavi SSH e fornite dall'utente

Specificare la propria chiave privata direttamente o in un file. La chiave deve essere in formato PEM e terminare con newline (\n).

Aggiungere la chiave pubblica associata all'account utente nel provider di servizi Git. Se la chiave viene aggiunta al repository anziché all'account utente, usare git@ al posto di user@.

Per altri dettagli, passare alla sezione Applica configurazione da un repository Git privato .

Parametro	Format	Note
`--repository-url`	ssh://user@server/repo[.git] o user@server:repo[.git]	`git@` può sostituire `user@`
`--ssh-private-key`	Chiave con codifica base64 in formato PEM	Specificare direttamente la chiave
`--ssh-private-key-file`	percorso completo del file locale	Specificare il percorso completo del file locale che contiene la chiave in formato PEM

Usare un host Git privato con SSH e host noti forniti dall'utente

L'operatore Flux gestisce un elenco di host Git comuni nel relativo file di host noti per autenticare il repository Git prima di stabilire la connessione SSH. Se si usa un repository Git non comune o il proprio host Git, è possibile specificare la chiave host in modo che Flux possa identificare il repository.

Proprio come le chiavi private, è possibile fornire il contenuto known_hosts direttamente o in un file. Quando si specificano contenuti personalizzati, usare le specifiche del formato di contenuto known_hosts, insieme a uno degli scenari di chiave SSH precedenti.

Parametro	Format	Note
`--repository-url`	ssh://user@server/repo[.git] o user@server:repo[.git]	`git@` può sostituire `user@`
`--ssh-known-hosts`	codifica base64	Fornire direttamente il contenuto degli host noti
`--ssh-known-hosts-file`	percorso completo del file locale	Fornire contenuto host noti in un file locale

Usare un repository Git privato con HTTPS

Parametro	Format	Note
`--repository-url`	https://server/repo[.git]	HTTPS con autenticazione di base
`--https-user`	non elaborato o con codifica base64	Nome utente HTTPS
`--https-key`	non elaborato o con codifica base64	Token di accesso personale HTTPS o password

Nota

Il grafico degli operatori Helm versione 1.2.0+ supporta l'autenticazione privata di rilascio HTTPS Helm.
La versione Helm HTTPS non è supportata per i cluster gestiti dal servizio Azure Kubernetes.
Se è necessario Flux per accedere al repository Git tramite il proxy, sarà necessario aggiornare gli agenti di Azure Arc con le impostazioni proxy. Per altre informazioni, vedere Connettersi usando un server proxy in uscita.

Parametri aggiuntivi

Personalizzare la configurazione con i parametri facoltativi seguenti:

Parametro	Descrizione
`--enable-helm-operator`	Passare all'opzione per abilitare il supporto per le distribuzioni del grafico Helm.
`--helm-operator-params`	Valori del grafico per l'operatore Helm (se abilitato). Ad esempio, `--set helm.versions=v3`.
`--helm-operator-chart-version`	Versione del grafico per l'operatore Helm (se abilitata). Usare la versione 1.2.0+. Impostazione predefinita: '1.2.0'.
`--operator-namespace`	Nome per lo spazio dei nomi dell'operatore. Impostazione predefinita: 'default'. Massimo: 23 caratteri.
`--operator-params`	Parametri per l'operatore. Deve essere specificato tra virgolette singole. Ad esempio, usare `--operator-params='--git-readonly --sync-garbage-collection --git-branch=main'`

Opzioni supportate in `--operator-params`:

Opzione	Descrizione
`--git-branch`	Ramo del repository Git da usare per i manifesti kubernetes. Il valore predefinito è "master". I repository più recenti hanno il ramo radice denominato `main`, in cui è necessario impostare `--git-branch=main`.
`--git-path`	Percorso relativo all'interno del repository Git per Flux per individuare i manifesti di Kubernetes.
`--git-readonly`	Il repository Git verrà considerato di sola lettura. Il flusso non tenterà di scriverlo.
`--manifest-generation`	Se abilitato, Flux cercherà solo .flux.yaml ed eseguirà Kustomize o altri generatori di manifesti.
`--git-poll-interval`	Periodo in cui eseguire il polling del repository Git per i nuovi commit. Il valore predefinito è `5m` (5 minuti).
`--sync-garbage-collection`	Se abilitato, Flux eliminerà le risorse create, che tuttavia non saranno più presenti in Git.
`--git-label`	Etichetta per tenere traccia dello stato di avanzamento della sincronizzazione. Usato per contrassegnare il ramo Git. Il valore predefinito è `flux-sync`.
`--git-user`	Nome utente per il commit Git.
`--git-email`	Email da usare per il commit Git.

Se non si vuole che Flux venga scritto nel repository e --git-user non --git-email sia impostato, --git-readonly verrà impostato automaticamente.

Per altre informazioni, vedere la documentazione di Flux.

Nota

Flusso predefinito per la sincronizzazione dal master ramo del repository git. Tuttavia, i repository Git più recenti hanno il ramo radice denominato main, in questo caso è necessario impostare --git-branch=main nel parametro --operator-params.

Suggerimento

È possibile creare una configurazione nella portale di Azure nella scheda GitOps della risorsa Kubernetes abilitata per Azure Arc.

Convalidare la configurazione

Usare l'interfaccia della riga di comando di Azure per verificare che la configurazione sia stata creata correttamente.

az k8s-configuration show --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --cluster-type connectedClusters

La risorsa di configurazione verrà aggiornata con lo stato di conformità, i messaggi e le informazioni di debug.

{
  "complianceStatus": {
    "complianceState": "Installed",
    "lastConfigApplied": "2020-12-10T18:26:52.801000+00:00",
    "message": "...",
    "messageLevel": "Information"
  },
  "configurationProtectedSettings": {},
  "enableHelmOperator": false,
  "helmOperatorProperties": {
    "chartValues": "",
    "chartVersion": ""
  },
  "id": "/subscriptions/<sub id>/resourceGroups/AzureArcTest/providers/Microsoft.Kubernetes/connectedClusters/AzureArcTest1/providers/Microsoft.KubernetesConfiguration/sourceControlConfigurations/cluster-config",
  "name": "cluster-config",
  "operatorInstanceName": "cluster-config",
  "operatorNamespace": "cluster-config",
  "operatorParams": "--git-readonly",
  "operatorScope": "cluster",
  "operatorType": "Flux",
  "provisioningState": "Succeeded",
  "repositoryPublicKey": "...",
  "repositoryUrl": "git://github.com/Azure/arc-k8s-demo.git",
  "resourceGroup": "AzureArcTest",
  "sshKnownHostsContents": null,
  "systemData": {
    "createdAt": "2020-12-01T03:58:56.175674+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2020-12-10T18:30:56.881219+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
},
  "type": "Microsoft.KubernetesConfiguration/sourceControlConfigurations"
}

Quando viene creata o aggiornata una configurazione, vengono eseguite alcune operazioni:

Azure Arc config-agent monitora Resource Manager di Azure per configurazioni nuove o aggiornate (Microsoft.KubernetesConfiguration/sourceControlConfigurations) e nota la nuova Pending configurazione.
Legge config-agent le proprietà di configurazione e crea lo spazio dei nomi di destinazione.
Azure Arc controller-manager crea un account del servizio Kubernetes e lo esegue il mapping a ClusterRoleBinding o RoleBinding per le autorizzazioni appropriate (cluster o namespace l'ambito). Distribuisce quindi un'istanza di flux.
Se si usa l'opzione SSH con chiavi generate da Flux, flux genera una chiave SSH e registra la chiave pubblica.
Lo config-agent stato dei report torna alla risorsa di configurazione in Azure.

Durante il processo di provisioning, la risorsa di configurazione verrà spostata in alcuni stati. Monitorare lo stato di avanzamento con il comando az k8s-configuration show ... precedente:

Modifica della fase	Descrizione
`complianceStatus`->`Pending`	Rappresenta gli stati iniziali e in corso.
`complianceStatus` ->`Installed`	`config-agent` configurato correttamente il cluster e distribuito `flux` senza errori.
`complianceStatus` ->`Failed`	`config-agent` è stato generato un errore durante la distribuzione di `flux`. I dettagli vengono forniti nel `complianceStatus.message` corpo della risposta.

Applicare la configurazione da un repository Git privato

Se si usa un repository Git privato, è necessario configurare la chiave pubblica SSH nel repository. Specificare o Flux genera la chiave pubblica SSH. È possibile configurare la chiave pubblica nel repository Git specifico o nell'utente Git che ha accesso al repository.

Ottenere la propria chiave pubblica

Se sono state generate chiavi SSH personalizzate, le chiavi private e pubbliche sono già disponibili.

Ottenere la chiave pubblica usando l'interfaccia della riga di comando di Azure

Usare quanto segue nell'interfaccia della riga di comando di Azure se le chiavi vengono generate da Flux.

az k8s-configuration show --resource-group <resource group name> --cluster-name <connected cluster name> --name <configuration name> --cluster-type connectedClusters --query 'repositoryPublicKey' 
"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAREDACTED"

Ottenere la chiave pubblica dal portale di Azure

Seguire questa procedura in portale di Azure se Flux genera le chiavi.

Nel portale di Azure, passare alla risorsa cluster connessa.
Nella pagina della risorsa selezionare "GitOps" e visualizzare l'elenco delle configurazioni per questo cluster.
Selezionare la configurazione usata dal repository Git privato.
Nella parte inferiore della finestra di contesto visualizzata, copiare la chiave pubblica del repository.

Aggiungere una chiave pubblica con GitHub

Usare una delle seguenti opzioni:

Opzione 1: aggiungere la chiave pubblica all'account utente (si applica a tutti i repository nell'account):
1. Aprire GitHub e fare clic sull'icona del profilo nell'angolo superiore destro della pagina.
2. Fare clic su Settings (Impostazioni).
3. Fare clic su SSH e chiavi GPG.
4. Fare clic su Nuova chiave SSH.
5. Specificare un titolo.
6. Incollare la chiave pubblica, escluse le virgolette circostanti.
7. Fare clic su Aggiungi chiave SSH.
Opzione 2: aggiungere la chiave pubblica come chiave di distribuzione al repository Git (si applica solo a questo repository):
1. Aprire GitHub e passare al repository.
2. Fare clic su Settings (Impostazioni).
3. Fare clic su Distribuisci chiavi.
4. Fare clic su Aggiungi chiave di distribuzione.
5. Specificare un titolo.
6. Selezionare Allow write access.
7. Incollare la chiave pubblica, escluse le virgolette circostanti.
8. Fare clic su Aggiungi chiave.

Aggiungere una chiave pubblica usando un repository Azure DevOps

Per aggiungere la chiave alle chiavi SSH, seguire questa procedura:

In Impostazioni utente nella parte superiore destra (accanto all'immagine del profilo), fare clic su Chiavi pubbliche SSH.
Selezionare + Nuova chiave.
Specificare un nome.
Incollare la chiave pubblica, escluse le virgolette circostanti.
Scegliere Aggiungi.

Convalidare la configurazione di Kubernetes

Dopo config-agent aver installato l'istanza, le flux risorse mantenute nel repository Git devono iniziare a scorrere nel cluster. Verificare che gli spazi dei nomi, le distribuzioni e le risorse siano stati creati con il comando seguente:

kubectl get ns --show-labels

NAME              STATUS   AGE    LABELS
azure-arc         Active   24h    <none>
cluster-config    Active   177m   <none>
default           Active   29h    <none>
itops             Active   177m   fluxcd.io/sync-gc-mark=sha256.9oYk8yEsRwWkR09n8eJCRNafckASgghAsUWgXWEQ9es,name=itops
kube-node-lease   Active   29h    <none>
kube-public       Active   29h    <none>
kube-system       Active   29h    <none>
team-a            Active   177m   fluxcd.io/sync-gc-mark=sha256.CS5boSi8kg_vyxfAeu7Das5harSy1i0gc2fodD7YDqA,name=team-a
team-b            Active   177m   fluxcd.io/sync-gc-mark=sha256.vF36thDIFnDDI2VEttBp5jgdxvEuaLmm7yT_cuA2UEw,name=team-b

È possibile osservare che spazi dei nomi team-a, team-b, itopse cluster-config sono stati creati.

L'operatore flux è stato distribuito nello cluster-config spazio dei nomi, come indicato dalla risorsa di configurazione:

kubectl -n cluster-config get deploy  -o wide

NAME             READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES                         SELECTOR
cluster-config   1/1     1            1           3h    flux         docker.io/fluxcd/flux:1.16.0   instanceName=cluster-config,name=flux
memcached        1/1     1            1           3h    memcached    memcached:1.5.15               name=memcached

Ulteriore approfondimento

È possibile esplorare le altre risorse distribuite come parte del repository di configurazione usando:

kubectl -n team-a get cm -o yaml
kubectl -n itops get all

Pulire le risorse

Eliminare una configurazione usando l'interfaccia della riga di comando di Azure o portale di Azure. Dopo aver eseguito il comando delete, la risorsa di configurazione verrà eliminata immediatamente in Azure. L'eliminazione completa degli oggetti associati dal cluster deve essere eseguita entro 10 minuti. Se la configurazione è in stato di errore quando viene rimossa, l'eliminazione completa degli oggetti associati può richiedere fino a un'ora.

Quando viene eliminata una configurazione con namespace ambito, lo spazio dei nomi non viene eliminato da Azure Arc per evitare l'interruzione dei carichi di lavoro esistenti. Se necessario, è possibile eliminare questo spazio dei nomi manualmente usando kubectl.

az k8s-configuration delete --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --cluster-type connectedClusters

Nota

Le modifiche apportate al cluster risultanti dalle distribuzioni dal repository Git monitorato non vengono eliminate quando la configurazione viene eliminata.

Passaggi successivi

Passare all'esercitazione successiva per informazioni su come implementare CI/CD con GitOps.

Implementare integrazione continua e recapito continuo con GitOps

Esercitazione: Distribuire configurazioni usando GitOps in un cluster Kubernetes abilitato per Azure Arc

Prerequisiti

Creare una configurazione

Utilizzare l'interfaccia della riga di comando di Azure

Usare un repository Git pubblico

Usare un repository Git privato con chiavi SSH e create da Flux

Usare un repository Git privato con chiavi SSH e fornite dall'utente

Usare un host Git privato con SSH e host noti forniti dall'utente

Usare un repository Git privato con HTTPS

Parametri aggiuntivi

Opzioni supportate in --operator-params:

Convalidare la configurazione

Applicare la configurazione da un repository Git privato

Ottenere la propria chiave pubblica

Ottenere la chiave pubblica usando l'interfaccia della riga di comando di Azure

Ottenere la chiave pubblica dal portale di Azure

Aggiungere una chiave pubblica con GitHub

Aggiungere una chiave pubblica usando un repository Azure DevOps

Convalidare la configurazione di Kubernetes

Ulteriore approfondimento

Pulire le risorse

Passaggi successivi

Risorse aggiuntive

Opzioni supportate in `--operator-params`: