Condividi tramite

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

In Kubernetes è possibile configurare i pod per l'utilizzo dei dati di configurazione da ConfigMaps. 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 costruire mappe e segreti di Kubernetes da riferimenti chiave-valore e Insieme di credenziali delle chiavi di Azure archiviati in Configurazione app. 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 incorpora il provider Kubernetes di Configurazione app di Azure nel carico di lavoro del servizio Azure Kubernetes. Il provider crea un oggetto ConfigMap dai dati nell'archivio di Configurazione app. 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 a Configurazione app da un carico di lavoro ospitato in Kubernetes, vedere Accesso al servizio Azure Kubernetes a Configurazione app.

Nota

Questa guida introduttiva illustra come configurare il 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 in esecuzione nel servizio Azure Kubernetes

In questa sezione viene creata un'applicazione Web di base ASP.NET Core eseguita nel servizio Azure Kubernetes. 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 servizio Azure Kubernetes che legge la configurazione da un file, è possibile ignorare questa sezione e passare a Usare il provider Kubernetes di Configurazione app di Azure. 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 un filemysettings.json che contiene il contenuto seguente:

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

  4. Nella directory radice del progetto aprire Program.cs e quindi aggiungere il file JSON all'origine di configurazione chiamando il AddJsonFile metodo .

    // 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
// ... ...

Distribuire l'applicazione in un contenitore

  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 .

Eseguire il push dell'immagine in Registro Container

  1. Per accedere al registro contenitori, eseguire il comando az acr login . Il codice seguente accede a un registro denominato myregistry. Sostituire il nome del Registro di sistema con il nome del Registro di sistema.

    az acr login --name myregistry

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

  2. Per creare un tag chiamato myregistry.azurecr.io/aspnetapp:v1 per l'immagine aspnetapp , usare il comando docker tag . Sostituire myregistry con il nome del Registro di sistema.

    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, l'output deve elencare almeno due immagini: aspnetapp e myregistry.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 myregistry:

    docker push myregistry.azurecr.io/aspnetapp:v1

Distribuire l'applicazione

  1. Creare una directory Deployment nella directory radice del 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: myregistry.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 per il cluster del servizio Azure Kubernetes e le unisce nel contesto del cluster.

    az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>

  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

Dopo aver eseguito un'applicazione nel servizio Azure Kubernetes, il passaggio successivo consiste nel distribuire il provider Kubernetes di Configurazione app di Azure nel cluster del servizio Azure Kubernetes per l'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

Aggiungere le chiavi e i valori seguenti all'archivio di Configurazione app. 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 Azure App Configuration

Configurare il provider Kubernetes di Configurazione app di Azure

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

    Aggiungere all'estensione dell'interfaccia k8s-extension della riga di comando di Azure.

    az extension add --name k8s-extension

    Registrare il KubernetesConfiguration provider di risorse.

    az provider register --namespace Microsoft.KubernetesConfiguration

    Installare l'estensione del servizio Azure Kubernetes per Configurazione app. Sostituire i valori dei cluster-name parametri e resource-group con i valori corrispondenti dell'istanza del servizio Azure Kubernetes. Per impostazione predefinita, il provider viene installato nello spazio dei azappconfig-system nomi .

    az k8s-extension create --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider \
    --extension-type Microsoft.AppConfiguration

    Per altre informazioni, vedere Installare l'estensione del servizio Azure Kubernetes 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 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 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.
    • ConfigMap viene reimpostato in base ai dati presenti nell'archivio di Configurazione app, se vengono eliminati o modificati da qualsiasi altro mezzo.
    • ConfigMap viene eliminato se il provider Kubernetes di Configurazione app di Azure viene disinstallato.

  3. Per eseguire l'autenticazione con l'archivio di Configurazione app, 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: 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

  5. Per distribuire le modifiche, eseguire il comando seguente. Aggiornare lo spazio dei nomi se si usa l'applicazione del servizio Azure Kubernetes 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 Azure App Configuration.

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, la phase proprietà nella status sezione dell'output deve 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 Configurazione app. 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 è possibile personalizzare l'installazione del provider Kubernetes di 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 Kubernetes aggiorna quindi ConfigMap e Secret con i dati più recenti dell'archivio di Configurazione app e dell'insieme di credenziali delle chiavi. 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 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 usare temporaneamente l'impostazione durante l'installazione workloadIdentity.globalServiceAccountEnabled=true del provider. Si noti che il supporto per l'uso dell'account del servizio del provider è pianificato per la deprecazione in una versione futura.

Pulire le risorse

Se si vuole disinstallare il provider Kubernetes di Configurazione app di Azure ma mantenere il cluster del servizio Azure Kubernetes, usare il comando seguente per disinstallare il provider:

az k8s-extension delete --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --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

Questa guida introduttiva spiega come:

  • Creazione di un'applicazione in esecuzione nel servizio Azure Kubernetes.
  • Connettere il cluster del servizio Azure Kubernetes all'archivio di Configurazione app usando il provider Kubernetes di Configurazione app di Azure.
  • È stato creato un oggetto ConfigMap con i dati dall'archivio di Configurazione app.
  • Eseguire l'applicazione con i dati di configurazione dall'archivio di Configurazione app senza modificare il codice dell'applicazione.

Per informazioni su come aggiornare i carichi di lavoro del servizio Azure Kubernetes per aggiornare dinamicamente i dati di configurazione, continuare con l'esercitazione successiva.

Usare la configurazione dinamica nel servizio Azure Kubernetes

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

  • Last updated on