快速入門：在 Azure Kubernetes Service 中使用 Azure 應用程式組態

在 Kubernetes 中，您已設定 Pod 取用 ConfigMaps 中的組態。 您可以藉此將組態與容器映像分離，以便您的應用程式易於移植。 Azure 應用程式組態 Kubernetes 提供者可以從 Azure 應用程式組態中的金鑰值和金鑰保存庫參考建構 ConfigMap 和祕密。 您可以藉此利用 Azure 應用程式組態來集中儲存和管理組態，而不需要變更應用程式的程式碼。

ConfigMap 可以取用為環境變數或掛接的檔案。 在本快速入門中，您會將 Azure 應用程式組態 Kubernetes 提供者併入 Azure Kubernetes Service 工作負載中，您可以在其中執行從 JSON 檔案取用組態的簡單 ASP.NET Core 應用程式。

提示

請參閱 Kubernetes 中裝載的工作負載選項，以存取 Azure 應用程式組態。

注意

本快速入門將逐步引導您設定 Azure 應用程式組態 Kubernetes 提供者。 您可以選擇性地使用下列 Azure Developer CLI 命令搭配 azure-appconfig-aks 範本，以佈建 Azure 資源以及部署本快速入門所使用的範例應用程式。 如需有關此範本的詳細資訊，請瀏覽 GitHub 上的 azure-appconfig-aks 存放庫。

azd init -t azure-appconfig-aks
azd up

必要條件

• 應用程式組態存放區。 建立存放區。
• Azure Container Registry。 建立登錄。
• 獲得授與的權限可以從 Azure Container Registry 提取映像的 Azure Kubernetes Service (AKS) 叢集。 建立 AKS 叢集。
• .NET SDK 6.0 或更新版本
• Azure CLI
• Docker Desktop
• helm
• kubectl

建立在 AKS 中執行的應用程式

在本節中，您將建立在 Azure Kubernetes Service (AKS) 中執行的簡單 ASP.NET Core Web 應用程式。 應用程式會從本地 JSON 檔案讀取組態。 在下一節中，您將能夠從 Azure 應用程式組態取用組態，而不需變更應用程式的程式碼。 如果您已經有 AKS 應用程式從檔案讀取組態，請略過本節並移至使用應用程式組態 Kubernetes 提供者。 您只需要確定提供者所產生的組態檔符合應用程式所使用的檔案路徑。

建立應用程式

1. 使用 .NET 命令列介面 (CLI) 並執行下列命令，以在新的 MyWebApp 目錄中建立新的 ASP.NET Core Web 應用程式專案：

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

2. 在 Pages 目錄中開啟 Index.cshtml，並使用下列程式碼更新內容。

   @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. 在專案的根中建立 config 目錄，並使用下列內容將 mysettings.json 檔案新增至其中。

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

4. 開啟 program.cs，並藉由呼叫 AddJsonFile 方法，將 JSON 檔案新增至組態來源。

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

將應用程式容器化

1. 執行 dotnet publish 命令，以發行模式建置應用程式，並在已發佈的目錄中建立資產。

   dotnet publish -c Release -o published
   

2. 在專案目錄的根目錄建立名為 Dockerfile 的檔案、在文字編輯器中開啟，並且輸入下列內容。 Dockerfile 是沒有副檔名且用來建立容器映像的文字檔。

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

3. 執行下列命令，以建置名為 aspnetapp 的容器映像。

   docker build --tag aspnetapp .
   

將映像推送至 Azure Container Registry

1. 執行 az acr login 命令來登入您的容器登錄。 下列範例會登入名為 myregistry 的登錄。 將登入名稱改成您的登入名稱。

   az acr login --name myregistry
   

   登入成功後，命令就會傳回 Login Succeeded。

2. 使用 docker 標籤建立映像 aspnetapp 的標籤 myregistry.azurecr.io/aspnetapp:v1。

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

   提示

   若要檢閱現有 Docker 映像和標籤清單，請執行 docker image ls。 在此案例中，您應該會看到至少兩個映像：aspnetapp 和 myregistry.azurecr.io/aspnetapp。

3. 使用 docker push 將映射上傳至容器登錄。 例如，下列命令會將映射推送至名為 aspnetapp 而且其標記 v1 在登錄 myregistry 下的存放庫。

   docker push myregistry.azurecr.io/aspnetapp:v1
   

部署應用程式

1. 在專案的根目錄中建立部署目錄。

2. 使用下列內容將 deployment.yaml 檔案新增至部署目錄，以建立部署。 將 template.spec.containers.image 的值 取代為您在上一個步驟中建立的映像。

   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. 使用下列內容將 service.yaml 檔案新增至部署目錄，以建立 LoadBalancer 服務。

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

4. 執行下列命令，將應用程式部署至 AKS 叢集。

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

5. 執行下列命令，並取得 LoadBalancer 服務公開的外部 IP 位址。

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

6. 開啟瀏覽器視窗，並且瀏覽至上一個步驟中取得的 IP 位址。 網頁如下所示：

   

使用應用程式組態 Kubernetes 提供者

既然您已在 AKS 中執行應用程式，您將會將應用程式組態 Kubernetes 提供者部署到以 Kubernetes 控制器身分執行的 AKS 叢集。 提供者會從應用程式組態存放區擷取資料，並建立 ConfigMap，該檔案會做為在資料磁碟區中掛接的 JSON 檔案。

設定 Azure 應用程式組態存放區

將下列金鑰值新增至應用程式組態存放區，並將標籤和內容類型保留預設值。 如需如何使用 Azure 入口網站或 CLI 將金鑰值新增至存放區的詳細資訊，請移至建立金鑰值。

索引鍵	值
Settings:FontColor	綠色
Settings:Message	來自 Azure 應用程式組態的問候

設定應用程式組態 Kubernetes 提供者

1. 執行下列命令，取得 AKS 叢集的存取認證。 將 name 和 resource-group 參數的值取代為您的 AKS 執行個體：

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

2. 使用 helm 將 Azure 應用程式組態 Kubernetes 提供者安裝到您的 AKS 叢集：

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

   提示

   應用程式組態 Kubernetes 提供者也可用作為 AKS 擴充功能。 此整合可讓您透過 Azure CLI、ARM 範本或 Bicep 範本順暢地進行安裝和管理。 使用 AKS 擴充功能有助於自動進行次要/修補版本更新，確保系統一律為最新狀態。 如需詳細的安裝指示，請參閱適用於 Azure Kubernetes Service 的 Azure 應用程式組態延伸模組。

3. 使用下列內容將 appConfigurationProvider.yaml 檔案新增至部署目錄，以建立 AzureAppConfigurationProvider 資源。 AzureAppConfigurationProvider 是自訂資源，定義要從 Azure 應用程式組態存放區下載哪些資料，並建立 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>
   

   將欄位 endpoint 的值取代為 Azure 應用程式組態存放區的端點。 繼續進行下一個步驟，以使用您的驗證資訊更新 auth 區段。

   注意

   AzureAppConfigurationProvider 是宣告式 API 物件。 這會使用下列行為，定義從應用程式組態存放區中的資料建立的 ConfigMap 所需狀態：

   • 如果具有相同名稱的 ConfigMap 已存在於相同的命名空間中，則無法建立 ConfigMap。
   • 如果應用程式組態存放區中的現有資料遭到其他任何方式刪除或修改，ConfigMap 將會重設。
   • 如果解除安裝應用程式組態 Kubernetes 提供者，將會刪除 ConfigMap。

4. 請遵循指示以使用工作負載身分識別，向應用程式組態存放區進行驗證。 將 appConfigurationProvider.yaml 檔案，以您建立的服務帳戶名稱取代 serviceAccountName 欄位。 如需其他驗證方法的詳細資訊，請參閱驗證 一節中的範例。

5. 更新部署目錄中的 deployment.yaml 檔案，以使用 ConfigMap configmap-created-by-appconfig-provider 做為掛接的資料磁碟區。 請務必確定 volumeMounts.mountPath 符合 Dockerfile 中指定的 WORKDIR，以及之前建立的 config 目錄。

   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. 執行下列命令以部署變更。 如果您使用現有的 AKS 應用程式，請取代命名空間。

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

7. 重新整理瀏覽器。 頁面會顯示更新的內容。

   

疑難排解

如果您並未看到應用程式從應用程式組態存放區挑選資料，請執行下列命令來驗證 ConfigMap 是否已正確建立。

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

如果未建立 ConfigMap，請執行下列命令以取得資料擷取狀態。

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

如果 Azure 應用程式組態 Kubernetes 提供者已成功從應用程式組態存放區擷取資料，輸出狀態區段下的 phase 屬性應該是 COMPLETE，如下列範例所示。

$ 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

如果階段不是 COMPLETE，則不會從應用程式組態存放區正確下載資料。 執行下列命令以顯示 Azure 應用程式組態 Kubernetes 提供者的記錄。

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

使用記錄進行進一步的疑難排解 如需常見問題，請參閱常見問題一節。

常見問題集

為何不會產生 ConfigMap 或祕密？

您可以依照疑難解答指南中的步驟收集記錄，以取得詳細的錯誤資訊。 以下是一些常見的原因。

• 回應 403：403 禁止：設定的身分識別缺少存取應用程式組態存放區的必要權限。 如需符合您所使用身分識別的範例，請參閱驗證一節。
• 在應用程式組態中找到 Key Vault 參考，但未設定 'spec.secret'：選取的索引鍵值中包含一或多個 Key Vault 參考，但未提供 Key Vault 的驗證資訊。 為了維護組態的完整性，整個組態無法載入。 設定 spec.secret 章節以提供必要的驗證資訊。 如需範例和更多資訊，請參閱 Key Vault 參考。

為什麼產生的 ConfigMap 未包含預期的資料？

請確定您指定正確的索引鍵值選取器，以符合預期的資料。 如果未指定選取器，則會從應用程式組態存放區下載不含標籤的所有索引鍵值。 使用索引鍵篩選時，請確認它符合您預期的索引鍵值前置詞。 如果您的索引鍵值具有標籤，請務必在選取器中指定標籤篩選。 如需更多範例，請參閱索引鍵值選取文件。

如何自訂 Azure 應用程式組態 Kubernetes 提供者的安裝？

您可以在安裝 Azure 應用程式組態 Kubernetes 提供者時提供額外的 Helm 值來自訂安裝。 例如，您可以設定記錄層級、設定提供者在特定節點上執行，或停用工作負載身分識別。 如需詳細資訊，請參閱安裝指南。

為什麼在將提供者升級至 2.0.0 版之後，我無法使用工作負載身分識別向 Azure 應用程式組態進行驗證？

從 2.0.0 版開始，要使用工作負載身分識別向 Azure 應用程式組態進行驗證，需要使用者提供的服務帳戶。 這項變更會透過命名空間隔離來增強安全性。 之前，Kubernetes 提供者的服務帳戶用於所有命名空間。 如需更新的指示，請參閱使用工作負載身分識別的文件。 如果您需要在升級至 2.0.0 版時移轉的時間，您可以在提供者安裝期間暫時設定 workloadIdentity.globalServiceAccountEnabled=true。 請注意，未來版本將會淘汰使用提供者服務帳戶的支援。

清除資源

如果您想要保留 AKS 叢集，請從 AKS 叢集解除安裝應用程式組態 Kubernetes 提供者。

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

如果您不想繼續使用本文中建立的資源，請刪除在此處建立的資源群組，以避免產生費用。

重要

刪除資源群組是無法回復的動作。 資源群組和其中的所有資源都將被永久刪除。 請確定您不會誤刪錯誤的資源群組或資源。 如果您是在包含需保留其他資源的資源群組內部，建立本文的資源，則可以從每個資源各自的窗格中個別刪除每個資源，而不必刪除整個資源群組。

1. 登入 Azure 入口網站，然後選取 [資源群組]。
2. 在 [依名稱篩選] 方塊中，輸入您資源群組的名稱。
3. 在結果清單中，選取資源群組名稱以查看概觀。
4. 選取 [刪除資源群組]。
5. 系統將會要求您確認是否刪除資源群組。 輸入您資源群組的名稱以進行確認，然後選取 [刪除]。

不久後，系統便會刪除該資源群組及其所有的資源。

注意

如果使用 Azure Developer CLI 以設定資源，您可以執行 azd down 命令以刪除 azure-appconfig-aks 範本所建立的所有資源。

下一步

在本快速入門中，您將：

• 已建立在 Azure Kubernetes Service (AKS) 中執行的應用程式。
• 使用應用程式組態 Kubernetes 提供者，將 AKS 叢集連線到應用程式組態存放區。
• 使用來自應用程式組態存放區的資料建立 ConfigMap。
• 從應用程式組態存放區使用組態執行應用程式，而不需要變更應用程式的程式碼。

若要了解如何將 AKS 工作負載更新為以動態方式重新整理組態，請繼續進行下一個教學課程。

在 Azure Kubernetes Service 中使用動態組態

若要深入了解 Azure 應用程式組態 Kubernetes 提供者，請參閱 Azure 應用程式組態 Kubernetes 提供者參考。