Udostępnij za pomocą

Szybki start: korzystanie z usługi Azure App Configuration w usłudze Azure Kubernetes Service

Na platformie Kubernetes można skonfigurować zasobniki do korzystania z danych konfiguracji z obiektów ConfigMap. Ta praktyka zwiększa przenośność aplikacji, ponieważ można rozdzielić dane konfiguracji z obrazów kontenerów.

Dostawca Kubernetes usługi Azure App Configuration oferuje sposób konstruowania map konfiguracji platformy Kubernetes i wpisów tajnych z kluczy-wartości i odwołań usługi Azure Key Vault przechowywanych w usłudze App Configuration. Korzystając z tego dostawcy, możesz użyć usługi App Configuration do centralnego przechowywania danych konfiguracji i zarządzania nimi bez wprowadzania zmian w kodzie aplikacji.

ConfigMap można używać jako zmiennych środowiskowych lub zainstalowanego pliku. W tym przewodniku Szybki start uwzględnisz dostawcę Kubernetes usługi Azure App Configuration w obciążeniu usługi AKS. Dostawca tworzy obiekt ConfigMap na podstawie danych w magazynie usługi App Configuration. W obciążeniu uruchamiasz podstawową aplikację ASP.NET Core w zasobniku, który używa obiektu ConfigMap jako pliku JSON zainstalowanego w woluminie danych.

Wskazówka

Aby uzyskać inne sposoby uzyskiwania dostępu do usługi App Configuration z obciążenia hostowanego na platformie Kubernetes, zobacz Azure Kubernetes Service access to App Configuration (Dostęp do usługi Azure Kubernetes Service do usługi App Configuration).

Uwaga / Notatka

Ten przewodnik Szybki start przeprowadzi Cię przez proces konfigurowania dostawcy Kubernetes usługi Azure App Configuration. Opcjonalnie możesz użyć następujących poleceń interfejsu wiersza polecenia dla deweloperów platformy Azure , aby aprowizować zasoby platformy Azure i wdrożyć przykładową aplikację, której używa ten przewodnik Szybki start. Te polecenia używają szablonu azure-appconfig-aks do tego celu. Aby uzyskać więcej informacji na temat tego szablonu, zobacz repozytorium GitHub azure-appconfig-aks .

azd init -t azure-appconfig-aks
azd up

Wymagania wstępne

Tworzenie aplikacji uruchamianej w usłudze AKS

W tej sekcji utworzysz podstawową aplikację internetową ASP.NET Core działającą w usłudze AKS. Aplikacja odczytuje dane konfiguracji z lokalnego pliku JSON. W następnej sekcji włączysz aplikacji korzystanie z danych konfiguracji z usługi App Configuration bez zmieniania kodu aplikacji.

Jeśli masz już aplikację usługi AKS, która odczytuje konfigurację z pliku, możesz pominąć tę sekcję i przejść do tematu Używanie dostawcy Kubernetes usługi Azure App Configuration. Jeśli pominiesz tę sekcję, upewnij się, że plik konfiguracji wygenerowany przez dostawcę jest zgodny ze ścieżką pliku używaną przez aplikację.

Tworzenie aplikacji

  1. Użyj interfejsu wiersza polecenia platformy .NET, aby uruchomić następujące polecenie. Tworzy projekt aplikacji internetowej ASP.NET Core w nowym katalogu MyWebApp .

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

  2. W katalogu MyWebApp przejdź do katalogu Pages , a następnie otwórz plik Index.cshtml. Zastąp zawartość następującym kodem:

    @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. Utwórz katalog konfiguracji w katalogu głównym projektu. W katalogu konfiguracji dodaj plik mysettings.json zawierający następującą zawartość:

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

  4. W katalogu głównym projektu otwórz Program.cs, a następnie dodaj plik JSON do źródła konfiguracji, wywołując metodę AddJsonFile .

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

Konteneryzowanie aplikacji

  1. Aby skompilować aplikację w trybie wydania i utworzyć zasoby w opublikowanym katalogu, uruchom polecenie dotnet publish .

    dotnet publish -c Release -o published

  2. Utwórz plik o nazwie Dockerfile w katalogu głównym projektu, otwórz go w edytorze tekstów i wprowadź następującą zawartość. Plik Dockerfile to plik tekstowy, który nie ma rozszerzenia. Służy do tworzenia obrazu kontenera.

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

  3. Skompiluj obraz kontenera o nazwie aspnetapp , uruchamiając następujące polecenie:

    docker build --tag aspnetapp .

Wypychanie obrazu do usługi Container Registry

  1. Aby zalogować się do rejestru kontenerów, uruchom polecenie az acr login . Poniższy kod loguje się do rejestru o nazwie myregistry. Zastąp tę nazwę rejestru nazwą rejestru.

    az acr login --name myregistry

    Polecenie zostanie zwrócone Login Succeeded , jeśli pomyślnie się zalogujesz.

  2. Aby utworzyć tag o nazwie myregistry.azurecr.io/aspnetapp:v1 dla aspnetapp obrazu, użyj polecenia docker tag . Zastąp myregistry ciąg nazwą rejestru.

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

    Wskazówka

    Aby przejrzeć listę istniejących obrazów i tagów platformy Docker, uruchom polecenie docker image ls. W tym scenariuszu dane wyjściowe powinny zawierać co najmniej dwa obrazy: aspnetapp i myregistry.azurecr.io/aspnetapp.

  3. Aby przekazać obraz do rejestru kontenerów, użyj polecenia docker push . Na przykład następujące polecenie wypycha obraz do repozytorium o nazwie aspnetapp z tagiem v1 w rejestrze myregistry:

    docker push myregistry.azurecr.io/aspnetapp:v1

Wdrażanie aplikacji

  1. Utwórz katalog wdrożenia w katalogu głównym projektu.

  2. Aby zdefiniować wdrożenie, dodaj plik deployment.yaml z następującą zawartością do katalogu Wdrożenia . Zastąp wartość template.spec.containers.image tagiem utworzonym w poprzedniej sekcji.

    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. Aby zdefiniować usługę LoadBalancer , dodaj plik service.yaml z następującą zawartością do katalogu Deployment :

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

  4. Aby umożliwić narzędzie kubectl nawiązywanie połączenia z klastrem usługi AKS, uruchom następujące polecenie. Pobiera poświadczenia klastra usługi AKS i scala je z kontekstem klastra.

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

  5. Aby wdrożyć aplikację w klastrze usługi AKS i utworzyć zasoby, uruchom następujące polecenia:

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

  6. Aby uzyskać zewnętrzny adres IP uwidoczniony przez usługę LoadBalancer , uruchom następujące polecenie:

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

  7. W oknie przeglądarki przejdź do adresu IP uzyskanego w poprzednim kroku. Strona internetowa powinna wyglądać podobnie do poniższego zrzutu ekranu:

    Zrzut ekranu przedstawiający przeglądarkę zawierającą stronę internetową aplikacji. Strona zawiera tekst z komunikatem Komunikat z konfiguracji lokalnej.

Korzystanie z dostawcy Kubernetes usługi Azure App Configuration

Teraz, gdy masz aplikację działającą w usłudze AKS, następnym krokiem jest wdrożenie dostawcy Kubernetes usługi Azure App Configuration w klastrze usługi AKS w celu uruchomienia go jako kontrolera Kubernetes. Dostawca pobiera dane z repozytorium App Configuration i tworzy obiekt ConfigMap, który jest możliwy do użycia jako plik JSON zainstalowany w woluminie danych.

Konfigurowanie magazynu App Configuration

Dodaj następujące klucze i wartości do magazynu App Configuration. Dla każdego z nich użyj wartości domyślnych etykiet i typu zawartości. Aby uzyskać więcej informacji na temat dodawania wartości kluczy do magazynu przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure, zobacz Tworzenie klucza-wartość.

Klucz Wartość
Ustawienia:FontColor Zielony
Ustawienia:Komunikat Witaj z usługi Azure App Configuration

Konfigurowanie dostawcy kubernetes usługi Azure App Configuration

  1. Zainstaluj dostawcę Kubernetes usługi Azure App Configuration w klastrze usługi AKS. Możesz zainstalować dostawcę jako rozszerzenie usługi AKS lub przy użyciu pakietu Helm. Rozszerzenie AKS zapewnia bezproblemową instalację i zarządzanie za pośrednictwem interfejsu wiersza polecenia platformy Azure, szablonów usługi Azure Resource Manager (szablonów usługi ARM) lub plików Bicep. Ponadto użycie rozszerzenia AKS ułatwia automatyczne aktualizacje wersji pomocniczej i poprawkowej, co pomaga zapewnić aktualność systemu.

    Dodaj element k8s-extension do rozszerzeń interfejsu wiersza polecenia platformy Azure.

    az extension add --name k8s-extension

    Zarejestruj dostawcę KubernetesConfiguration zasobów.

    az provider register --namespace Microsoft.KubernetesConfiguration

    Zainstaluj rozszerzenie AKS dla usługi App Configuration. Zastąp wartości parametrów cluster-name i resource-group odpowiednimi wartościami z wystąpienia usługi AKS. Domyślnie dostawca jest instalowany w azappconfig-system przestrzeni nazw.

    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

    Aby uzyskać więcej informacji, zobacz Instalowanie rozszerzenia AKS usługi Azure App Configuration.

  2. Aby zdefiniować AzureAppConfigurationProvider zasób, dodaj plik appConfigurationProvider.yaml z następującą zawartością do katalogu Deployment . AzureAppConfigurationProvider jest zasobem niestandardowym. Definiuje dane do pobrania ze sklepu App Configuration. Tworzy również obiekt 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>

    Zastąp wartość pola endpoint punktem końcowym magazynu Azure App Configuration. Przejdź do następnego kroku, aby zaktualizować sekcję auth przy użyciu informacji uwierzytelniania.

    Uwaga / Notatka

    AzureAppConfigurationProvider jest obiektem deklaratywnego interfejsu API. Definiuje żądany stan obiektu ConfigMap utworzonego na podstawie danych w magazynie usługi App Configuration. Definicja żądanego stanu określa następujące zachowanie:

    • Tworzenie obiektu ConfigMap kończy się niepowodzeniem, jeśli ConfigMap o tej samej nazwie już istnieje w tej samej przestrzeni nazw.
    • Obiekt ConfigMap jest resetowany na podstawie obecnych danych w magazynie usługi App Configuration, jeśli zostaną usunięte lub zmodyfikowane w jakikolwiek inny sposób.
    • Obiekt ConfigMap zostanie usunięty, jeśli dostawca kubernetes usługi Azure App Configuration zostanie odinstalowany.

  3. Aby uwierzytelnić się w magazynie usługi App Configuration, postępuj zgodnie z instrukcjami dotyczącymi używania tożsamości obciążenia. Zaktualizuj plik appConfigurationProvider.yaml , serviceAccountName zastępując pole nazwą utworzonego konta usługi podczas wykonywania instrukcji. Aby uzyskać więcej informacji na temat innych metod uwierzytelniania, zobacz przykłady w temacie Authentication (Uwierzytelnianie).

  4. Jak pokazano w poniższym kodzie, zaktualizuj plik deployment.yaml w katalogu Deployment , aby użyć obiektu ConfigMap configmap-created-by-appconfig-provider jako zainstalowanego woluminu danych. Ważne jest, aby volumeMounts.mountPath wartość była zgodna z wartością WORKDIR określoną w pliku Dockerfile i utworzonym wcześniej katalogu konfiguracji . Upewnij się również, że wartość jest template.spec.containers.image zgodna z nazwą utworzonego wcześniej obrazu.

    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. Aby wdrożyć zmiany, uruchom następujące polecenie. Zaktualizuj przestrzeń nazw, jeśli używasz istniejącej aplikacji usługi AKS.

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

  6. Odśwież przeglądarkę. Na stronie jest wyświetlana zaktualizowana zawartość.

    Zrzut ekranu przedstawiający przeglądarkę zawierającą stronę internetową aplikacji. Strona zawiera zielony tekst z informacją Hello from Azure App Configuration (Witaj z usługi Azure App Configuration).

Rozwiązywanie problemów

Jeśli aplikacja nie odczytuje danych ze sklepu App Configuration, uruchom następujące polecenie, aby sprawdzić, czy aplikacja ConfigMap została utworzona prawidłowo:

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

Jeśli element ConfigMap nie został utworzony, uruchom następujące polecenie, aby uzyskać stan pobierania danych:

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

Jeśli dostawca Kubernetes usługi Azure App Configuration pomyślnie pobiera dane ze sklepu App Configuration, phase właściwość w status sekcji danych wyjściowych powinna mieć wartość Complete, jak pokazano w poniższym przykładzie:

$ 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

Jeśli właściwość phase nie COMPLETEjest , dane nie są prawidłowo pobierane z magazynu usługi App Configuration. Aby uzyskać dostęp do dzienników dostawcy Kubernetes usługi Azure App Configuration, uruchom następujące polecenie:

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

Użyj dzienników w celu dalszego rozwiązywania problemów. Aby uzyskać rozwiązania typowych problemów, zobacz Często zadawane pytania.

Często zadawane pytania

Dlaczego element ConfigMap lub Sekret nie jest generowany?

Aby zebrać dzienniki zawierające szczegółowe informacje o błędzie, wykonaj kroki opisane w temacie Rozwiązywanie problemów. Poniżej przedstawiono niektóre typowe przyczyny tego problemu:

  • RESPONSE 403: 403 Zabronione: Skonfigurowana tożsamość nie ma niezbędnych uprawnień dostępu do magazynu App Configuration. Aby zapoznać się z przykładami zgodnymi z używaną tożsamością, zobacz Uwierzytelnianie.
  • Odwołanie do usługi Key Vault znajduje się w usłudze App Configuration, ale "spec.secret" nie zostało skonfigurowane: co najmniej jedno odwołanie usługi Key Vault znajduje się w wybranych wartościach kluczy, ale nie podano informacji o uwierzytelnianiu dla usługi Key Vault. Aby zachować integralność konfiguracji, nie można załadować całej konfiguracji. Skonfiguruj sekcję spec.secret, aby zapewnić niezbędne informacje dotyczące uwierzytelniania. Aby uzyskać przykłady i więcej informacji, zobacz Odwołania do usługi Key Vault .

Dlaczego wygenerowana mapa ConfigMap nie zawiera oczekiwanych danych?

Upewnij się, że selektory klucz-wartość określone są zgodne z oczekiwaną danymi. Jeśli nie określisz żadnych selektorów, wszystkie wartości kluczy bez etykiety będą pobierane ze sklepu App Configuration. Jeśli używasz filtru klucza, sprawdź, czy jest on zgodny z prefiksem oczekiwanych wartości klucza. Jeśli twoje wartości kluczy mają etykiety, pamiętaj, aby określić filtr etykiet w selektorach. Aby uzyskać więcej przykładów, zobacz Wybór wartości klucza.

Jak dostosować instalację dostawcy Kubernetes usługi Azure App Configuration?

Instalację można dostosować, podając dodatkowe wartości programu Helm podczas instalowania dostawcy Kubernetes usługi Azure App Configuration. Można na przykład ustawić poziom dziennika, skonfigurować dostawcę do uruchamiania w określonym węźle lub wyłączyć tożsamość obciążenia. Aby uzyskać więcej informacji, zobacz Instalacja.

Jak mogę wyzwolić odświeżanie na żądanie obiektu ConfigMap i wpisu tajnego?

Dane można skonfigurować do automatycznego odświeżania. Jednak czasami możesz chcieć wyzwolić odświeżanie na żądanie, aby pobrać najnowsze dane z usługi App Configuration i Key Vault. Aby wyzwolić odświeżanie, możesz zmodyfikować sekcję metadata.annotations .AzureAppConfigurationProvider Dostawca Kubernetes aktualizuje następnie ConfigMap i Secret najnowsze dane ze sklepu App Configuration store i Key Vault. Aby zapoznać się z przykładem, zobacz Odświeżanie na żądanie.

Nie zalecamy usuwania ani modyfikowania elementu ConfigMap i wpisu tajnego wygenerowanego przez dostawcę Kubernetes. Nowe są generowane na podstawie najnowszych danych, ale taka sytuacja może spowodować przestój aplikacji podczas awarii.

Dlaczego nie mogę uwierzytelnić się w usłudze App Configuration przy użyciu tożsamości obciążenia po uaktualnieniu dostawcy do wersji 2.0.0?

Począwszy od wersji 2.0.0, do uwierzytelniania przy użyciu tożsamości obciążenia wymagane jest konto usługi udostępniane przez użytkownika. Ta zmiana zwiększa bezpieczeństwo dzięki izolacji przestrzeni nazw. Wcześniej konto usługi dostawcy Kubernetes było używane dla wszystkich przestrzeni nazw. Aby uzyskać zaktualizowane instrukcje, zobacz dokumentację dotyczącą użycia tożsamości funkcjonalnej. Jeśli potrzebujesz czasu na migrację podczas uaktualniania do wersji 2.0.0, możesz tymczasowo użyć workloadIdentity.globalServiceAccountEnabled=true tego ustawienia podczas instalacji dostawcy. Należy pamiętać, że obsługa korzystania z konta usługi dostawcy jest zaplanowana na zakończenie pracy w przyszłej wersji.

Uprzątnij zasoby

Jeśli chcesz odinstalować dostawcę Kubernetes usługi Azure App Configuration, ale zachować klaster usługi AKS, użyj następującego polecenia, aby odinstalować dostawcę:

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

Jeśli nie chcesz nadal korzystać z zasobów utworzonych w tym artykule, usuń utworzoną tutaj grupę zasobów, aby uniknąć naliczania opłat.

Ważne

Usunięcie grupy zasobów jest nieodwracalne. Grupa zasobów i wszystkie zasoby w niej są trwale usuwane. Upewnij się, że nie usuniesz przypadkowo niewłaściwej grupy zasobów lub zasobów. Jeśli zasoby dla tego artykułu zostały utworzone w grupie zasobów zawierającej inne zasoby, które chcesz zachować, usuń każdy zasób oddzielnie z odpowiedniego okienka zamiast usuwać grupę zasobów.

  1. Zaloguj się do witryny Azure Portal i wybierz pozycję Grupy zasobów.
  2. W polu Filtruj według nazwy wprowadź nazwę grupy zasobów.
  3. Na liście wyników wybierz nazwę grupy zasobów, aby wyświetlić przegląd.
  4. Wybierz pozycję Usuń grupę zasobów.
  5. Poproszono Cię o potwierdzenie usunięcia grupy zasobów. Wprowadź nazwę grupy zasobów, aby potwierdzić, a następnie wybierz pozycję Usuń.

Po kilku chwilach grupa zasobów i wszystkie jej zasoby zostaną usunięte.

Uwaga / Notatka

Jeśli używasz interfejsu wiersza polecenia dla deweloperów platformy Azure do konfigurowania zasobów, możesz uruchomić azd down polecenie , aby usunąć wszystkie zasoby utworzone przez azure-appconfig-aks szablon.

Dalsze kroki

W ramach tego szybkiego przewodnika wykonasz następujące czynności:

  • Utworzono aplikację działającą w usłudze AKS.
  • Połączono klaster usługi AKS z magazynem App Configuration przy użyciu dostawcy kubernetes usługi Azure App Configuration.
  • Utworzono aplikację ConfigMap z danymi ze sklepu App Configuration.
  • Uruchom aplikację z danymi konfiguracji ze sklepu App Configuration bez zmiany kodu aplikacji.

Aby dowiedzieć się, jak zaktualizować obciążenia usługi AKS w celu dynamicznego odświeżania danych konfiguracji, przejdź do następnego samouczka.

Używanie konfiguracji dynamicznej w usłudze Azure Kubernetes Service

Aby uzyskać więcej informacji na temat dostawcy kubernetes usługi Azure App Configuration, zobacz Azure App Configuration Kubernetes Provider reference (Dokumentacja dostawcy kubernetes usługi Azure App Configuration).

  • Last updated on