Quickstart: Azure-app-configuratie gebruiken in Azure Kubernetes Service

2025-09-02

In Kubernetes kunt u pods instellen om configuratiegegevens van ConfigMaps te gebruiken. Deze procedure verbetert de draagbaarheid van uw toepassingen, omdat u configuratiegegevens kunt loskoppelen van uw containerinstallatiekopieën.

Azure App Configuration Kubernetes Provider biedt een manier om Kubernetes ConfigMaps en Geheimen te maken op basis van sleutelwaarden en Azure Key Vault-verwijzingen die zijn opgeslagen in App Configuration. Wanneer u deze provider gebruikt, kunt u App Configuration gebruiken om uw configuratiegegevens centraal op te slaan en te beheren zonder wijzigingen aan te brengen in uw toepassingscode.

Een ConfigMap kan worden gebruikt als omgevingsvariabelen of in de vorm van een gekoppeld bestand. In deze quickstart neemt u Azure App Configuration Kubernetes Provider op in uw AKS-workload. De provider maakt een ConfigMap op basis van gegevens in uw App Configuration-archief. In de workload voert u een eenvoudige ASP.NET Core-app uit in een pod die de ConfigMap gebruikt als een JSON-bestand dat is gekoppeld aan een gegevensvolume.

Aanbeveling

Voor andere manieren om toegang te krijgen tot App Configuration vanuit een workload die wordt gehost in Kubernetes, raadpleegt u Azure Kubernetes Service-toegang tot App Configuration.

Notitie

Deze quickstart begeleidt u bij het instellen van Azure App Configuration Kubernetes Provider. U kunt eventueel de volgende Azure Developer CLI-opdrachten gebruiken om Azure-resources in te richten en de voorbeeldtoepassing te implementeren die in deze quickstart wordt gebruikt. Deze opdrachten maken gebruik van de azure-appconfig-aks sjabloon voor dit doel. Zie de GitHub-opslagplaats azure-appconfig-aks voor meer informatie over deze sjabloon.

azd init -t azure-appconfig-aks
azd up

Afhankelijk van de context kan "Voorwaarden" een betere vertaling zijn voor "Prerequisites".

Een App Configuration-winkel. Een winkel maken.
Een exemplaar van Azure Container Registry. Maak een register.
Een AKS-cluster met machtigingen voor het ophalen van installatiekopieën uit uw containerregister. Maak een AKS-cluster.
.NET SDK 8.0 of hoger.
De Azure CLI.
Docker Desktop.
Helm.
kubectl.

Een toepassing maken die wordt uitgevoerd in AKS

In deze sectie maakt u een eenvoudige ASP.NET Core-webtoepassing die wordt uitgevoerd in AKS. De toepassing leest configuratiegegevens uit een lokaal JSON-bestand. In de volgende sectie schakelt u de toepassing in om configuratiegegevens uit App Configuration te gebruiken zonder de toepassingscode te wijzigen.

Als u al een AKS-toepassing hebt die de configuratie van een bestand leest, kunt u deze sectie overslaan en naar Azure App Configuration Kubernetes Provider gaan. Als u deze sectie overslaat, moet u ervoor zorgen dat het configuratiebestand dat de provider genereert overeenkomt met het bestandspad dat door uw toepassing wordt gebruikt.

Een app maken

Gebruik de .NET-opdrachtregelinterface (CLI) om de volgende opdracht uit te voeren. Er wordt een ASP.NET Core-web-app-project gemaakt in een nieuwe MyWebApp-map .
```
dotnet new webapp --output MyWebApp --framework net8.0
```

Ga in de map MyWebApp naar de map Pages en open Index.cshtml. Vervang de inhoud door de volgende code:

@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>

Maak een configuratiemap in de hoofdmap van uw project. Voeg in de configuratiemap een mysettings.json-bestand toe dat de volgende inhoud bevat:
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

Open Program.cs in de hoofdmap van uw project en voeg vervolgens het JSON-bestand toe aan de configuratiebron door de AddJsonFile methode aan te roepen.

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

De toepassing in een container plaatsen

Als u de app wilt bouwen in de releasemodus en de assets in de gepubliceerde map wilt maken, voert u de opdracht dotnet publish uit.
```
dotnet publish -c Release -o published
```
Maak een bestand met de naam Dockerfile in de hoofdmap van uw projectmap, open het in een teksteditor en voer de volgende inhoud in. Een Dockerfile is een tekstbestand dat geen extensie heeft. U gebruikt deze om een containerinstallatiekopieën te maken.
```
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]
```
Bouw een containerinstallatiekopieën met de naam aspnetapp door de volgende opdracht uit te voeren:
```
docker build --tag aspnetapp .
```

De installatiekopieën naar Container Registry pushen

Voer de opdracht az acr login uit om u aan te melden bij uw containerregister. De volgende code meldt zich aan bij een register met de naam myregistry. Vervang deze registernaam door de naam van het register.
```
az acr login --name myregistry
```
De opdracht wordt geretourneerd Login Succeeded als u zich hebt aangemeld.
Als u een tag wilt maken die wordt aangeroepen myregistry.azurecr.io/aspnetapp:v1 voor de aspnetapp installatiekopieën, gebruikt u de opdracht docker-tag . Vervang door myregistry de naam van het register.
```
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
```
Aanbeveling

Voer uit docker image lsom de lijst met bestaande Docker-installatiekopieën en -tags te bekijken. In dit scenario moet in de uitvoer ten minste twee afbeeldingen worden weergegeven: aspnetapp en myregistry.azurecr.io/aspnetapp.
Als u de installatiekopieën wilt uploaden naar het containerregister, gebruikt u de docker-pushopdracht . Met de volgende opdracht wordt de installatiekopieën bijvoorbeeld gepusht naar een opslagplaats met de naam aspnetapp tag v1 onder het register myregistry:
```
docker push myregistry.azurecr.io/aspnetapp:v1
```

De toepassing implementeren

Maak een implementatiemap in de hoofdmap van uw project.

Als u een implementatie wilt definiëren, voegt u een deployment.yaml-bestand met de volgende inhoud toe aan de implementatiemap . Vervang de waarde door template.spec.containers.image de tag die u in de vorige sectie hebt gemaakt.

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

Als u een LoadBalancer service wilt definiëren, voegt u een service.yaml-bestand toe met de volgende inhoud aan de implementatiemap :

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

Voer de volgende opdracht uit om kubectl verbinding te laten maken met uw AKS-cluster. De referenties voor uw AKS-cluster worden gedownload en samengevoegd in de context voor uw cluster.
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
Als u de toepassing wilt implementeren in het AKS-cluster en de resources wilt maken, voert u de volgende opdrachten uit:
```
kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo
```
Voer de volgende opdracht uit om het externe IP-adres weer te geven dat door de LoadBalancer service wordt weergegeven:
```
kubectl get service aspnetapp-demo-service -n appconfig-demo
```
Ga in een browservenster naar het IP-adres dat u in de vorige stap hebt verkregen. De webpagina moet er ongeveer uitzien als in de volgende schermopname:

Azure App Configuration Kubernetes-provider gebruiken

Nu u een toepassing hebt die wordt uitgevoerd in AKS, is de volgende stap het implementeren van Azure App Configuration Kubernetes Provider in uw AKS-cluster om uit te voeren als een Kubernetes-controller. De provider haalt gegevens op uit uw App Configuration-archief en maakt een ConfigMap, die kan worden gebruikt als een JSON-bestand dat is gekoppeld aan een gegevensvolume.

Het App Configuration-archief instellen

Voeg de volgende sleutels en waarden toe aan het App Configuration-archief. Gebruik voor elk label eninhoudstype standaardwaarden. Zie Een sleutelwaarde maken voor meer informatie over het toevoegen van sleutelwaarden aan een archief met behulp van Azure Portal of de Azure CLI.

Sleutel	Waarde
Instellingen:FontColor	Groen
Instellingen:Bericht	Hallo van Azure-app-configuratie

Azure App Configuration Kubernetes Provider instellen

Installeer Azure App Configuration Kubernetes Provider in uw AKS-cluster. U kunt de provider installeren als een AKS-extensie of met behulp van een Helm-grafiek. De AKS-extensie biedt naadloze installatie en beheer via de Azure CLI, Azure Resource Manager-sjablonen (ARM-sjablonen) of Bicep-bestanden. Het gebruik van de AKS-extensie faciliteert ook automatische updates voor secundaire en patchversies, zodat uw systeem up-to-date blijft.
- AKS-extensie
- Helm-grafiek
Voeg de extensie k8s-extension toe aan uw Azure CLI-extensies.
```
az extension add --name k8s-extension
```
Registreer de KubernetesConfiguration resourceprovider.
```
az provider register --namespace Microsoft.KubernetesConfiguration
```
Installeer de AKS-extensie voor App Configuration. Vervang de cluster-name waarden en resource-group parameterwaarden door de bijbehorende waarden uit uw AKS-exemplaar. De provider is standaard geïnstalleerd in de azappconfig-system naamruimte.
```
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
```
Zie Azure App Configuration AKS-extensie installeren voor meer informatie.
Voer de volgende opdracht uit om toegangsreferenties voor uw AKS-cluster op te halen. Vervang de name waarden en resource-group parameterwaarden door de bijbehorende waarden uit uw AKS-exemplaar.
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
Installeer de Helm-grafiek.
```
helm install azureappconfiguration.kubernetesprovider \
    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
    --namespace azappconfig-system \
    --create-namespace
```
Als u een AzureAppConfigurationProvider resource wilt definiëren, voegt u een bestand appConfigurationProvider.yaml toe met de volgende inhoud aan de implementatiemap . AzureAppConfigurationProvider is een aangepaste resource. Hiermee worden de gegevens gedefinieerd die moeten worden gedownload uit een App Configuration-archief. Er wordt ook een ConfigMap gemaakt.
```
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>
```
Vervang de waarde van het endpoint veld door het eindpunt van uw Azure App Configuration-opslag. Ga verder met de volgende stap om de auth sectie bij te werken met uw verificatiegegevens.
Notitie

AzureAppConfigurationProvider is een declaratief API-object. Het definieert de gewenste status van de ConfigMap die wordt gemaakt op basis van de gegevens in uw App Configuration-archief. De definitie van de gewenste status geeft het volgende gedrag op:
- Het maken van ConfigMap mislukt als er al een ConfigMap met dezelfde naam bestaat in dezelfde naamruimte.
- De ConfigMap wordt opnieuw ingesteld op basis van de huidige gegevens in uw App Configuration-archief als deze op een andere manier worden verwijderd of gewijzigd.
- De ConfigMap wordt verwijderd als De Kubernetes-provider van Azure App Configuration wordt verwijderd.
Volg de instructies voor het gebruik van de workloadidentiteit om te verifiëren met uw App Configuration-archief. Werk het bestand appConfigurationProvider.yaml bij door het serviceAccountName veld te vervangen door de naam van het serviceaccount dat u maakt wanneer u de instructies volgt. Zie de voorbeelden in Verificatie voor meer informatie over andere verificatiemethoden.

Zoals wordt weergegeven in de volgende code, werkt u het bestand deployment.yaml bij in de implementatiemap om de ConfigMap configmap-created-by-appconfig-provider te gebruiken als een gekoppeld gegevensvolume. Het is belangrijk dat de volumeMounts.mountPath waarde overeenkomt met de WORKDIR waarde die is opgegeven in uw Dockerfile en de configuratiemap die u eerder hebt gemaakt. Zorg er ook voor dat de waarde template.spec.containers.image overeenkomt met de naam van de afbeelding die u eerder hebt gemaakt.

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

Voer de volgende opdracht uit om de wijzigingen te implementeren. Werk de naamruimte bij als u uw bestaande AKS-toepassing gebruikt.
```
kubectl apply -f ./Deployment -n appconfig-demo
```
Vernieuw de browser. Op de pagina wordt bijgewerkte inhoud weergegeven.

Probleemoplossing

Als uw toepassing de gegevens uit uw App Configuration-archief niet leest, voert u de volgende opdracht uit om te controleren of de ConfigMap juist is gemaakt:

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

Als de ConfigMap niet is gemaakt, voert u de volgende opdracht uit om de status van het ophalen van gegevens op te halen:

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

Als Azure App Configuration Kubernetes Provider gegevens ophaalt uit uw App Configuration-archief, moet de phase eigenschap in de status sectie van de uitvoer worden Completeweergegeven, zoals wordt weergegeven in het volgende voorbeeld:

$ 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

Als de fase-eigenschap niet COMPLETEis, worden de gegevens niet correct gedownload uit uw App Configuration-archief. Voer de volgende opdracht uit om toegang te krijgen tot de logboeken van Azure App Configuration Kubernetes Provider:

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

Gebruik de logboeken voor verdere probleemoplossing. Zie veelgestelde vragen voor oplossingen voor veelvoorkomende problemen.

Veelgestelde vragen

Waarom wordt de ConfigMap of het geheim niet gegenereerd?

Als u logboeken wilt verzamelen die gedetailleerde foutinformatie bevatten, volgt u de stappen in Probleemoplossing. Hier volgen enkele veelvoorkomende oorzaken van dit probleem:

ANTWOORD 403: 403 Verboden: De geconfigureerde identiteit beschikt niet over de benodigde machtigingen voor toegang tot het App Configuration-archief. Zie Verificatie voor voorbeelden die overeenkomen met de identiteit die u gebruikt.
Er is een Key Vault-verwijzing gevonden in App Configuration, maar 'spec.secret' is niet geconfigureerd: een of meer Key Vault-verwijzingen zijn opgenomen in de geselecteerde sleutelwaarden, maar de verificatiegegevens voor Key Vault zijn niet opgegeven. Om de integriteit van de configuratie te behouden, kan de volledige configuratie niet worden geladen. Configureer de spec.secret sectie om de benodigde verificatiegegevens op te geven. Zie Key Vault-verwijzingen voor voorbeelden en meer informatie.

Waarom bevat de gegenereerde ConfigMap niet de verwachte gegevens?

Zorg ervoor dat de sleutel-waardekiezers die u opgeeft overeenkomen met de verwachte gegevens. Als u geen selectors opgeeft, worden alle sleutelwaarden zonder label gedownload uit uw App Configuration-archief. Wanneer u een sleutelfilter gebruikt, controleert u of het overeenkomt met het voorvoegsel van de verwachte sleutelwaarden. Als uw sleutelwaarden labels hebben, moet u het labelfilter in de selectors opgeven. Zie Sleutelwaarde selecteren voor meer voorbeelden.

Hoe kan ik de installatie van Azure App Configuration Kubernetes Provider aanpassen?

U kunt de installatie aanpassen door extra Helm-waarden op te geven wanneer u Azure App Configuration Kubernetes Provider installeert. U kunt bijvoorbeeld het logboekniveau instellen, de provider configureren voor uitvoering op een specifiek knooppunt of de workloadidentiteit uitschakelen. Zie Installatie voor meer informatie.

Hoe kan ik een on-demand vernieuwing van de ConfigMap en Secret activeren?

U kunt de gegevens zo configureren dat ze automatisch worden vernieuwd. Maar er zijn momenten waarop u een vernieuwing op aanvraag wilt activeren om de meest recente gegevens op te halen uit App Configuration en Key Vault. Als u een vernieuwing wilt activeren, kunt u de metadata.annotations sectie van AzureAppConfigurationProvider. De Kubernetes-provider werkt vervolgens de ConfigMap en Het geheim bij met de meest recente gegevens uit uw App Configuration-archief en Key Vault. Zie voor een voorbeeld vernieuwen op aanvraag.

Het is niet raadzaam om de ConfigMap en het geheim dat door de Kubernetes-provider wordt gegenereerd, te verwijderen of te wijzigen. Er worden nieuwe gegenereerd op basis van de meest recente gegevens, maar deze situatie kan leiden tot downtime voor uw toepassingen tijdens storingen.

Waarom kan ik me niet verifiëren met App Configuration met behulp van workloadidentiteit na het upgraden van de provider naar versie 2.0.0?

Vanaf versie 2.0.0 is een door de gebruiker geleverd serviceaccount vereist voor verificatie met App Configuration met behulp van workloadidentiteit. Deze wijziging verbetert de beveiliging via isolatie van naamruimten. Voorheen werd het serviceaccount van een Kubernetes-provider gebruikt voor alle naamruimten. Zie de documentatie over het gebruik van workloadidentiteit voor bijgewerkte instructies. Als u tijd nodig hebt om te migreren wanneer u een upgrade uitvoert naar versie 2.0.0, kunt u de instelling tijdelijk gebruiken tijdens de installatie van de workloadIdentity.globalServiceAccountEnabled=true provider. Houd er rekening mee dat ondersteuning voor het gebruik van het serviceaccount van de provider is gepland voor afschaffing in een toekomstige release.

Middelen opschonen

Als u Azure App Configuration Kubernetes Provider wilt verwijderen, maar uw AKS-cluster wilt behouden, gebruikt u de volgende opdracht om de provider te verwijderen:

AKS-extensie
Helm-grafiek

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

Als u de resources die in dit artikel zijn gemaakt niet wilt blijven gebruiken, verwijdert u de resourcegroep die u hier hebt gemaakt om kosten te voorkomen.

Belangrijk

Het verwijderen van een resourcegroep kan niet ongedaan worden gemaakt. De resourcegroep en alle resources daarin worden permanent verwijderd. Zorg ervoor dat u niet per ongeluk de verkeerde resourcegroep of bronnen verwijdert. Als u de resources voor dit artikel in een resourcegroep hebt gemaakt die andere resources bevat die u wilt behouden, moet u elke resource afzonderlijk verwijderen uit het deelvenster in plaats van dat u de resourcegroep verwijdert.

Meld u aan bij de Azure-portal en selecteer Resourcegroepen.
Voer de naam van de resourcegroep in het vak Filteren op naam in.
Selecteer in de resultatenlijst de resourcegroepnaam om een overzicht te bekijken.
Selecteer Resourcegroep verwijderen.
U wordt gevraagd om het verwijderen van de resourcegroep te bevestigen. Voer de naam van de resourcegroep in ter bevestiging en selecteer Verwijderen.

Na enkele ogenblikken worden de resourcegroep en alle bijbehorende resources verwijderd.

Notitie

Als u de Azure Developer CLI gebruikt om de resources in te stellen, kunt u de azd down opdracht uitvoeren om alle resources te verwijderen die door de azure-appconfig-aks sjabloon zijn gemaakt.

Volgende stappen

In deze snelstart, gaat u het volgende doen:

Er is een toepassing gemaakt die wordt uitgevoerd in AKS.
Uw AKS-cluster verbonden met uw App Configuration-archief met behulp van De Kubernetes-provider van Azure App Configuration.
Een ConfigMap is gemaakt met gegevens uit uw App Configuration-opslag.
De toepassing is uitgevoerd met configuratiegegevens uit uw App Configuration-archief zonder de toepassingscode te wijzigen.

Als u wilt zien hoe u uw AKS-workloads bijwerkt om configuratiegegevens dynamisch te vernieuwen, gaat u verder met de volgende zelfstudie.

Dynamische configuratie gebruiken in Azure Kubernetes Service

Zie de naslaginformatie over Azure App Configuration Kubernetes Provider voor meer informatie over Azure App Configuration Kubernetes Provider.

Feedback

Is deze pagina nuttig?