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

In Kubernetes è possibile configurare i pod in modo che utilizzino i dati di configurazione delle ConfigMap. Questa procedura migliora la portabilità delle applicazioni, perché è possibile separare i dati di configurazione dalle immagini del contenitore.

Il provider Kubernetes di Configurazione app di Azure offre un modo per creare ConfigMap e Secret di Kubernetes a partire da coppie chiave-valore e riferimenti ad Azure Key Vault archiviati in App Configuration. Quando si usa questo provider, è possibile usare Configurazione app per archiviare e gestire centralmente i dati di 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 integra Configurazione app di Azure Kubernetes Provider nel carico di lavoro AKS. Il provider crea una ConfigMap a partire dai dati presenti nell'archivio App Configuration. Nel carico di lavoro si esegue un'app di base ASP.NET Core in un pod che usa ConfigMap come file JSON montato in un volume di dati.

Suggerimento

Per altri modi per accedere ad App Configuration da un carico di lavoro ospitato in Kubernetes, vedere Accesso ad App Configuration da servizio Azure Kubernetes.

Nota

Questa guida di avvio rapido guida l'utente nella configurazione del provider Kubernetes di Configurazione app di Azure. Facoltativamente, è possibile usare i comandi seguenti dell'interfaccia della riga di comando per sviluppatori di Azure per effettuare il provisioning delle risorse di Azure e distribuire l'applicazione di esempio usata da questa guida introduttiva. Questi comandi usano il azure-appconfig-aks modello a questo scopo. Per altre informazioni su questo modello, vedere il repository GitHub azure-appconfig-aks .

azd init -t azure-appconfig-aks
azd up

Prerequisiti

Creare un'applicazione che viene eseguita in AKS

In questa sezione si crea un'applicazione Web ASP.NET Core di base che viene eseguita in AKS. L'applicazione legge i dati di configurazione da un file JSON locale. Nella sezione successiva si abilita l'applicazione a usare i dati di configurazione da Configurazione app senza modificare il codice dell'applicazione.

Se si dispone già di un'applicazione AKS che legge la configurazione da un file, è possibile ignorare questa sezione e passare a Usare Configurazione app di Azure Kubernetes Provider. Se si ignora questa sezione, verificare che il file di configurazione generato dal provider corrisponda al percorso del file usato dall'applicazione.

Creare un'applicazione

  1. Usare l'interfaccia della riga di comando di .NET per eseguire il comando seguente. Crea un progetto di app Web core ASP.NET in una nuova directory MyWebApp .

    dotnet new webapp --output MyWebApp --framework net8.0

  2. Nella directory MyWebApp passare alla directory Pages e quindi aprire Index.cshtml. Sostituire 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>

  3. Creare una directory di configurazione nella radice del progetto. Nella directory config, aggiungere il file mysettings.json contenente il seguente contenuto:

    {
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}

  4. Nella directory radice del progetto, apri Program.cs e quindi aggiungi il file JSON alle origini di 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 the existing code in Program.cs
// ... ...

Containerizza l'applicazione

  1. Per compilare l'app in modalità di rilascio e creare gli asset nella directory pubblicata , eseguire il comando dotnet publish .

    dotnet publish -c Release -o published

  2. 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. Viene usato per creare un'immagine del contenitore.

    FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]

  3. Compilare un'immagine del contenitore denominata aspnetapp eseguendo il comando seguente:

    docker build --tag aspnetapp .

Caricare l'immagine in Container Registry

  1. Per accedere al registro contenitori, eseguire il comando az acr login . Negli esempi seguenti sostituire <ContainerRegistryName> con il nome del registro contenitori.

    az acr login --name <ContainerRegistryName>

    Il comando restituisce Login Succeeded se l'accesso è stato eseguito correttamente.

  2. Per creare un tag chiamato <ContainerRegistryName>.azurecr.io/aspnetapp:v1 per l'immagine aspnetapp , usare il comando docker tag . Sostituisci <ContainerRegistryName> con il nome del registro.

    docker tag aspnetapp <ContainerRegistryName>.azurecr.io/aspnetapp:v1

    Suggerimento

    Per esaminare l'elenco delle immagini e dei tag Docker esistenti, eseguire docker image ls. In questo scenario, l'output deve elencare almeno due immagini: aspnetapp e <ContainerRegistryName>.azurecr.io/aspnetapp.

  3. Per caricare l'immagine nel registro contenitori, usare il comando docker push . Ad esempio, il comando seguente esegue il push dell'immagine in un repository denominato aspnetapp con tag v1 nel Registro di sistema <ContainerRegistryName>:

    docker push <ContainerRegistryName>.azurecr.io/aspnetapp:v1

Distribuire l'applicazione

  1. Creare una directory Deployment nella directory principale del tuo progetto.

  2. Per definire una distribuzione, aggiungere un file deployment.yaml con il contenuto seguente alla directory Deployment . Sostituire il valore di template.spec.containers.image con il tag creato nella sezione 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: <ContainerRegistryName>.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80

  3. Per definire un LoadBalancer servizio, aggiungere un file service.yaml con il contenuto seguente alla directory Distribuzione :

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

  4. Per consentire a kubectl di connettersi al cluster del servizio Azure Kubernetes, eseguire il comando seguente. Scarica le credenziali del cluster AKS e le unisce al contesto del cluster.

    az aks get-credentials --name <AksClusterName> --resource-group <AksResourceGroupName>

  5. Per distribuire l'applicazione nel cluster del servizio Azure Kubernetes e creare le risorse, eseguire i comandi seguenti:

    kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo

  6. Per ottenere l'indirizzo IP esterno esposto dal LoadBalancer servizio, eseguire il comando seguente:

    kubectl get service aspnetapp-demo-service -n appconfig-demo

  7. In una finestra del browser passare all'indirizzo IP ottenuto nel passaggio precedente. La pagina Web dovrebbe essere simile alla schermata seguente:

    Screenshot di un browser che mostra la pagina Web di un'app. La pagina contiene testo che indica Messaggio dalla configurazione locale.

Usare il provider Kubernetes di Configurazione app di Azure

Ora che un'applicazione è in esecuzione in AKS, il passaggio successivo consiste nel distribuire Configurazione app di Azure Kubernetes Provider nel cluster AKS affinché venga eseguito 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 App Configuration

Aggiungi le chiavi e i valori seguenti nell'archivio di App Configuration. Per ognuno di essi, usare i valori predefiniti per Label e Content Type. Per altre informazioni su come aggiungere valori chiave a un archivio usando il portale di Azure o l'interfaccia della riga di comando di Azure, vedere Creare un valore chiave.

Chiave valore
Impostazioni:FontColor Verde
Impostazioni:Messaggio Ciao da parte di Configurazione app di Azure

Configurare il provider Kubernetes di Configurazione app di Azure

  1. Installa il provider Kubernetes di Configurazione app di Azure nel tuo cluster AKS. È possibile installare il provider come estensione del servizio Azure Kubernetes o usando un grafico Helm. L'estensione di Azure Kubernetes Service (AKS) offre un'installazione e una gestione integrate tramite l'interfaccia della riga di comando di Azure (interfaccia della riga di comando di Azure), i modelli di Azure Resource Manager (modelli ARM) o i file Bicep. Inoltre, l'uso dell'estensione di AKS facilita gli aggiornamenti automatici alle versioni secondarie e alle patch, contribuendo a garantire che il sistema rimanga aggiornato.

    Aggiungi k8s-extension alle estensioni di interfaccia della riga di comando di Azure.

    az extension add --name k8s-extension

    Registra il provider di risorse KubernetesConfiguration.

    az provider register --namespace Microsoft.KubernetesConfiguration

    Installare l'estensione AKS per App Configuration. Sostituisci i valori dei parametri cluster-name e resource-group con i valori corrispondenti della tua istanza AKS. Per impostazione predefinita, il provider viene installato nel namespace azappconfig-system.

    az k8s-extension create --cluster-type managedClusters \
    --cluster-name <AksClusterName> \
    --resource-group <AksResourceGroupName> \
    --name appconfigurationkubernetesprovider \
    --extension-type Microsoft.AppConfiguration

    Per altre informazioni, vedere Installare l'estensione AKS di Configurazione app di Azure.

  2. Per definire una AzureAppConfigurationProvider risorsa, aggiungere un file appConfigurationProvider.yaml con il contenuto seguente alla directory Deployment . AzureAppConfigurationProvider è una risorsa personalizzata. Definisce i dati da scaricare da un archivio di Configurazione app. Crea anche un ConfigMap.

    apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <AppConfigurationEndpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData: 
      type: json
      key: mysettings.json
  auth:
    workloadIdentity:
      serviceAccountName: <ServiceAccountName>

    Sostituisci il valore del campo endpoint con l'endpoint del tuo archivio 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 dell'oggetto ConfigMap creato dai dati nell'archivio di Configurazione app. La definizione dello stato desiderato specifica il comportamento seguente:

    • La creazione di ConfigMap ha esito negativo se un oggetto ConfigMap con lo stesso nome esiste già nello stesso spazio dei nomi.
    • Il ConfigMap viene reimpostato in base ai dati attualmente presenti nel tuo archivio App Configuration, se viene eliminato o modificato in qualsiasi altro modo.
    • La ConfigMap viene eliminata se il Provider Kubernetes di Configurazione app di Azure viene disinstallato.

  3. Per autenticarsi con l'archivio di App Configuration, seguire le istruzioni per l'uso dell'identità del carico di lavoro. Aggiornare il file appConfigurationProvider.yaml sostituendo il serviceAccountName campo con il nome dell'account del servizio creato quando si seguono le istruzioni. Per altre informazioni su altri metodi di autenticazione, vedere gli esempi in Autenticazione.

  4. Come illustrato nel codice seguente, aggiornare il file deployment.yaml nella directory Deployment per usare ConfigMap configmap-created-by-appconfig-provider come volume di dati montato. È importante che il volumeMounts.mountPath valore corrisponda al WORKDIR valore specificato nel Dockerfile e alla directory di configurazione creata in precedenza. Assicurarsi inoltre che il valore di template.spec.containers.image corrisponda al nome dell'immagine 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: <ContainerRegistryName>.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

  5. Per distribuire le modifiche, eseguire il comando seguente. Aggiorna il namespace se usi l'applicazione AKS esistente.

    kubectl apply -f ./Deployment -n appconfig-demo

  6. Aggiornare il browser. La pagina mostra il contenuto aggiornato.

    Screenshot di un browser che mostra la pagina Web di un'app. La pagina contiene testo verde che indica Hello from Configurazione app di Azure.

Risoluzione dei problemi

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

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

Se ConfigMap non viene 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 di Configurazione app di Azure recupera correttamente i dati dall'archivio di Configurazione app di Azure, la proprietà phase nella sezione status dell'output dovrebbe essere Complete, come illustrato nell'esempio seguente:

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

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
  ... ... ...
status:
  lastReconcileTime: "2025-08-04T13:58:02Z"
  lastSyncTime: "2025-08-04T13:58:02Z"
  message: Complete sync key-values from App Configuration to target ConfigMap or
    Secret.
  phase: Complete

Se la proprietà phase non è COMPLETE, i dati non vengono scaricati correttamente dall'archivio di App Configuration. Per accedere ai log del provider Kubernetes di Configurazione app di Azure, eseguire il comando seguente:

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

Usare i log per ulteriori informazioni sulla risoluzione dei problemi. Per soluzioni ai problemi comuni, vedere Domande frequenti.

Domande frequenti

Perché non vengono generati il ConfigMap o il Secret?

Per raccogliere i log contenenti informazioni dettagliate sugli errori, seguire la procedura descritta in Risoluzione dei problemi. Ecco alcune cause comuni di questo problema:

  • RISPOSTA 403: 403 Accesso negato: l'identità configurata non dispone delle autorizzazioni necessarie per accedere all'archivio di Configurazione app. Per esempi che corrispondono all'identità in uso, vedere Autenticazione.
  • Un riferimento all'insieme di credenziali delle chiavi è disponibile in Configurazione app, ma 'spec.secret' non è stato configurato: uno o più riferimenti all'insieme di credenziali delle chiavi 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 Riferimenti a Key Vault .

Perché l'oggetto ConfigMap generato non contiene i dati previsti?

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

Come posso personalizzare l'installazione del provider Kubernetes per Configurazione app di Azure?

È possibile personalizzare l'installazione fornendo valori Helm aggiuntivi quando si installa il 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 Installazione.

Come è possibile attivare un aggiornamento su richiesta di ConfigMap e Secret?

È possibile configurare i dati per l'aggiornamento automatico. In alcuni casi, tuttavia, potrebbe essere necessario attivare un aggiornamento su richiesta per ottenere i dati più recenti da Configurazione app e Key Vault. Per attivare un aggiornamento, è possibile modificare la metadata.annotations sezione di AzureAppConfigurationProvider. Il provider di Kubernetes aggiorna quindi ConfigMap e Secret con i dati più aggiornati dell’App Configuration Store e di Key Vault. Per un esempio, vedere Aggiornamento su richiesta.

Non è consigliabile eliminare o modificare configmap e segreto generato dal provider Kubernetes. I nuovi dati vengono generati dai dati più recenti, ma questa situazione può causare tempi di inattività per le applicazioni durante gli errori.

Perché non è possibile eseguire l'autenticazione con Configurazione app 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 usando l'identità del carico di lavoro. Questa modifica migliora la sicurezza mediante l'isolamento del namespace. In precedenza, per tutti i namespace veniva usato l'account di servizio di un provider Kubernetes. Per istruzioni aggiornate, consulta la documentazione sull'utilizzo di Workload Identity. Se hai bisogno di tempo per eseguire la migrazione durante l'aggiornamento alla versione 2.0.0, puoi utilizzare temporaneamente l'impostazione workloadIdentity.globalServiceAccountEnabled=true durante l'installazione del provider. Si noti che il supporto all'uso dell'account di servizio del fornitore verrà deprecato in una versione futura.

Pulire le risorse

Se si desidera disinstallare il provider Kubernetes di Configurazione app di Azure ma mantenere il cluster AKS, usare il comando seguente per disinstallare il provider:

az k8s-extension delete --cluster-type managedClusters \
    --cluster-name <AksClusterName> \
    --resource-group <AksResourceGroupName> \
    --name appconfigurationkubernetesprovider

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.

  1. Accedere al portale di Azure e selezionare Gruppi di risorse.
  2. Nella casella Filtra per nome immettere il nome del gruppo di risorse.
  3. Nell'elenco dei risultati selezionare il nome del gruppo di risorse per visualizzare una panoramica.
  4. Selezionare Elimina gruppo di risorse.
  5. 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

Questo avvio rapido spiega come:

  • Ha creato un'applicazione in esecuzione in AKS.
  • Connesso il cluster AKS all'archivio di configurazione app usando Configurazione app di Azure Kubernetes Provider.
  • È stato creato un oggetto ConfigMap con i dati dall'archivio di Configurazione app.
  • Ha eseguito l'applicazione usando i dati di configurazione dell'archivio di App Configuration senza modificare il codice dell'applicazione.

Per scoprire come aggiornare i carichi di lavoro di AKS affinché i dati di configurazione vengano aggiornati dinamicamente, passare all'esercitazione successiva.

Usare la configurazione dinamica nel servizio Azure Kubernetes

Per altre informazioni su Configurazione app di Azure Kubernetes Provider, vedere la documentazione di riferimento di Configurazione app di Azure Kubernetes Provider.

  • Last updated on