Snabbstart: Använda Azure App Configuration i Azure Kubernetes Service

I Kubernetes kan du konfigurera poddar för att använda konfigurationsdata från ConfigMaps. Den här metoden förbättrar portabiliteten för dina program eftersom du kan frikoppla konfigurationsdata från dina containeravbildningar.

Azure App Configuration Kubernetes-providern erbjuder ett sätt att konstruera Kubernetes ConfigMaps och hemligheter från nyckelvärden och Azure Key Vault-referenser som lagras i App Configuration. När du använder den här providern kan du använda App Configuration för att lagra och hantera dina konfigurationsdata centralt utan att göra ändringar i programkoden.

En ConfigMap kan användas som miljövariabler eller som en monterad fil. I den här snabbstarten införlivar du Azure App Configuration Kubernetes-providern i din AKS-arbetsbelastning. Providern skapar en ConfigMap från data i appkonfigurationsarkivet. I arbetsbelastningen kör du en grundläggande ASP.NET Core-app i en podd som använder ConfigMap som en JSON-fil monterad på en datavolym.

azd init -t azure-appconfig-aks
azd up

Förutsättningar

• En konfigurationsbutik för appar. Skapa en butik.
• En instans av Azure Container Registry. Skapa ett register.
• Ett AKS-kluster som har behörighet att hämta avbildningar från containerregistret. Skapa ett AKS-kluster.
• .NET SDK 8.0 eller senare.
• Azure CLI.
• Docker Desktop.
• Helm.
• kubectl.

Skapa ett program som körs i AKS

I det här avsnittet skapar du en grundläggande ASP.NET Core-webbapp som körs i AKS. Programmet läser konfigurationsdata från en lokal JSON-fil. I nästa avsnitt gör du det möjligt för programmet att använda konfigurationsdata från App Configuration utan att ändra programkoden.

Om du redan har ett AKS-program som läser konfigurationen från en fil kan du hoppa över det här avsnittet och gå till Använda Azure App Configuration Kubernetes-providern. Om du hoppar över det här avsnittet kontrollerar du att konfigurationsfilen som providern genererar matchar den filsökväg som programmet använder.

Skapa ett program

1. Använd .NET-kommandoradsgränssnittet (CLI) för att köra följande kommando. Det skapar ett ASP.NET Core-webbappsprojekt i en ny MyWebApp-katalog .

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

2. I katalogen MyWebApp går du till katalogen Pages och öppnar sedan Index.cshtml. Ersätt innehållet med följande kod:

   @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. Skapa en konfigurationskatalog i projektets rot. I konfigurationskatalogen lägger du till en mysettings.json fil som innehåller följande innehåll:

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

4. Öppna Program.cs i projektrotkatalogen och lägg sedan till JSON-filen i konfigurationskällan genom att anropa AddJsonFile metoden.

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

Containerisera applikationen

1. Kör kommandot dotnet publish för att skapa appen i versionsläge och skapa tillgångarna i den publicerade katalogen.

   dotnet publish -c Release -o published
   

2. Skapa en fil med namnet Dockerfile i roten av projektkatalogen, öppna den i en textredigerare och ange följande innehåll. En Dockerfile är en textfil som inte har något tillägg. Du använder den för att skapa en containeravbildning.

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

3. Skapa en containeravbildning med namnet aspnetapp genom att köra följande kommando:

   docker build --tag aspnetapp .
   

Skicka avbildningen till Container Registry

1. Om du vill logga in på containerregistret kör du kommandot az acr login . Följande kod loggar in i ett register med namnet myregistry. Ersätt registernamnet med namnet på registret.

   az acr login --name myregistry
   

   Kommandot returnerar Login Succeeded om du har loggat in.

2. Om du vill skapa en tagg med namnet myregistry.azurecr.io/aspnetapp:v1 på avbildningen aspnetapp använder du docker-taggkommandot . Ersätt myregistry med namnet på registret.

   docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
   

   Tips/Råd

   Om du vill granska listan över dina befintliga Docker-avbildningar och taggar kör du docker image ls. I det här scenariot bör utdata visa minst två bilder: aspnetapp och myregistry.azurecr.io/aspnetapp.

3. Om du vill ladda upp avbildningen till containerregistret använder du docker push-kommandot . Följande kommando skickar till exempel avbildningen till en lagringsplats med namnet aspnetapp med taggen v1 under registret myregistry:

   docker push myregistry.azurecr.io/aspnetapp:v1
   

Distribuera programmet

1. Skapa en distributionskatalog i rotkatalogen för projektet.

2. Om du vill definiera en distribution lägger du till en deployment.yaml-fil med följande innehåll i distributionskatalogen . Ersätt värdet template.spec.containers.image för med taggen som du skapade i föregående avsnitt.

   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. Om du vill definiera en LoadBalancer tjänst lägger du till en service.yaml-fil med följande innehåll i distributionskatalogen :

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

4. Kör följande kommando för att göra det möjligt för kubectl att ansluta till ditt AKS-kluster. Den laddar ned autentiseringsuppgifterna för ditt AKS-kluster och sammanfogar dem i kontexten för klustret.

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

5. Om du vill distribuera programmet till AKS-klustret och skapa resurserna kör du följande kommandon:

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

6. Kör följande kommando för att hämta den externa IP-adressen som exponeras av LoadBalancer tjänsten:

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

7. I ett webbläsarfönster går du till den IP-adress som du fick i föregående steg. Webbsidan bör se ut ungefär så här:

   

Använda Kubernetes-provider för Azure App Configuration

Nu när du har ett program som körs i AKS är nästa steg att distribuera Azure App Configuration Kubernetes Provider till AKS-klustret för att köras som en Kubernetes-kontrollant. Providern hämtar data från appkonfigurationsarkivet och skapar en ConfigMap som kan användas som en JSON-fil monterad i en datavolym.

Konfigurera App Configuration Store

Lägg till följande nycklar och värden i App Configuration Store. För var och en använder du standardvärden för Etikett och Innehållstyp. Mer information om hur du lägger till nyckelvärden i ett arkiv med hjälp av Azure-portalen eller Azure CLI finns i Skapa ett nyckelvärde.

Konfigurera Kubernetes-provider för Azure App Configuration

1. Installera Kubernetes-providern för Azure App Configuration i ditt AKS-kluster. Du kan installera providern antingen som ett AKS-tillägg eller med hjälp av ett Helm-diagram. AKS-tillägget tillhandahåller sömlös installation och hantering via Azure CLI, Azure Resource Manager-mallar (ARM-mallar) eller Bicep-filer. Dessutom underlättar användningen av AKS-tillägget automatiska uppdateringar av mindre versioner och korrigeringsversioner, vilket hjälper till att säkerställa att systemet förblir uppdaterat.

   • AKS-tillägg
   • Helm-diagram

   k8s-extension Lägg till i dina Azure CLI-tillägg.

   az extension add --name k8s-extension
   

   KubernetesConfiguration Registrera resursprovidern.

   az provider register --namespace Microsoft.KubernetesConfiguration
   

   Installera AKS-tillägget för App Configuration. Ersätt parametervärdena cluster-name och resource-group med motsvarande värden från din AKS-instans. Som standard installeras providern i azappconfig-system namnområdet.

   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
   

   Mer information finns i Installera AZURE App Configuration AKS-tillägget.

2. Om du vill definiera en AzureAppConfigurationProvider resurs lägger du till en appConfigurationProvider.yaml-fil med följande innehåll i distributionskatalogen . AzureAppConfigurationProvider är en anpassad resurs. Den definierar de data som ska laddas ned från ett appkonfigurationsarkiv. Den skapar också en 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>
   

   Ersätt värdet för endpoint fältet med slutpunkten för ditt Azure App Configuration Store. Gå vidare till nästa steg för att uppdatera auth avsnittet med din autentiseringsinformation.

   Anmärkning

   AzureAppConfigurationProvider är ett deklarativt API-objekt. Den definierar önskat tillstånd för den ConfigMap som skapas från data i appkonfigurationsarkivet. Definitionen av önskat tillstånd anger följande beteende:

   • Det går inte att skapa ConfigMap om det redan finns en ConfigMap med samma namn i samma namnområde.
   • ConfigMap återställs baserat på aktuella data i appkonfigurationsarkivet om det tas bort eller ändras på något annat sätt.
   • ConfigMap tas bort om Kubernetes-providern för Azure App Configuration avinstalleras.

3. Om du vill autentisera med appkonfigurationsarkivet följer du anvisningarna för att använda arbetsbelastningsidentiteten. Uppdatera filen appConfigurationProvider.yaml genom att serviceAccountName ersätta fältet med namnet på det tjänstkonto som du skapar när du följer anvisningarna. Mer information om andra autentiseringsmetoder finns i exemplen i Autentisering.

4. Som du ser i följande kod uppdaterar du filen deployment.yaml i distributionskatalogen för att använda ConfigMap configmap-created-by-appconfig-provider som en monterad datavolym. Det är viktigt att volumeMounts.mountPath värdet matchar värdet WORKDIR som angavs i din Dockerfile och konfigurationskatalogen som du skapade tidigare. Kontrollera också att värdet template.spec.containers.image för matchar namnet på den avbildning som du skapade tidigare.

   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. Om du vill distribuera ändringarna kör du följande kommando. Uppdatera namnområdet om du använder ditt befintliga AKS-program.

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

6. Uppdatera webbläsaren. Sidan visar uppdaterat innehåll.

   

Felsökning

Om programmet inte läser data från appkonfigurationsarkivet kör du följande kommando för att kontrollera att ConfigMap har skapats korrekt:

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

Om ConfigMap inte har skapats kör du följande kommando för att hämta datahämtningsstatusen:

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

Om Kubernetes-providern för Azure App Configuration hämtar data från appkonfigurationsarkivet phase ska egenskapen i status utdataavsnittet vara Complete, enligt följande exempel:

$ 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

Om fasegenskapen inte COMPLETEär hämtas inte data från appkonfigurationsarkivet korrekt. Kör följande kommando för att komma åt loggarna för Azure App Configuration Kubernetes-providern:

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

Använd loggarna för ytterligare felsökning. Lösningar på vanliga problem finns i Vanliga frågor och svar.

Vanliga frågor

Varför genereras inte ConfigMap eller hemligheten?

Om du vill samla in loggar som innehåller detaljerad felinformation följer du stegen i Felsökning. Här är några vanliga orsaker till det här problemet:

• SVAR 403: 403 Förbjudet: Den konfigurerade identiteten saknar de behörigheter som krävs för att få åtkomst till App Configuration Store. Exempel som matchar den identitet du använder finns i Autentisering.
• En Key Vault-referens finns i App Configuration, men "spec.secret" har inte konfigurerats: En eller flera Key Vault-referenser ingår i de valda nyckelvärdena, men autentiseringsinformationen för Key Vault tillhandahålls inte. För att bevara konfigurationens integritet misslyckas hela konfigurationen med att laddas in. Konfigurera avsnittet spec.secret för att tillhandahålla nödvändig autentiseringsinformation. Exempel och mer information finns i Key Vault-referenser .

Varför innehåller inte den genererade ConfigMap förväntade data?

Kontrollera att nyckel/värde-väljare som du anger matchar förväntade data. Om du inte anger några väljare hämtas alla nyckelvärden utan en etikett från appkonfigurationsarkivet. När du använder ett nyckelfilter kontrollerar du att det matchar prefixet för dina förväntade nyckelvärden. Om dina nyckelvärden har etiketter måste du ange etikettfiltret i väljarna. Fler exempel finns i Val av nyckelvärde.

Hur kan jag anpassa installationen av Kubernetes-providern för Azure App Configuration?

Du kan anpassa installationen genom att ange extra Helm-värden när du installerar Kubernetes-providern för Azure App Configuration. Du kan till exempel ange loggnivån, konfigurera providern så att den körs på en specifik nod eller inaktivera arbetsbelastningsidentiteten. Mer information finns i Installation.

Hur utlöser jag en uppdatering på begäran av ConfigMap och Hemlighet?

Du kan konfigurera data så att de uppdateras automatiskt. Men det finns tillfällen då du kanske vill utlösa en uppdatering på begäran för att hämta de senaste data från App Configuration och Key Vault. Om du vill utlösa en uppdatering kan du ändra avsnittet i metadata.annotationsAzureAppConfigurationProvider. Kubernetes-providern uppdaterar sedan ConfigMap och Secret med de senaste data från ditt App Configuration Store och Key Vault. Ett exempel finns i Uppdatering på begäran.

Vi rekommenderar inte att du tar bort eller ändrar ConfigMap och Secret som genereras av Kubernetes-providern. Nya genereras från de senaste data, men den här situationen kan orsaka stilleståndstid för dina program vid fel.

Varför kan jag inte autentisera med App Configuration med hjälp av arbetsbelastningsidentitet efter uppgradering av providern till version 2.0.0?

Från och med version 2.0.0 krävs ett tjänstkonto som tillhandahålls av användaren för autentisering med App Configuration med hjälp av arbetsbelastningsidentitet. Den här ändringen förbättrar säkerheten genom namnområdesisolering. Tidigare användes en Kubernetes-providerns tjänstkonto för alla namnområden. Uppdaterade instruktioner finns i dokumentationen om hur du använder arbetsbelastningsidentitet. Om du behöver tid att migrera när du uppgraderar till version 2.0.0 kan du tillfälligt använda inställningen under providerinstallationen workloadIdentity.globalServiceAccountEnabled=true . Observera att stöd för att använda providerns tjänstkonto är schemalagt för utfasning i en framtida version.

Rensa resurser

Om du vill avinstallera Azure App Configuration Kubernetes-providern men behålla AKS-klustret använder du följande kommando för att avinstallera providern:

az k8s-extension delete --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

Om du inte vill fortsätta använda resurserna som skapas i den här artikeln tar du bort resursgruppen som du skapade här för att undvika avgifter.

1. Logga in på Azure Portal och välj Resursgrupper.
2. I rutan Filtrera efter namn anger du namnet på resursgruppen.
3. I resultatlistan väljer du resursgruppens namn för att se en översikt.
4. Välj Ta bort resursgrupp.
5. Du blir ombedd att bekräfta borttagningen av resursgruppen. Ange namnet på resursgruppen för att bekräfta och välj Ta bort.

Efter en liten stund tas resursgruppen och alla dess resurser bort.

Nästa steg

I den här snabbstarten kommer du att göra följande:

• Skapade ett program som körs i AKS.
• Anslut aks-klustret till appkonfigurationsarkivet med hjälp av Azure App Configuration Kubernetes-providern.
• Skapade en ConfigMap med data från din Appkonfigurationsbutik.
• Körde programmet med konfigurationsdata från appkonfigurationsarkivet utan att ändra programkoden.

Om du vill ta reda på hur du uppdaterar dina AKS-arbetsbelastningar för att dynamiskt uppdatera konfigurationsdata fortsätter du till nästa självstudie.

Mer information om Kubernetes-providern för Azure App Configuration finns i Referens för Azure App Configuration Kubernetes Provider.