Schnellstart: Verwenden von Azure App Configuration in Azure Kubernetes Service

Artikel
10/16/2024

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 und myregistry.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- und resource-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 Abschnitt auth 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, dass volumeMounts.mountPath mit dem in Ihrem WORKDIR 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.

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.

Verwenden der dynamischen Konfiguration in Azure Kubernetes Service

Weitere Informationen zum Azure App Configuration Kubernetes-Anbieter finden Sie unter Azure App Configuration Kubernetes-Anbieterreferenz.

Freigeben über