Freigeben über


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

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

  1. 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
    
  2. Ö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>
    
  3. 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"
      }
    }
    
  4. Ö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

  1. 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
    
  2. 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"]
    
  3. 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

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

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

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

  1. Erstellen Sie ein Verzeichnis Bereitstellung im Stammverzeichnis Ihres Projekts.

  2. 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
    
  3. 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
    
  4. 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
    
  5. 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
    
  6. Öffnen Sie ein Browserfenster, und navigieren Sie zur IP-Adresse, die im vorherigen Schritt erhalten wurde. Die Webseite sieht folgendermaßen aus:

    Screenshot zeigt den Kubernetes-Anbieter vor der Verwendung von configMap.

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

  1. 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>
    
  2. 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.

  3. 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.
  4. 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.

  5. 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
    
  6. 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
    
  7. Aktualisieren Sie den Browser. Die Seite zeigt aktualisierte Inhalte an.

    Screenshot zeigt den Kubernetes-Anbieter nach der Verwendung von configMap.

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.

  1. Melden Sie sich beim Azure-Portal an, und klicken Sie auf Ressourcengruppen.
  2. Geben Sie im Feld Nach Name filtern den Namen Ihrer Ressourcengruppe ein.
  3. Wählen Sie in der Ergebnisliste den Ressourcengruppennamen aus, um eine Übersicht anzuzeigen.
  4. Wählen Sie die Option Ressourcengruppe löschen.
  5. 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.