Schnellstart: Verwenden von Azure App Configuration in Azure Kubernetes Service
In Kubernetes richten Sie Pods ein, um die Konfiguration von ConfigMaps zu konsumieren. Dies ermöglicht Ihnen, die Konfiguration von Ihren Containerimages zu entkoppeln, sodass Ihre Anwendungen einfach portierbar sind. Der Azure App Configuration Kubernetes-Anbieter kann ConfigMaps und Geheimnisse aus Ihren Schlüsselwerten und Key Vault-Verweises in Azure App Configuration erstellen. Es ermöglicht Ihnen, Azure App Configuration für die zentrale Speicherung und Verwaltung Ihrer Konfiguration ohne Änderungen an Ihrem Anwendungscode zu nutzen.
Eine ConfigMap kann als Umgebungsvariable oder als eingebundene Datei verwendet werden. In diesem Schnellstart integrieren Sie den Azure App Configuration Kubernetes-Anbieter in eine Azure Kubernetes Service-Workload und führen dort eine einfache ASP.NET Core-App aus, die die Konfiguration aus einer JSON-Datei verarbeitet.
Tipp
Unter den Optionen für Workloads, die in Kubernetes gehostet werden, können Sie auf Azure App Configuration zugreifen.
Hinweis
Diese Schnellstartanleitung führt Sie durch das Einrichten des Azure App Configuration Kubernetes-Anbieters. Optional können Sie die folgenden Azure Developer CLI-Befehle mit der azure-appconfig-aks
-Vorlage verwenden, um Azure-Ressourcen bereitzustellen und die Beispielanwendung bereitzustellen, die von dieser Schnellstartanleitung verwendet wird. Weitere Informationen zu dieser Vorlage finden Sie im Repositoryazure-appconfig-aks in GitHub.
azd init -t azure-appconfig-aks
azd up
Voraussetzungen
- Ein App Configuration-Speicher. Erstellen Sie einen Speicher.
- Eine Azure Container Registry. Erstellen einer Registrierung.
- Ein Azure Kubernetes Service (AKS)-Cluster, dem die Berechtigung zum Pullen von Images aus Ihrer Azure Container Registry erteilt wird. Erstellen eines AKS-Clusters.
- .NET SDK 6.0 oder höher
- Azure-Befehlszeilenschnittstelle
- Docker Desktop
- Helm
- kubectl
Erstellen einer Anwendung, die in AKS ausgeführt wird
In diesem Abschnitt werden Sie eine einfache ASP.NET Core-Webanwendung erstellen, die in Azure Kubernetes Service (AKS) ausgeführt wird. Die Anwendung liest die Konfiguration aus einer lokalen JSON-Datei. Im nächsten Abschnitt werden Sie diese aktivieren, um die Konfiguration von Azure App Configuration zu konsumieren, ohne den Anwendungscode zu ändern. Wenn Sie bereits über eine AKS-Anwendung verfügen, die die Konfiguration aus einer Datei liest, können Sie diesen Abschnitt überspringen und mit Verwenden des App Configuration-Kubernetes-Anbieters fortfahren. Sie müssen nur sicherstellen, dass die vom Anbieter generierte Konfigurationsdatei mit dem in Ihrer Anwendung verwendeten Dateipfad übereinstimmt.
Erstellen einer Anwendung
Verwenden Sie die .NET-Befehlszeilenschnittstelle (CLI), und führen Sie den folgenden Befehl aus, um ein neues ASP.NET Core-Web-App-Projekt in einem neuen MyWebApp-Verzeichnis zu erstellen:
dotnet new webapp --output MyWebApp --framework net6.0
Öffnen Sie Index.cshtml im Verzeichnis Pages, und aktualisieren Sie den Inhalt mit dem folgenden 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>
Erstellen Sie ein Konfigurationsverzeichnis im Stammverzeichnis Ihres Projekts und fügen Sie dort eine Datei mysettings.json mit folgendem Inhalt hinzu.
{ "Settings": { "FontColor": "Black", "Message": "Message from the local configuration" } }
Öffnen Sie program.cs, und fügen Sie die JSON-Datei als zusätzliche Konfigurationsquelle hinzu, indem Sie die
AddJsonFile
-Methode aufrufen.// 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 // ... ...
Packen der Anwendung in Container
Führen Sie den Befehl dotnet publish aus, um die App im Releasemodus und die Ressourcen im Ordner published zu erstellen.
dotnet publish -c Release -o published
Erstellen Sie eine Datei mit Namen Dockerfile im Stamm Ihres Projektverzeichnisses, öffnen Sie diese in einem Text-Editor und geben Sie den folgenden Inhalt ein. Eine Dockerfile-Datei ist eine Textdatei ohne Dateierweiterung, die zum Erstellen eines Containerimages verwendet wird.
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime WORKDIR /app COPY published/ ./ ENTRYPOINT ["dotnet", "MyWebApp.dll"]
Erstellen Sie ein Containerimage mit Namen aspnetapp, indem Sie den folgenden Befehl ausführen.
docker build --tag aspnetapp .
Übertragen des Images an Azure Container Registry per Push
Führen Sie den Befehl az acr login aus, um sich an Ihrer Containerregistrierung anzumelden. Das folgende Beispiel meldet sich bei einer Registrierung namens myregistry an. Ersetzen Sie den Registrierungsnamen durch den Namen Ihrer Registrierung.
az acr login --name myregistry
Der Befehl gibt
Login Succeeded
zurück, sobald die Anmeldung erfolgreich war.Verwenden Sie docker tag, um ein Tag myregistry.azurecr.io/aspnetapp:v1 für das Image aspnetapp zu erstellen.
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
Tipp
Führen Sie
docker image ls
aus, um die Liste Ihrer vorhandenen Docker-Images und -Tags zu überprüfen. In diesem Szenario sollten mindestens zwei Images angezeigt werden:aspnetapp
undmyregistry.azurecr.io/aspnetapp
.Verwenden Sie docker push, um das Image in die Containerregistrierung hochzuladen. Mit dem folgenden Befehl wird das Image beispielsweise in ein Repository namens aspnetapp mit dem Tag v1 unter der Registrierung myregistry gepusht.
docker push myregistry.azurecr.io/aspnetapp:v1
Bereitstellen der Anwendung
Erstellen Sie ein Verzeichnis Bereitstellung im Stammverzeichnis Ihres Projekts.
Fügen Sie eine Datei deployment.yaml mit dem folgenden Inhalt zum Verzeichnis Bereitstellung hinzu, um eine Bereitstellung zu erstellen. Ersetzen Sie den Wert von
template.spec.containers.image
mit dem Image, den Sie im vorherigen Schritt erstellt haben.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
Fügen Sie eine Datei service.yaml mit dem folgenden Inhalt zum Verzeichnis Bereitstellung hinzu, um einen LoadBalancer-Dienst zu erstellen.
apiVersion: v1 kind: Service metadata: name: aspnetapp-demo-service spec: type: LoadBalancer ports: - port: 80 selector: app: aspnetapp-demo
Führen Sie den folgenden Befehl aus, um die Anwendung im AKS-Cluster bereitzustellen.
kubectl create namespace appconfig-demo kubectl apply -f ./Deployment -n appconfig-demo
Führen Sie den folgenden Befehl aus, und erhalten Sie die externe IP-Adresse, die vom LoadBalancer-Dienst verfügbar gemacht wird.
kubectl get service aspnetapp-demo-service -n appconfig-demo
Öffnen Sie ein Browserfenster, und navigieren Sie zur IP-Adresse, die im vorherigen Schritt erhalten wurde. Die Webseite sieht folgendermaßen aus:
Verwenden des App Configuration Kubernetes-Anbieters
Nachdem Sie nun eine Anwendung haben, die in AKS ausgeführt wird, stellen Sie den App Configuration Kubernetes-Anbieter in Ihrem AKS-Cluster bereit, der als Kubernetes-Controller ausgeführt wird. Der Anbieter ruft Daten aus Ihrem App Configuration-Speicher ab und erstellt eine ConfigMap, die als in ein Datenvolume eingebundene JSON-Datei verarbeitet werden kann.
Einrichten des Azure App Configuration-Speichers
Fügen Sie dem App Configuration-Speicher die folgenden Schlüsselwerte hinzu, und belassen Sie Bezeichnung und Inhaltstyp auf ihren Standardwerten. Weitere Informationen zum Hinzufügen von Schlüssel-Wert-Paaren zu einem Speicher mithilfe des Azure-Portals oder der CLI finden Sie unter Erstellen eines Schlüssel-Wert-Paars.
Schlüssel | Wert |
---|---|
Settings:FontColor | Grün |
Settings:Message | Hallo von Azure App Configuration |
Einrichten des App Configuration-Kubernetes-Anbieters
Führen Sie den folgenden Befehl aus, um Anmeldeinformationen für de´n Zugriff auf Ihren AKS-Cluster abzurufen. Ersetzen Sie den Wert der
name
- undresource-group
-Parameter mit Ihrer AKS-Instanz:az aks get-credentials --name <your-aks-instance-name> --resource-group <your-aks-resource-group>
Installieren Sie den Azure App Configuration Kubernetes-Anbieter in Ihrem AKS-Cluster mittels
helm
:helm install azureappconfiguration.kubernetesprovider \ oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \ --namespace azappconfig-system \ --create-namespace
Tipp
Der App Configuration-Kubernetes-Anbieter ist auch als AKS-Erweiterung verfügbar. Diese Integration ermöglicht eine nahtlose Installation und Verwaltung über die Azure CLI, ARM-Vorlagen oder Bicep-Vorlagen. Durch die Verwendung der AKS-Erweiterung werden automatische Neben-/Patchversionsupdates unterstützt, um sicherzustellen, dass Ihr System immer auf dem neuesten Stand ist. Ausführliche Installationsanweisungen finden Sie in der Azure App Configuration-Erweiterung für Azure Kubernetes Service.
Fügen Sie eine Datei appConfigurationProvider.yaml mit dem folgenden Inhalt zum Verzeichnis Bereitstellung hinzu, um eine
AzureAppConfigurationProvider
-Ressource zu erstellen.AzureAppConfigurationProvider
ist eine benutzerdefinierte Ressource, die definiert, welche Daten aus einem Azure App Configuration-Speicher heruntergeladen werden sollen, und sie erstellt eine 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>
Ersetzen Sie den Wert des
endpoint
-Felds durch den Endpunkt Ihres Azure App Configuration-Speichers. Fahren Sie mit dem nächsten Schritt fort, um den Abschnittauth
mit Ihren Authentifizierungsinformationen zu aktualisieren.Hinweis
AzureAppConfigurationProvider
ist ein deklaratives API-Objekt. Es definiert den gewünschten Zustand der ConfigMap, die aus den Daten in Ihrem App Configuration-Speicher erstellt wurde, mit dem folgenden Verhalten:- Die ConfigMap kann nicht erstellt werden, wenn eine ConfigMap mit demselben Namen bereits im gleichen Namespace vorhanden ist.
- Die ConfigMap wird basierend auf den vorhandenen Daten in Ihrem App Configuration-Speicher zurückgesetzt, wenn sie auf andere Weise gelöscht oder geändert wird.
- Die ConfigMap wird gelöscht, wenn der App Configuration Kubernetes-Anbieter deinstalliert wird.
Befolgen Sie die Anweisungen zum Verwenden der Workloadidentität für die Authentifizierung bei Ihrem App Configuration-Speicher. Aktualisieren Sie die Datei appConfigurationProvider.yaml, indem Sie das Feld
serviceAccountName
durch den Namen des erstellten Dienstkontos ersetzen. Weitere Informationen zu anderen Authentifizierungsmethoden finden Sie in den Beispielen im Abschnitt Authentifizierung.Aktualisieren Sie die Datei deployment.yaml im Verzeichnis Deployment, um die ConfigMap
configmap-created-by-appconfig-provider
als eingebundenes Datenvolume zu verwenden. Es ist wichtig sicherzustellen, dassvolumeMounts.mountPath
mit dem in IhremWORKDIR
in Dockerfile angegebenen und dem zuvor erstellten Konfigurationsverzeichnis übereinstimmt.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
Führen Sie den folgenden Befehl aus, um die Änderungen bereitzustellen. Ersetzen Sie den Namespace, wenn Sie Ihre vorhandene AKS-Anwendung verwenden.
kubectl apply -f ./Deployment -n appconfig-demo
Aktualisieren Sie den Browser. Die Seite zeigt aktualisierte Inhalte an.
Problembehandlung
Wenn Sie nicht sehen, dass Ihre Anwendung die Daten aus dem App Configuration-Speicher abruft, führen Sie den folgenden Befehl aus, um zu überprüfen, ob die ConfigMap ordnungsgemäß erstellt wurde.
kubectl get configmap configmap-created-by-appconfig-provider -n appconfig-demo
Wenn die ConfigMap nicht erstellt wurde, führen Sie den folgenden Befehl aus, um den Datenabrufstatus abzurufen.
kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml
Wenn der Azure App Configuration Kubernetes-Anbieter Daten aus Ihrem App Configuration-Speicher erfolgreich abgerufen hat, sollte die phase
-Eigenschaft unter dem Abschnitt „Status“ der Ausgabe COMPLETE
lauten, wie im folgenden Beispiel gezeigt.
$ 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
Wenn die Phase nicht COMPLETE
ist, werden die Daten nicht ordnungsgemäß aus Ihrem App Configuration-Speicher heruntergeladen. Führen Sie den folgenden Befehl aus, um die Protokolle des Azure App Configuration Kubernetes-Anbieters anzuzeigen.
kubectl logs deployment/az-appconfig-k8s-provider -n azappconfig-system
Verwenden Sie die Protokolle für die weitere Problembehandlung. Informationen zu häufig auftretenden Problemen finden Sie im Abschnitt Häufig gestellte Fragen.
Häufig gestellte Fragen
Warum wird die ConfigMap oder der geheime Schlüssel nicht generiert?
Sie können die Schritte im Handbuch zur Problembehandlung befolgen, um Protokolle für detaillierte Fehlerinformationen zu sammeln. Hier sind einige häufige Ursachen.
- ANTWORT 403: 403 Forbidden: Die konfigurierte Identität verfügt nicht über die erforderlichen Berechtigungen für den Zugriff auf den App-Konfigurationsspeicher. Im Abschnitt Authentifizierung finden Sie Beispiele, die der verwendeten Identität entsprechen.
- Ein Key Vault-Verweis wurde in der App-Konfiguration gefunden, aber „spec.secret“ wurde nicht konfiguriert: Mindestens ein Key Vault-Verweis wird in den ausgewählten Schlüsselwerten enthalten, die Authentifizierungsinformationen für Key Vaults werden jedoch nicht bereitgestellt. Um die Integrität der Konfiguration beizubehalten, schlägt das Laden der gesamten Konfiguration fehl. Konfigurieren Sie den
spec.secret
-Abschnitt, um die erforderlichen Authentifizierungsinformationen bereitzustellen. Beispiele und weitere Informationen finden Sie unter Key Vault-Referenz.
Warum enthält die generierte ConfigMap nicht die erwarteten Daten?
Stellen Sie sicher, dass Sie die richtigen Schlüsselwertselektoren angeben, die den erwarteten Daten entsprechen. Wenn keine Selektoren angegeben werden, werden alle Schlüsselwerte ohne Bezeichnung aus Ihrem App-Konfigurationsspeicher heruntergeladen. Stellen Sie bei Verwendung eines Schlüsselfilters sicher, dass er dem Präfix Ihrer erwarteten Schlüsselwerte entspricht. Wenn Ihre Schlüsselwerte Bezeichnungen enthalten, stellen Sie sicher, dass Sie den Bezeichnungsfilter in den Selektoren angeben. Weitere Beispiele finden Sie in der Dokumentation zur Schlüsselwertauswahl.
Wie kann ich die Installation des Azure App Configuration Kubernetes-Anbieters anpassen?
Sie können die Installation anpassen, indem Sie zusätzliche Helmwerte angeben, wenn Sie den Kubernetes-Anbieter für die Azure App Configuration installieren. Sie können z. B. die Protokollebene festlegen, den Anbieter zur Ausführung auf bestimmten Knoten konfigurieren, oder die Workloadidentität deaktivieren. Weitere Informationen finden Sie im Installationshandbuch.
Auslösen einer bedarfsgesteuerten Aktualisierung von ConfigMap und Geheimnis
Sie können zwar die automatische Datenaktualisierung einrichten, es kann aber vorkommen, dass Sie eine bedarfsgesteuerte Aktualisierung auslösen möchten, um die neuesten Daten aus App Configuration und Key Vault abzurufen. Dazu können Sie die Bereitstellung des Kubernetes-Anbietercontrollers von Azure App Configuration neu starten. Der Kubernetes-Anbieter wird dann die ConfigMap und das Geheimnis mit den neuesten Daten aus Ihrem App Configuration-Speicher und Key Vault abstimmen und aktualisieren.
Es wird nicht empfohlen, die vom Kubernetes-Anbieter generierte ConfigMap und das Geheimnis zu löschen oder zu ändern. Obwohl neue aus den neuesten Daten generiert werden, kann dies bei Fehlern zu einer Downtime Ihrer Anwendungen führen.
Warum kann ich mich nicht mithilfe der Workloadidentität bei Azure App Configuration authentifizieren, nachdem der Anbieter auf Version 2.0.0 aktualisiert wurde?
Ab Version 2.0.0 ist ein vom Benutzer bereitgestelltes Dienstkonto für die Authentifizierung bei Azure App Configuration mithilfe der Workloadidentität erforderlich. Diese Änderung verbessert die Sicherheit durch Namespaceisolation. Zuvor wurde das Dienstkonto eines Kubernetes-Anbieters für alle Namespaces verwendet. Aktualisierte Anweisungen finden Sie in der Dokumentation zur Verwendung der Workloadidentität. Wenn Sie beim Upgrade auf Version 2.0.0 Zeit für die Migration benötigen, können Sie vorübergehend workloadIdentity.globalServiceAccountEnabled=true
während der Anbieterinstallation festlegen. Beachten Sie, dass die Unterstützung für die Verwendung des Dienstkontos des Anbieters in einer zukünftigen Version eingestellt wird.
Bereinigen von Ressourcen
Deinstallieren Sie den App Configuration Kubernetes-Anbieter aus Ihrem AKS-Cluster, wenn Sie den AKS-Cluster beibehalten möchten.
helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system
Wenn Sie die in diesem Artikel erstellten Ressourcen nicht mehr verwenden möchten, löschen Sie die erstellte Ressourcengruppe, um Kosten zu vermeiden.
Wichtig
Das Löschen einer Ressourcengruppe kann nicht rückgängig gemacht werden. Die Ressourcengruppe und alle darin enthaltenen Ressourcen werden unwiderruflich gelöscht. Achten Sie daher darauf, dass Sie nicht versehentlich die falsche Ressourcengruppe oder die falschen Ressourcen löschen. Falls Sie die Ressourcen für diesen Artikel in einer Ressourcengruppe erstellt haben, die andere beizubehaltende Ressourcen enthält, löschen Sie die Ressourcen einzeln über den entsprechenden Bereich, statt die Ressourcengruppe zu löschen.
- Melden Sie sich beim Azure-Portal an, und klicken Sie auf Ressourcengruppen.
- Geben Sie im Feld Nach Name filtern den Namen Ihrer Ressourcengruppe ein.
- Wählen Sie in der Ergebnisliste den Ressourcengruppennamen aus, um eine Übersicht anzuzeigen.
- Wählen Sie die Option Ressourcengruppe löschen.
- Sie werden aufgefordert, das Löschen der Ressourcengruppe zu bestätigen. Geben Sie zur Bestätigung den Namen Ihrer Ressourcengruppe ein, und klicken Sie auf Löschen.
Daraufhin werden die Ressourcengruppe und alle darin enthaltenen Ressourcen gelöscht.
Hinweis
Wenn Sie die Azure Developer CLI zum Einrichten der Ressourcen verwenden, können Sie den Befehl azd down
ausführen, um alle von der azure-appconfig-aks
-Vorlage erstellten Ressourcen zu löschen.
Nächste Schritte
In dieser Schnellstartanleitung führen Sie die folgenden Schritte aus:
- Sie haben eine Anwendung erstellt, die in Azure Kubernetes Service (AKS) ausgeführt wird.
- Sie haben Ihren AKS-Cluster mithilfe des App Configuration Kubernetes-Anbieters mit Ihrem App Configuration-Speicher verbunden.
- Sie haben eine ConfigMap mit Daten aus Ihrem App Configuration-Speicher erstellt.
- Sie haben die Anwendung mit einer Konfiguration aus Ihrem App Configuration-Speicher ausgeführt, ohne den Anwendungscode zu ändern.
Fahren Sie mit dem nächsten Tutorial fort, um zu erfahren, wie Sie Ihre AKS-Workloads für die dynamische Aktualisierung der Konfiguration aktualisieren.
Weitere Informationen zum Azure App Configuration Kubernetes-Anbieter finden Sie unter Azure App Configuration Kubernetes-Anbieterreferenz.