Guida introduttiva: Usare Configurazione app di Azure nel servizio Azure Kubernetes

Articolo
10/16/2024

In Kubernetes si configurano i pod per l'uso della configurazione da ConfigMaps. In questo modo è possibile separare la configurazione dalle immagini del contenitore, per semplificare la portabilità delle applicazioni. Il provider Kubernetes Configurazione app di Azure può creare oggetti ConfigMaps e segreti dalle coppie chiave-valore e dai riferimenti di Key Vault in Configurazione app di Azure. Consente di sfruttare Configurazione app di Azure per l'archiviazione e la gestione centralizzate della configurazione senza apportare modifiche al codice dell'applicazione.

Un oggetto ConfigMap può essere utilizzato come variabili di ambiente o come file montato. In questa guida introduttiva si incorpora il provider Kubernetes Configurazione app di Azure in un carico di lavoro del servizio Azure Kubernetes in cui si esegue una semplice app ASP.NET Core che utilizza la configurazione da un file JSON.

Suggerimento

Vedere le opzioni per i carichi di lavoro ospitati in Kubernetes per accedere a Configurazione app di Azure.

Nota

Questa guida introduttiva illustra come configurare il provider Kubernetes Configurazione app di Azure. Facoltativamente, è possibile usare i comandi di Azure Developer CLI seguenti con il modello azure-appconfig-aks per effettuare il provisioning delle risorse di Azure e distribuire l'applicazione di esempio usata da questa guida introduttiva. Per altre informazioni su questo modello, visitare il repository azure-appconfig-aks in GitHub.

azd init -t azure-appconfig-aks
azd up

Prerequisiti

Un Archivio di configurazione app. Creare un archivio.
Un Registro Azure Container. Creare un registro.
Un cluster del servizio Azure Kubernetes autorizzato a eseguire il pull delle immagini dal Registro Azure Container. Creare un cluster del servizio Azure Kubernetes.
.NET SDK 6.0 o versione successiva
Interfaccia della riga di comando di Azure
Docker Desktop
helm
kubectl

Creare un'applicazione in esecuzione nel servizio Azure Kubernetes

In questa sezione si creerà una semplice applicazione Web ASP.NET Core in esecuzione nel servizio Azure Kubernetes. L'applicazione legge la configurazione da un file JSON locale. Nella sezione successiva la si abiliterà per l'utilizzo della configurazione da Configurazione app di Azure senza modificare il codice dell'applicazione. Se si dispone già di un'applicazione del servizio Azure Kubernetes che legge la configurazione da un file, ignorare questa sezione e passare a Usare il provider Kubernetes Configurazione app. È sufficiente assicurarsi che il file di configurazione generato dal provider corrisponda al percorso del file usato dall'applicazione.

Creare un'applicazione

Usare l'interfaccia della riga di comando di .NET ed eseguire il comando seguente per creare un nuovo progetto di app Web ASP.NET Core in una nuova directory MyWebApp:
```
dotnet new webapp --output MyWebApp --framework net6.0
```

Aprire il file Index.cshtml nella directory Pages e aggiornare il contenuto con il codice seguente.

@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
@{
    ViewData["Title"] = "Home page";
}

<style>
    h1 {
        color: @Configuration["Settings:FontColor"];
    }
</style>

<div class="text-center">
    <h1>@Configuration["Settings:Message"]</h1>
</div>

Creare una directory config nella radice del progetto e aggiungervi un file mysettings.json con il contenuto seguente.
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

Aprire program.cs e aggiungere il file JSON all'origine della configurazione chiamando il metodo AddJsonFile.

// Existing code in Program.cs
// ... ...

// Add a JSON configuration source 
builder.Configuration.AddJsonFile("config/mysettings.json", reloadOnChange: true, optional: false);

var app = builder.Build();

// The rest of existing code in program.cs
// ... ...

Distribuire l'applicazione in un contenitore

Eseguire il comando dotnet publish per compilare l'app in modalità versione e creare gli asset nella directory pubblicata.
```
dotnet publish -c Release -o published
```
Creare un file denominato Dockerfile nella radice della directory del progetto, aprirlo in un editor di testo e immettere il contenuto seguente. Un Dockerfile è un file di testo che non ha un'estensione e che viene usato per creare un'immagine del contenitore.
```
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]
```
Creare un'immagine del contenitore denominata aspnetapp eseguendo il comando seguente.
```
docker build --tag aspnetapp .
```

Eseguire il push delle immagini in Registro Azure Container

Usare quindi il comando az acr login per accedere al registro contenitori. Nell'esempio seguente si accede a un registro denominato myregistry. Sostituire il nome del registro con il proprio nome.
```
az acr login --name myregistry
```
Il comando restituisce Login Succeeded una volta eseguito l'accesso.
Usare il comando docker tag per creare un tag myregistry.azurecr.io/aspnetapp:v1 per l'immagine aspnetapp.
```
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
```
Suggerimento

Per esaminare l'elenco delle immagini e dei tag Docker esistenti, eseguire docker image ls. In questo scenario dovrebbero essere visualizzate almeno due immagini: aspnetapp e myregistry.azurecr.io/aspnetapp.
Usare ora il comando docker push per caricare l'immagine nel registro. Ad esempio, il comando seguente esegue il push dell'immagine in un repository denominato aspnetapp con il tag v1 nel registro myregistry.
```
docker push myregistry.azurecr.io/aspnetapp:v1
```

Distribuire l'applicazione

Creare una directory Deployment nella directory radice del progetto.

Aggiungere un file deployment.yaml alla directory Deployment con il contenuto seguente per creare una distribuzione. Sostituire il valore di template.spec.containers.image con l'immagine creata nel passaggio precedente.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80

Aggiungere un file service.yaml alla directory Deployment con il contenuto seguente per creare un servizio LoadBalancer.

apiVersion: v1
kind: Service
metadata:
  name: aspnetapp-demo-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: aspnetapp-demo

Eseguire il comando seguente per distribuire l'applicazione nel cluster del servizio Azure Kubernetes.
```
kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo
```
Eseguire il comando seguente e ottenere l'indirizzo IP esterno esposto dal servizio LoadBalancer.
```
kubectl get service aspnetapp-demo-service -n appconfig-demo
```
Aprire una finestra del browser e passare all'indirizzo IP ottenuto nel passaggio precedente. La pagina Web avrà un aspetto simile al seguente:

Usare il provider Kubernetes Configurazione app

Ora che è disponibile un'applicazione in esecuzione nel servizio Azure Kubernetes, si distribuirà il provider Kubernetes Configurazione app nel cluster del servizio Azure Kubernetes in esecuzione come controller Kubernetes. Il provider recupera i dati dall'archivio di Configurazione app e crea un oggetto ConfigMap, utilizzabile come file JSON montato in un volume di dati.

Configurare l'archivio di Configurazione app di Azure

Aggiungere le coppie chiave-valore seguenti all'archivio di Configurazione app e lasciare i valori predefiniti per Etichetta e Tipo di contenuto. Per altre informazioni su come aggiungere valori chiave a un archivio usando il portale di Azure o l’interfaccia della riga di comando, andare a Creare un valore chiave.

Chiave	valore
Settings:FontColor	Verde
Settings:Message	Hello from Azure App Configuration

Configurare il provider Kubernetes Configurazione app

Per ottenere le credenziali di accesso per il cluster del servizio Azure Kubernetes, eseguire il comando seguente. Sostituire il valore dei parametri name e resource-group con l'istanza del servizio Azure Kubernetes:
```
az aks get-credentials --name <your-aks-instance-name> --resource-group <your-aks-resource-group>
```
Installare il provider Kubernetes Configurazione app di Azure nel cluster del servizio Azure Kubernetes usando helm:
```
helm install azureappconfiguration.kubernetesprovider \
     oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
     --namespace azappconfig-system \
     --create-namespace
```
Suggerimento

Il provider Kubernetes Configurazione app è disponibile anche come estensione del servizio Azure Kubernetes. Questa integrazione consente l'installazione e la gestione semplificate tramite l'interfaccia della riga di comando di Azure, i modelli di ARM o i modelli di Bicep. L'uso dell'estensione per il servizio Azure Kubernetes facilita gli aggiornamenti automatici delle versioni secondarie/patch, assicurandosi che il sistema sia sempre aggiornato. Per istruzioni dettagliate sull'installazione, vedere Estensione Configurazione app di Azure per il servizio Azure Kubernetes.
Aggiungere un file appConfigurationProvider.yaml alla directory Deployment con il contenuto seguente per creare una risorsa AzureAppConfigurationProvider. AzureAppConfigurationProvider è una risorsa personalizzata che definisce i dati da scaricare da un archivio di Configurazione app di Azure e crea un oggetto ConfigMap.
```
apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData: 
      type: json
      key: mysettings.json
  auth:
    workloadIdentity:
      serviceAccountName: <your-service-account-name>
```
Sostituire il valore del campo endpoint con l'endpoint dell'archivio di Configurazione app di Azure. Passare al passaggio successivo per aggiornare la sezioneauth con le informazioni di autenticazione.
Nota

AzureAppConfigurationProvider è un oggetto API dichiarativo. Definisce lo stato desiderato di ConfigMap creato dai dati nell'archivio di Configurazione app con il comportamento seguente:
- L'oggetto ConfigMap non verrà creato se un oggetto ConfigMap con lo stesso nome esiste già nello stesso spazio dei nomi.
- L'oggetto ConfigMap verrà reimpostato in base ai dati presenti nell'archivio di Configurazione app se vengono eliminati o modificati in altro modo.
- L'oggetto ConfigMap verrà eliminato se il provider Kubernetes Configurazione app viene disinstallato.
Seguire le istruzioni per usare l'identità del carico di lavoro per l'autenticazione con l'archivio di Configurazione app. Aggiornare il file appConfigurationProvider.yaml sostituendo il campo serviceAccountName con il nome dell'account del servizio creato. Per altre informazioni su altri metodi di autenticazione, vedere gli esempi nella sezione Autenticazione.

Aggiornare il file deployment.yaml nella directory Deployment per usare l'oggetto ConfigMap configmap-created-by-appconfig-provider come volume di dati montato. È importante assicurarsi che il percorso volumeMounts.mountPath corrisponda al percorso WORKDIR specificato nel Dockerfile e alla directory config creata in precedenza.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /app/config
      volumes:
      - name: config-volume 
        configMap: 
          name: configmap-created-by-appconfig-provider

Eseguire il comando seguente per distribuire le modifiche. Sostituire lo spazio dei nomi se si usa l'applicazione del servizio Azure Kubernetes esistente.
```
kubectl apply -f ./Deployment -n appconfig-demo
```
Aggiornare il browser. La pagina mostra il contenuto aggiornato.

Risoluzione dei problemi

Se l'applicazione non recupera i dati dall'archivio di Configurazione app, eseguire il comando seguente per verificare che l'oggetto ConfigMap sia stato creato correttamente.

kubectl get configmap configmap-created-by-appconfig-provider -n appconfig-demo

Se l'oggetto ConfigMap non è stato creato, eseguire il comando seguente per ottenere lo stato di recupero dei dati.

kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

Se il provider Kubernetes Configurazione app di Azure ha recuperato correttamente i dati dall'archivio di Configurazione app, la proprietà phase nella sezione stato dell'output sarà COMPLETE, come illustrato nell'esempio seguente.

$ kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
  ... ... ...
status:
  lastReconcileTime: "2023-04-06T06:17:06Z"
  lastSyncTime: "2023-04-06T06:17:06Z"
  message: Complete sync settings to ConfigMap or Secret
  phase: COMPLETE

Se non è COMPLETE, i dati non vengono scaricati correttamente dall'archivio di Configurazione app. Eseguire il comando seguente per visualizzare i log del provider Kubernetes Configurazione app di Azure.

kubectl logs deployment/az-appconfig-k8s-provider -n azappconfig-system

Usare i log per ulteriori informazioni sulla risoluzione dei problemi. Per informazioni sui problemi comuni, vedere la sezione Domande frequenti.

Domande frequenti

Perché non viene generato ConfigMap o Segreto?

È possibile seguire la procedura descritta nella guida Risoluzione dei problemi per raccogliere i log per informazioni dettagliate sull'errore. Ecco alcune cause comuni.

RISPOSTA 403: 403 Accesso negato: l'identità configurata non dispone delle autorizzazioni necessarie per accedere all'archivio di Configurazione app. Fare riferimento alla sezione Autenticazione per esempi che corrispondono all'identità in uso.
Un riferimento Key Vault è disponibile in Configurazione app, ma 'spec.secret' non è stato configurato: uno o più riferimenti Key Vault sono inclusi nei valori chiave selezionati, ma le informazioni di autenticazione per Key Vault non vengono fornite. Per mantenere l'integrità della configurazione, l'intera configurazione non viene caricata. Configurare la sezione spec.secret per fornire le informazioni di autenticazione necessarie. Per esempi e altre informazioni, vedere Informazioni di riferimento di Key Vault.

Perché ConfigMap generato non contiene i dati previsti?

Assicurarsi di specificare i selettori chiave-valore corretti in modo che corrispondano ai dati previsti. Se non vengono specificati selettori, tutti i valori chiave senza etichetta verranno scaricati dall'archivio di Configurazione app. Quando si usa un filtro chiave, verificare che corrisponda al prefisso dei valori di chiave previsti. Se i valori chiave hanno etichette, assicurarsi di specificare il filtro etichetta nei selettori. Per altri esempi, vedere la documentazione sulla selezione chiave-valore.

Come è possibile personalizzare l'installazione del provider Kubernetes di Configurazione app di Azure?

È possibile personalizzare l'installazione fornendo valori Helm aggiuntivi durante l'installazione del provider Kubernetes di Configurazione app di Azure. Ad esempio, è possibile impostare il livello di log, configurare il provider per l'esecuzione in un nodo specifico o disabilitare l'identità del carico di lavoro. Per altre informazioni, vedere la guida all'installazione.

Perché non è possibile eseguire l'autenticazione con Configurazione app di Azure usando l'identità del carico di lavoro dopo l'aggiornamento del provider alla versione 2.0.0?

A partire dalla versione 2.0.0, è necessario un account del servizio fornito dall'utente per l'autenticazione con Configurazione app di Azure usando l'identità del carico di lavoro. Questa modifica migliora la sicurezza tramite l'isolamento dello spazio dei nomi. In precedenza, per tutti gli spazi dei nomi è stato usato un account del servizio del provider Kubernetes. Per istruzioni aggiornate, vedere la documentazione sull'uso dell'identità del carico di lavoro. Se è necessario eseguire la migrazione quando si esegue l'aggiornamento alla versione 2.0.0, è possibile impostare workloadIdentity.globalServiceAccountEnabled=true temporaneamente durante l'installazione del provider. Si noti che il supporto per l'uso dell'account del servizio del provider sarà deprecato in una versione futura.

Pulire le risorse

Disinstallare il provider Kubernetes Configurazione app dal cluster del servizio Azure Kubernetes se si vuole mantenere il cluster del servizio Azure Kubernetes.

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

Se non si vuole continuare a usare le risorse create in questo articolo, eliminare il gruppo di risorse creato qui per evitare addebiti.

Importante

L'eliminazione di un gruppo di risorse è irreversibile. Il gruppo di risorse e tutte le risorse in esso contenute vengono eliminati in modo permanente. Assicurarsi di non eliminare accidentalmente il gruppo di risorse o le risorse sbagliate. Se le risorse per questo articolo sono state create in un gruppo di risorse che contiene altre risorse che si vogliono mantenere, eliminare ogni risorsa singolarmente dal rispettivo riquadro anziché eliminare il gruppo di risorse.

Accedere al portale di Azure e selezionare Gruppi di risorse.
Nella casella Filtra per nome immettere il nome del gruppo di risorse.
Nell'elenco dei risultati selezionare il nome del gruppo di risorse per visualizzare una panoramica.
Selezionare Elimina gruppo di risorse.
Verrà chiesto di confermare l'eliminazione del gruppo di risorse. Immettere il nome del gruppo di risorse per confermare e selezionare Elimina.

Dopo qualche istante, il gruppo di risorse e tutte le risorse che contiene vengono eliminati.

Nota

Se si usa Azure Developer CLI per configurare le risorse, è possibile eseguire il comando azd down per eliminare tutte le risorse create dal modello di azure-appconfig-aks.

Passaggi successivi

Questa guida introduttiva spiega come:

È stata creata un'applicazione in esecuzione nel servizio Azure Kubernetes.
Il cluster del servizio Azure Kubernetes è stato connesso all'archivio di Configurazione app usando il provider Kubernetes Configurazione app.
È stato creato un oggetto ConfigMap con i dati dall'archivio di Configurazione app.
L'applicazione è stata eseguita con la configurazione dall'archivio di Configurazione app senza modificare il codice dell'applicazione.

Per informazioni su come configurare i carichi di lavoro del servizio Azure Kubernetes per aggiornare la configurazione in modo dinamico, continuare con l'esercitazione successiva.

Usare la configurazione dinamica nel servizio Azure Kubernetes

Per altre informazioni sul provider Kubernetes Configurazione app di Azure, vedere Informazioni di riferimento sul provider Kubernetes Configurazione app di Azure.

Condividi tramite