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

Articolo
09/25/2024

Importante

Questa esercitazione è destinata a GitOps con Flux v1. GitOps con Flux v2 è ora disponibile per i cluster Kubernetes abilitati per Azure Arc e il cluster del servizio Azure Kubernetes (AKS); passare all'esercitazione per GitOps con Flux v2. È consigliabile eseguire la migrazione a Flux v2 il prima 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 di Flux v1 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 connesso Kubernetes esistente abilitato per Azure Arc.
- Se non è ancora stato connesso un cluster, seguire la guida introduttiva Connettere un cluster Kubernetes abilitato per Azure Arc.
Comprendere i vantaggi e l'architettura di questa funzionalità. Per maggiori informazioni, vedere l'articolo Configurazioni e GitOps - Kubernetes abilitato per Azure Arc.
Installare l'k8s-configurationestensione dell'interfaccia 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 alla figura dell'operatore di 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 nel cluster le risorse seguenti:

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

config-agent esegue il polling di Azure per le configurazioni nuove o aggiornate. Questa attività richiede non più di 5 minuti.

Se si associa un repository privato alla configurazione, completare i passaggi seguenti in Applicare la configurazione da un repository Git privato.

Importante

Utilizzare l'interfaccia della riga di comando di Azure

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

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

Fornire le autorizzazioni all'operatore cluster-admin.

az k8s-configuration flux 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	Formattazione
`--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@ anzichè user@ nell'URL.

Per ulteriori dettagli, vedere la sezione Applicare la configurazione da un repository Git privato.

Parametro	Formattazione	Note
`--repository-url`	ssh://user@server/repo[.git] or 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 un carattere di nuova riga (\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@ anzichè user@.

Per ulteriori dettagli, vedere la sezione Applicare la configurazione da un repository Git privato.

Parametro	Formattazione	Note
`--repository-url`	ssh://user@server/repo[.git] or user@server:repo[.git]	`git@` può sostituire `user@`
`--ssh-private-key`	Chiave con codifica base64 in formato PEM	Fornire 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.

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

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

Usare un repository Git privato con HTTPS

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

Nota

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

Altri parametri

Personalizzare la configurazione con i parametri facoltativi seguenti:

Parametro	Descrizione
`--enable-helm-operator`	Passare ad abilita 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 abilitato). Usare la versione 1.2.0+. Valore predefinito: '1.2.0'.
`--operator-namespace`	Nome per lo spazio dei nomi dell'operatore. Predefinito: 'predefinito'. Massimo: 23 caratteri.
`--operator-params`	Parametri per l'operatore. Deve essere specificato tra virgolette singole. Ad esempio, `--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 principale denominato `main`, nel qual caso è necessario impostare `--git-branch=main`.
`--git-path`	Percorso relativo all'interno del repository Git per permettere a Flux di individuare i manifesti Kubernetes.
`--git-readonly`	Il repository Git verrà considerato di sola lettura. Flux non tenterà di scriverci sopra.
`--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`	Etichettare 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`	Indirizzo di posta elettronica da usare per il commit Git.

Se non si vuole che Flux scriva nel repository e --git-user o --git-email non risultano impostati, verrà impostato automaticamente --git-readonly.

Per maggiori informazioni, vedere la documentazione di Flux.

Nota

Per impostazione predefinita, Flux esegue la sincronizzazione dal ramo master del repository Git. Tuttavia, i repository Git più recenti hanno il ramo principale denominato main, nel qual caso è necessario impostare --git-branch=main in --operator-params.

Suggerimento

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

Convalida della 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"
}

Ecco cosa accade quando viene creata o aggiornata una configurazione:

Azure Arc config-agent monitora Azure Resource Manager per le configurazioni nuove o aggiornate (Microsoft.KubernetesConfiguration/sourceControlConfigurations) e comunica la nuova Pending configurazione.
config-agent legge le proprietà di configurazione e crea lo spazio dei nomi di destinazione.
Azure Arc controller-manager crea un account del servizio Kubernetes ed esegue il mapping su ClusterRoleBinding o RoleBinding per le dovute autorizzazioni ( ambito cluster o namespace). 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.
config-agent riporta lo stato alla risorsa di configurazione in Azure.

Durante il processo di provisioning, la risorsa di configurazione passerà attraverso alcune modifiche di stato. Monitorare lo stato di avanzamento con il comando az k8s-configuration show ... precedente:

Modifica fase	Descrizione
`complianceStatus`->`Pending`	Rappresenta gli stati iniziale e in corso.
`complianceStatus` ->`Installed`	`config-agent` ha configurato correttamente il cluster e ha distribuito `flux` senza errori.
`complianceStatus` ->`Failed`	`config-agent` ha prodotto 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. Sia che la chiave pubblica SSH sia specificata dall'utente o che sia generata da Flux. È 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 nel portale di Azure se Flux genera le chiavi.

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

Aggiungere 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 distribuzione chiave.
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 in alto a 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.
Fare clic su Aggiungi.

Convalidare la configurazione di Kubernetes

Dopo che config-agent avrà installato l'istanza flux, le risorse contenute nel repository Git inizieranno a fluire 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 spazio dei nomi cluster-config, 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, in questo modo:

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 il portale di Azure. Dopo aver eseguito il comando elimina, la risorsa di configurazione verrà eliminata immediatamente in Azure. L'eliminazione completa degli oggetti associati dal cluster avviene entro 10 minuti. Se la configurazione si trova in stato non riuscito 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

Durante l'eliminazione della configurazione, nessuna delle modifiche apportate al cluster, risultanti dalle distribuzioni dal repository Git rilevato, viene eliminata.

Importante

Passaggi successivi

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

Implementare CI/CD con GitOps

Condividi tramite

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

Altri parametri

Opzioni supportate in `--operator-params`:

Convalida della 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 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

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

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

Altri parametri

Opzioni supportate in --operator-params:

Convalida della 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 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

Commenti e suggerimenti

Risorse aggiuntive

Opzioni supportate in `--operator-params`: