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

在 Kubernetes 中，您可以設定 Pod 來取用 ConfigMap 中的組態資料。此作法可改善應用程式的可攜性，因為您可以將組態資料與容器映像分離。

Azure 應用程式設定 Kubernetes 提供者提供一種方法，可從儲存在應用程式設定中的索引鍵/值和 Azure 金鑰保存庫參考建構 Kubernetes ConfigMap 和秘密。當您使用此提供者時，您可以使用 App Configuration 來集中儲存和管理您的組態資料，而無需變更應用程式程式碼。

ConfigMap 可以取用為環境變數或掛接的檔案。在本快速入門中，您會將 Azure 應用程式設定 Kubernetes 提供者併入 AKS 工作負載中。提供者會從 App Configuration 存放區中的資料建立 ConfigMap。在工作負載中，您會在網繭中執行基本的 ASP.NET Core 應用程式，該應用程式會將 ConfigMap 取用為掛載在資料磁碟區中的 JSON 檔案。

提示

如需從裝載於 Kubernetes 的工作負載存取 App Configuration 的其他方式，請參閱 Azure Kubernetes Service 存取 App Configuration。

注意

本快速入門會逐步引導您設定 Azure 應用程式設定 Kubernetes 提供者。您可以選擇性地使用下列 Azure 開發人員 CLI 命令來佈建 Azure 資源，並部署本快速入門所使用的範例應用程式。這些命令會針對 azure-appconfig-aks 此目的使用範本。如需此範本的詳細資訊，請參閱 azure-appconfig-aks GitHub 存放庫。

azd init -t azure-appconfig-aks
azd up

必要條件

應用程式組態存放區。建立存放區。
Azure Container Registry 的實例。建立登錄。
具有從容器登錄提取映像許可權的 AKS 叢集。建立 AKS 叢集。
.NET SDK 8.0 或更新版本。
Azure CLI。
Docker 桌面。
頭盔。
kubectl。

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

在本節中，您會建立在 AKS 中執行的基本 ASP.NET Core Web 應用程式。應用程式會從本機 JSON 檔案讀取組態資料。在下一節中，您可以讓應用程式取用 App Configuration 中的組態資料，而不變更應用程式程式碼。

如果您已經有從檔案讀取組態的 AKS 應用程式，您可以略過本節，並移至使用 Azure 應用程式組態 Kubernetes 提供者。如果您略過本節，請確定提供者產生的組態檔符合應用程式使用的檔案路徑。

建立應用程式

使用 .NET 命令列介面（CLI）來執行下列命令。它會在新的 MyWebApp 目錄中建立 ASP.NET Core Web 應用程式專案。
```
dotnet new webapp --output MyWebApp --framework net8.0
```

在 MyWebApp 目錄中，移至 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>

在專案的根目錄中建立設定目錄。在 config 目錄中，新增包含下列內容的 mysettings.json 檔案：
```
{
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}
```

在您的專案根目錄中，開啟 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 the existing code in Program.cs
// ... ...

將應用程式容器化

若要以發行模式建置應用程式，並在 已發佈 的目錄中建立資產，請執行 dotnet publish 命令。
```
dotnet publish -c Release -o published
```
在專案目錄的根目錄建立名為 Dockerfile 的檔案、在文字編輯器中開啟，並且輸入下列內容。 Dockerfile 是沒有副檔名的文字檔。您可以使用它來建立容器映像。
```
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]
```
建置以執行下列命令命名的 aspnetapp 容器映像：
```
docker build --tag aspnetapp .
```

將映像推送至 Container Registry

若要登入容器登錄，請執行 az acr login 命令。下列程式碼會登入名為 myregistry的登錄。將該登錄名稱取代為您的登錄名稱。
```
az acr login --name myregistry
```
如果您成功登入，則會傳回 Login Succeeded 命令。
若要建立呼叫映像檔的aspnetapp標籤myregistry.azurecr.io/aspnetapp:v1，請使用 docker tag 命令。取代 myregistry 為您的登錄名稱。
```
docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1
```
提示

若要檢閱現有 Docker 映像和標籤的清單，請執行 docker image ls。在此案例中，輸出應列出至少兩個影像： aspnetapp 和 myregistry.azurecr.io/aspnetapp。
若要將映像上傳至容器登錄，請使用 docker push 命令。例如，下列命令會將映像檔推送至登錄myregistry下名為 aspnetapp with tag v1 的存放庫：
```
docker push myregistry.azurecr.io/aspnetapp:v1
```

部署應用程式

若要定義部署，請將具有下列內容的 deployment.yaml 檔案新增至 Deployment 目錄。將的 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

若要定義 LoadBalancer 服務，請將具有下列內容的 service.yaml 檔案新增至 Deployment 目錄：

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

若要讓 kubectl 能夠連線到您的 AKS 叢集，請執行下列命令。它會下載 AKS 叢集的認證，並將其合併到叢集的內容中。
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```

若要將應用程式部署至 AKS 叢集並建立資源，請執行下列命令：

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

若要取得服務公開的 LoadBalancer 外部 IP 位址，請執行下列命令：
```
kubectl get service aspnetapp-demo-service -n appconfig-demo
```
在瀏覽器視窗中，移至您在上一步中取得的 IP 位址。網頁看起來應該類似下列螢幕擷取畫面：

使用 Azure 應用程式設定 Kubernetes 提供者

現在您已在 AKS 中執行應用程式，下一個步驟是將 Azure 應用程式設定 Kubernetes 提供者部署至 AKS 叢集，以 Kubernetes 控制器的形式執行。提供者會從應用程式組態存放區擷取資料，並建立 ConfigMap，該檔案會做為在資料磁碟區中掛接的 JSON 檔案。

設定 App Configuration 存放區

將下列索引鍵和值新增至 App Configuration 存放區。對於每一個，請使用標籤和 內容型別的預設值。如需如何使用 Azure 入口網站或 Azure CLI 將索引鍵/值新增至存放區的詳細資訊，請參閱建立索引鍵/值。

索引鍵	值
設定：字體顏色	綠色
設定：訊息	來自 Azure 應用程式組態的問候

設定 Azure 應用程式設定 Kubernetes 提供者

在 AKS 叢集上安裝 Azure 應用程式設定 Kubernetes 提供者。您可以將提供者安裝為 AKS 延伸模組，或使用 Helm 圖表。 AKS 延伸模組可透過 Azure CLI、Azure Resource Manager 範本（ARM 範本）或 Bicep 檔案提供順暢的安裝和管理。此外，使用 AKS 延伸模組有助於自動次要和修補程式版本更新，有助於確保您的系統保持最新狀態。
- AKS 擴充功能
- Helm 圖表
將新增至 k8s-extension 您的 Azure CLI 延伸模組。
```
az extension add --name k8s-extension
```
註冊 KubernetesConfiguration 資源提供者。
```
az provider register --namespace Microsoft.KubernetesConfiguration
```
安裝適用於應用程式組態的 AKS 擴充功能。將和 resource-group 參數值取代cluster-name為 AKS 執行個體中的對應值。根據預設，提供者會安裝在命名空間中 azappconfig-system 。
```
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
```
如需詳細資訊，請參閱安裝 Azure 應用程式設定 AKS 延伸模組。
執行下列命令以取得 AKS 叢集的存取認證。將和 resource-group 參數值取代name為 AKS 執行個體中的對應值。
```
az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
```
安裝 Helm 圖表。
```
helm install azureappconfiguration.kubernetesprovider \
    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
    --namespace azappconfig-system \
    --create-namespace
```
若要定義 AzureAppConfigurationProvider 資源，請將具有下列內容的 appConfigurationProvider.yaml 檔案新增至 Deployment 目錄。 AzureAppConfigurationProvider 是自訂資源。它定義要從 App Configuration 存放區下載的資料。它還創建了一個 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 物件。它會定義從 App Configuration 存放區中資料建立的 ConfigMap 所需狀態。所需狀態的定義會指定下列行為：
- 如果相同命名空間中已存在具有相同名稱的 ConfigMap，則 ConfigMap 建立會失敗。
- 如果 ConfigMap 以任何其他方式刪除或修改，則會根據 App Configuration 存放區中的目前資料重設。
- 如果解除安裝 Azure App Configuration Kubernetes 提供者，則會刪除 ConfigMap。
若要向 App Configuration 存放區進行驗證，請遵循使用工作負載身分識別的指示。更新 appConfigurationProvider.yaml 檔案，方法是將欄位 serviceAccountName 取代為您依照指示建立的服務帳戶名稱。如需其他驗證方法的詳細資訊，請參閱驗證中的範例。

如下列程式碼所示，更新 Deployment 目錄中的 deployment.yaml 檔案，以使用 ConfigMap configmap-created-by-appconfig-provider 作為掛載的資料磁碟區。請務必符合 volumeMounts.mountPathWORKDIR Dockerfile 中指定的值，以及您先前建立的組態目錄。此外，請確定的 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
        volumeMounts:
        - name: config-volume
          mountPath: /app/config
      volumes:
      - name: config-volume 
        configMap: 
          name: configmap-created-by-appconfig-provider

若要部署變更，請執行下列命令。如果您使用現有的 AKS 應用程式，請更新命名空間。
```
kubectl apply -f ./Deployment -n appconfig-demo
```
重新整理瀏覽器。頁面會顯示更新的內容。

疑難排解

如果您的應用程式未從 App Configuration 存放區讀取資料，請執行下列命令，以確認已正確建立 ConfigMap：

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

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

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

如果 Azure App Configuration Kubernetes 提供者成功從 App Configuration 存放區擷取資料， phase 則輸出區段中的 status 屬性應該是 Complete，如下列範例所示：

$ 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

如果階段屬性不是 COMPLETE，則不會正確地從 App Configuration 存放區下載資料。若要存取 Azure 應用程式設定 Kubernetes 提供者的記錄，請執行下列命令：

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

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

FAQ

為什麼 ConfigMap 或 Secret 沒有被生成？

若要收集包含詳細錯誤資訊的日誌，請遵循疑難排解中的步驟。以下是導致此問題的一些常見原因：

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

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

請確定您指定的索引鍵值選取器符合預期的資料。如果您未指定任何選取器，則所有沒有標籤的索引鍵/值都會從您的 App Configuration 存放區下載。使用索引鍵篩選器時，請確認它符合預期索引鍵/值的前置詞。如果您的索引鍵值具有標籤，請務必在選取器中指定標籤篩選。如需更多範例，請參閱索引鍵值選取。

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

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

如何觸發 ConfigMap 和密碼的隨選重新整理？

您可以將資料設定為自動重新整理。但有時候，您可能想要觸發隨選重新整理，以從應用程式設定和金鑰保存庫取得最新資料。若要觸發重新整理，您可以修改 metadata.annotations 的區段 AzureAppConfigurationProvider。然後，Kubernetes 提供者會使用來自 App Configuration 存放區和 Key Vault 的最新資料來更新 ConfigMap 和秘密。如需範例，請參閱隨需重新整理。

我們不建議刪除或修改 Kubernetes 提供者所產生的 ConfigMap 和密碼。新的應用程式是從最新資料產生的，但這種情況可能會導致應用程式在失敗期間停機。

為什麼在將提供者升級至 2.0.0 版之後，我無法使用工作負載身分識別來向 App Configuration 進行驗證？

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

清除資源

如果您想要解除安裝 Azure 應用程式組態 Kubernetes 提供者，但保留 AKS 叢集，請使用下列命令來解除安裝提供者：

AKS 擴充功能
Helm 圖表

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

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

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

重要

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

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

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

注意

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

下一步

在本快速入門中，您將：

已建立在 AKS 中執行的應用程式。
使用 Azure App Configuration Kubernetes 提供者將 AKS 叢集連線到 App Configuration 存放區。
使用來自應用程式組態存放區的資料建立 ConfigMap。
使用應用程式設定存放區中的組態資料執行應用程式，而不變更應用程式程式碼。

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

在 Azure Kubernetes Service 中使用動態組態

如需 Azure 應用程式設定 Kubernetes 提供者的詳細資訊，請參閱 Azure 應用程式設定 Kubernetes 提供者參考。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-02