Rychlý start: Použití konfigurace Aplikace Azure ve službě Azure Kubernetes Service

V Kubernetes můžete nastavit pody tak, aby spotřebováovaly konfigurační data z objektů ConfigMap. Tento postup zlepšuje přenositelnost vašich aplikací, protože můžete oddělit konfigurační data od imagí kontejnerů.

Poskytovatel Kubernetes pro Azure App Configuration nabízí způsob, jak vytvořit objekty ConfigMap a tajné kódy Kubernetes z hodnot klíčů a odkazů služby Azure Key Vault, které jsou uložené v App Configuration. Když použijete tohoto poskytovatele, můžete použít App Configuration k centrálnímu ukládání a správě konfiguračních dat, aniž byste museli provádět změny kódu aplikace.

Objekt ConfigMap lze použít jako proměnné prostředí nebo připojený soubor. V tomto rychlém startu zahrnete do úlohy AKS zprostředkovatele Kubernetes služby Azure App Configuration. Zprostředkovatel vytvoří objekt ConfigMap z dat v obchodě App Configuration Store. V úloze spustíte základní aplikaci ASP.NET Core v podu, která využívá Objekt ConfigMap jako soubor JSON připojený ke svazku dat.

Návod

Další způsoby přístupu ke službě App Configuration z úlohy hostované v Kubernetes najdete v tématu Přístup ke službě Azure Kubernetes Service ke službě App Configuration.

Poznámka:

Tento rychlý start vás provede nastavením zprostředkovatele Kubernetes služby Azure App Configuration. Volitelně můžete pomocí následujících příkazů Azure Developer CLI zřídit prostředky Azure a nasadit ukázkovou aplikaci, kterou tento rychlý start používá. Tyto příkazy k tomuto účelu azure-appconfig-aks používají šablonu. Další informace o této šabloně najdete v úložišti GitHub azure-appconfig-aks .

azd init -t azure-appconfig-aks
azd up

Požadavky

• App Configuration Store. Vytvořte úložiště.
• Instance služby Azure Container Registry. Vytvořte registr.
• Cluster AKS, který má oprávnění k načtení imagí z registru kontejneru. Vytvořte cluster AKS.
• .NET SDK 8.0 nebo novější.
• Azure CLI.
• Docker Desktop.
• Helm.
• kubectl.

Vytvoření aplikace, která běží v AKS

V této části vytvoříte základní webovou aplikaci ASP.NET Core, která běží v AKS. Aplikace načte konfigurační data z místního souboru JSON. V další části povolíte aplikaci využívat konfigurační data z App Configuration beze změny kódu aplikace.

Pokud už máte aplikaci AKS, která čte konfiguraci ze souboru, můžete tuto část přeskočit a přejít na Použití zprostředkovatele Kubernetes konfigurace aplikace Azure. Pokud tuto část přeskočíte, ujistěte se, že konfigurační soubor, který zprostředkovatel generuje, odpovídá cestě k souboru, kterou vaše aplikace používá.

Vytvoření aplikace

1. Pomocí rozhraní příkazového řádku .NET (CLI) spusťte následující příkaz. Vytvoří projekt webové aplikace ASP.NET Core v novém adresáři MyWebApp .

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

2. V adresáři MyWebApp přejděte do adresáře Pages a otevřete Index.cshtml. Nahraďte obsah následujícím kódem:

   @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. Vytvořte konfigurační adresář v kořenovém adresáři projektu. V konfiguračním adresáři přidejte mysettings.json soubor, který obsahuje následující obsah:

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

4. V kořenovém adresáři projektu otevřete Program.cs a pak soubor JSON přidejte do zdroje konfigurace voláním AddJsonFile metody.

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

Kontejnerizace aplikace

1. Pokud chcete aplikaci sestavit v režimu vydání a vytvořit prostředky v publikovaném adresáři, spusťte příkaz dotnet publish .

   dotnet publish -c Release -o published
   

2. Vytvořte soubor s názvem Dockerfile v kořenovém adresáři projektu, otevřete ho v textovém editoru a zadejte následující obsah. Soubor Dockerfile je textový soubor, který nemá příponu. Použijete ji k vytvoření image kontejneru.

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

3. Spuštěním následujícího příkazu sestavte image kontejneru s názvem aspnetapp :

   docker build --tag aspnetapp .
   

Nahrání image do služby Container Registry

1. Pokud se chcete přihlásit k registru kontejneru, spusťte příkaz az acr login . Následující kód se přihlásí k registru s názvem myregistry. Nahraďte tento název registru názvem vašeho registru.

   az acr login --name myregistry
   

   Příkaz se vrátí Login Succeeded , pokud se úspěšně přihlásíte.

2. K vytvoření značky volané myregistry.azurecr.io/aspnetapp:v1 pro aspnetapp image použijte příkaz značky Dockeru . Nahraďte myregistry názvem vašeho registru.

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

   Návod

   Pokud chcete zkontrolovat seznam existujících imagí a značek Dockeru, spusťte docker image lspříkaz . V tomto scénáři by výstup měl obsahovat alespoň dva obrázky: aspnetapp a myregistry.azurecr.io/aspnetapp.

3. Pokud chcete nahrát image do registru kontejneru, použijte příkaz docker push . Například následující příkaz nasdílí image do úložiště s názvem aspnetapp značkou v1 pod registrem myregistry:

   docker push myregistry.azurecr.io/aspnetapp:v1
   

Nasazení aplikace

1. Vytvořte adresář nasazení v kořenovém adresáři projektu.

2. Pokud chcete definovat nasazení, přidejte do adresáře nasazení soubor deployment.yaml s následujícím obsahem. Nahraďte hodnotu template.spec.containers.image značkou, kterou jste vytvořili v předchozí části.

   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. Pokud chcete definovat LoadBalancer službu, přidejte do adresáře nasazení soubor service.yaml s následujícím obsahem:

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

4. Pokud chcete, aby se kubectl připojil ke clusteru AKS, spusťte následující příkaz. Stáhne přihlašovací údaje pro cluster AKS a sloučí je do kontextu vašeho clusteru.

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

5. Pokud chcete nasadit aplikaci do clusteru AKS a vytvořit prostředky, spusťte následující příkazy:

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

6. Pokud chcete získat externí IP adresu vystavenou službou LoadBalancer , spusťte následující příkaz:

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

7. V okně prohlížeče přejděte na IP adresu, kterou jste získali v předchozím kroku. Webová stránka by měla vypadat podobně jako na následujícím snímku obrazovky:

   

Použití zprostředkovatele Kubernetes služby Azure App Configuration

Teď, když máte aplikaci spuštěnou v AKS, je dalším krokem nasazení zprostředkovatele Kubernetes služby Azure App Configuration do clusteru AKS, který se spustí jako kontroler Kubernetes. Zprostředkovatel načte data z úložiště App Configuration Store a vytvoří objekt ConfigMap, který je použitelný jako soubor JSON připojený ke svazku dat.

Nastavení App Configuration Storu

Do App Configuration Storu přidejte následující klíče a hodnoty. Pro každou z nich použijte výchozí hodnoty pro Popisek a Typ obsahu. Další informace o tom, jak přidat hodnoty klíčů do úložiště pomocí webu Azure Portal nebo Azure CLI, najdete v tématu Vytvoření hodnoty klíče.

Klíč	Hodnota
Nastavení:FontColor	Zelený
Nastavení:Zpráva	Dobrý den z konfigurace Aplikace Azure

Nastavení zprostředkovatele Kubernetes služby Azure App Configuration

1. Nainstalujte do clusteru AKS zprostředkovatele Kubernetes služby Azure App Configuration. Poskytovatele můžete nainstalovat buď jako rozšíření AKS, nebo pomocí chartu Helm. Rozšíření AKS poskytuje bezproblémovou instalaci a správu prostřednictvím Azure CLI, šablon Azure Resource Manageru (šablon ARM) nebo souborů Bicep. Použití rozšíření AKS také usnadňuje automatické aktualizace podverze a oprav, což pomáhá zajistit, aby váš systém zůstal aktuální.

   Rozšíření AKS

   k8s-extension Přidejte rozšíření Azure CLI.

   az extension add --name k8s-extension
   

   Zaregistrujte KubernetesConfiguration poskytovatele prostředků.

   az provider register --namespace Microsoft.KubernetesConfiguration
   

   Nainstalujte rozšíření AKS pro App Configuration. cluster-name Nahraďte hodnoty parametrů resource-group odpovídajícími hodnotami z vaší instance AKS. Ve výchozím nastavení je poskytovatel nainstalován v azappconfig-system oboru názvů.

   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
   

   Další informace najdete v tématu Instalace rozšíření Azure App Configuration AKS.

   Chart Helm

   Spuštěním následujícího příkazu získejte přihlašovací údaje pro přístup ke clusteru AKS. name Nahraďte hodnoty parametrů resource-group odpovídajícími hodnotami z vaší instance AKS.

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

   Nainstalujte chart Helm.

   helm install azureappconfiguration.kubernetesprovider \
       oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
       --namespace azappconfig-system \
       --create-namespace
   

2. Pokud chcete definovat AzureAppConfigurationProvider prostředek, přidejte do adresáře nasazení soubor appConfigurationProvider.yaml s následujícím obsahem. AzureAppConfigurationProvider je vlastní prostředek. Definuje data, která se mají stáhnout z App Configuration Storu. Vytvoří také objekt 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>
   

   Nahraďte hodnotu endpoint pole koncovým bodem vašeho úložiště konfigurace Aplikace Azure. Přejděte k dalšímu kroku a aktualizujte auth oddíl ověřovacími údaji.

   Poznámka:

   AzureAppConfigurationProvider je deklarativní objekt rozhraní API. Definuje požadovaný stav objektu ConfigMap, který se vytvoří z dat v obchodě App Configuration Store. Definice požadovaného stavu určuje následující chování:

   • Vytvoření objektu ConfigMap selže, pokud objekt ConfigMap se stejným názvem již existuje ve stejném oboru názvů.
   • Objekt ConfigMap se resetuje na základě aktuálních dat v obchodě App Configuration Store, pokud se odstraní nebo upraví jiným způsobem.
   • Konfigurační mapa se odstraní, pokud se odinstaluje zprostředkovatel Kubernetes konfigurace aplikace Azure.

3. Pokud se chcete ověřit ve službě App Configuration Store, postupujte podle pokynů pro použití identity úlohy. Aktualizujte soubor appConfigurationProvider.yaml nahrazením serviceAccountName pole názvem účtu služby, který vytvoříte, když budete postupovat podle pokynů. Další informace o jiných metodách ověřování najdete v příkladech v tématu Ověřování.

4. Jak je znázorněno v následujícím kódu, aktualizujte soubor deployment.yaml v adresáři nasazení tak, aby jako připojený datový svazek používal ConfigMap configmap-created-by-appconfig-provider . Je důležité, aby volumeMounts.mountPath hodnota odpovídala hodnotě WORKDIR zadané v souboru Dockerfile a konfiguračním adresáři, který jste vytvořili dříve. Také se ujistěte, že hodnota template.spec.containers.image odpovídá názvu image, kterou jste vytvořili dříve.

   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. Pokud chcete změny nasadit, spusťte následující příkaz. Pokud používáte existující aplikaci AKS, aktualizujte obor názvů.

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

6. Aktualizujte prohlížeč. Stránka zobrazuje aktualizovaný obsah.

   

Řešení problému

Pokud vaše aplikace nečte data z obchodu App Configuration Store, spusťte následující příkaz a ověřte, že je objekt ConfigMap vytvořený správně:

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

Pokud se objekt ConfigMap nevytvořil, spuštěním následujícího příkazu získejte stav načtení dat:

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

Pokud poskytovatel Kubernetes služby Azure App Configuration načte data z vašeho úložiště App Configuration Store úspěšně, phase měla by být Completevlastnost v status části výstupu , jak je znázorněno v následujícím příkladu:

$ 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

Pokud vlastnost fáze není COMPLETE, data se nestáhnou z vašeho obchodu App Configuration správně. Pokud chcete získat přístup k protokolům zprostředkovatele Kubernetes služby Azure App Configuration, spusťte následující příkaz:

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

Protokoly použijte k dalšímu řešení potíží. Řešení běžných problémů najdete v nejčastějších dotazech.

časté otázky

Proč se negeneruje objekt ConfigMap nebo tajný klíč?

Pokud chcete shromáždit protokoly, které obsahují podrobné informace o chybě, postupujte podle kroků v tématu Řešení potíží. Tady jsou některé běžné příčiny tohoto problému:

• ODPOVĚĎ 403: 403 Zakázáno: Nakonfigurovaná identita nemá potřebná oprávnění pro přístup ke službě App Configuration Store. Příklady, které odpovídají identitě, kterou používáte, najdete v tématu Ověřování.
• Referenční informace ke službě Key Vault se nacházejí v konfiguraci aplikace, ale "spec.secret" nebyla nakonfigurována: Ve vybraných hodnotách klíčů jsou zahrnuty některé odkazy služby Key Vault, ale nejsou k dispozici ověřovací informace pro Službu Key Vault. Kvůli zachování integrity konfigurace se celá konfigurace nenačte. Nakonfigurujte oddíl tak spec.secret , aby poskytoval potřebné ověřovací informace. Příklady a další informace najdete v referenčních informacích ke službě Key Vault .

Proč vygenerovaný objekt ConfigMap neobsahuje očekávaná data?

Ujistěte se, že selektory klíč-hodnota, které zadáte, odpovídají očekávaným datům. Pokud nezadáte žádné selektory, všechny hodnoty klíčů bez popisku se stáhnou z app Configuration Storu. Pokud používáte filtr klíčů, ověřte, že odpovídá předponě očekávaných hodnot klíče. Pokud mají hodnoty klíčů popisky, nezapomeňte v selektorech zadat filtr popisků. Další příklady najdete v tématu Výběr klíč-hodnota.

Jak můžu přizpůsobit instalaci poskytovatele Kubernetes služby Azure App Configuration?

Instalaci můžete přizpůsobit tak, že při instalaci zprostředkovatele Kubernetes služby Azure App Configuration poskytnete další hodnoty Helmu. Můžete například nastavit úroveň protokolu, nakonfigurovat zprostředkovatele tak, aby běžel na konkrétním uzlu, nebo zakázat identitu úlohy. Další informace naleznete v tématu Instalace.

Jak můžu aktivovat aktualizaci objektu ConfigMap a tajného kódu na vyžádání?

Data můžete nakonfigurovat tak, aby se automaticky aktualizovala. Někdy ale můžete chtít aktivovat aktualizaci na vyžádání, abyste získali nejnovější data ze služby App Configuration a Key Vault. Chcete-li aktivovat aktualizaci, můžete upravit metadata.annotations oddíl souboru AzureAppConfigurationProvider. Zprostředkovatel Kubernetes pak aktualizuje Objekt ConfigMap a Tajný kód nejnovějšími daty z úložiště app Configuration a služby Key Vault. Příklad najdete v tématu Aktualizace na vyžádání.

Nedoporučujeme odstraňovat ani upravovat objekt ConfigMap a tajný klíč vygenerovaný poskytovatelem Kubernetes. Nové se generují z nejnovějších dat, ale tato situace může způsobit výpadky aplikací během selhání.

Proč se po upgradu zprostředkovatele na verzi 2.0.0 nemůžu ověřit pomocí identity úloh pomocí konfigurace aplikace?

Od verze 2.0.0 se pro ověřování pomocí identity úloh vyžaduje účet služby poskytovaný uživatelem. Tato změna zlepšuje zabezpečení prostřednictvím izolace oboru názvů. Dříve se pro všechny obory názvů použil účet služby poskytovatele Kubernetes. Aktualizované pokyny najdete v dokumentaci k používání identity úloh. Pokud potřebujete čas na migraci při upgradu na verzi 2.0.0, můžete nastavení dočasně použít workloadIdentity.globalServiceAccountEnabled=true během instalace poskytovatele. Upozorňujeme, že podpora použití účtu služby poskytovatele je naplánovaná na vyřazení v budoucí verzi.

Vyčištění prostředků

Pokud chcete odinstalovat poskytovatele Kubernetes služby Azure App Configuration, ale zachovat cluster AKS, odinstalujte poskytovatele pomocí následujícího příkazu:

Rozšíření AKS

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

Chart Helm

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

Pokud nechcete dál používat prostředky vytvořené v tomto článku, odstraňte skupinu prostředků, kterou jste tady vytvořili, abyste se vyhnuli poplatkům.

Důležité

Odstranění skupiny prostředků je nevratné. Skupina prostředků a všechny prostředky v ní se trvale odstraní. Ujistěte se, že omylem neodstraníte nesprávnou skupinu prostředků nebo prostředky. Pokud jste vytvořili prostředky pro tento článek ve skupině prostředků, která obsahuje další prostředky, které chcete zachovat, odstraňte jednotlivé prostředky z příslušného podokna místo odstranění skupiny prostředků.

1. Přihlaste se k webu Azure Portal a vyberte skupiny prostředků.
2. Do pole Filtrovat podle názvu zadejte název vaší skupiny prostředků.
3. V seznamu výsledků vyberte název skupiny prostředků, abyste zobrazili přehled.
4. Vyberte Odstranit skupinu prostředků.
5. Zobrazí se výzva k potvrzení odstranění skupiny prostředků. Potvrďte název skupiny prostředků a vyberte Odstranit.

Po chvíli se skupina prostředků a všechny její prostředky odstraní.

Poznámka:

Pokud k nastavení prostředků použijete Azure Developer CLI, můžete spuštěním azd down příkazu odstranit všechny prostředky vytvořené šablonou azure-appconfig-aks .

Další kroky

V tomto rychlém startu:

• Vytvořili jste aplikaci spuštěnou v AKS.
• Připojili jste cluster AKS ke službě App Configuration Store pomocí zprostředkovatele Kubernetes služby Azure App Configuration.
• Vytvořili jste objekt ConfigMap s daty z obchodu App Configuration Store.
• Spustili jste aplikaci s konfiguračními daty z app Configuration Storu beze změny kódu aplikace.

Pokud chcete zjistit, jak aktualizovat úlohy AKS tak, aby dynamicky aktualizovaly konfigurační data, pokračujte dalším kurzem.

Použití dynamické konfigurace ve službě Azure Kubernetes Service

Další informace o poskytovateli Kubernetes služby Azure App Configuration najdete v referenčních informacích ke zprostředkovateli Kubernetes služby Azure App Configuration.