快速入门：在 Azure Kubernetes 服务中使用 Azure 应用程序配置

2025-09-19

在 Kubernetes 中，可以设置 Pod 以使用 ConfigMaps 中的配置数据。这种做法可提高应用程序的可移植性，因为可以将配置数据与容器映像分离。

Azure 应用配置 Kubernetes 提供程序提供了从密钥值和存储在应用配置中的 Azure Key Vault 引用构造 Kubernetes ConfigMap 和机密的方法。使用此提供程序时，可以使用应用配置集中存储和管理配置数据，而无需更改应用程序代码。

ConfigMap 可以作为环境变量或装载的文件使用。在本快速入门中，你将在 AKS 工作负载中合并 Azure 应用配置 Kubernetes 提供程序。提供程序从应用程序配置存储中的数据创建 ConfigMap。在工作负荷中，在 Pod 中运行基本的 ASP.NET Core 应用，该应用使用 ConfigMap 作为数据卷中装载的 JSON 文件。

提示

有关从 Kubernetes 中托管的工作负荷访问应用配置的其他方法，请参阅 Azure Kubernetes 服务对应用配置的访问权限。

注意

本快速入门逐步讲解如何设置 Azure 应用配置 Kubernetes 提供程序。（可选）可以使用以下 Azure 开发人员 CLI 命令来预配 Azure 资源并部署本快速入门使用的示例应用程序。这些命令将 azure-appconfig-aks 模板用于此目的。有关此模板的详细信息，请参阅 azure-appconfig-aks GitHub 存储库。

azd init -t azure-appconfig-aks
azd up

先决条件

应用程序配置存储区。创建存储区。
Azure 容器注册表的实例。创建注册表。
有权从容器注册表拉取映像的 AKS 群集。创建 AKS 群集。
.NET SDK 8.0 或更高版本。
Azure CLI。
Docker Desktop。
赫尔姆
kubectl。

创建在 AKS 中运行的应用程序

在本部分中，你将创建在 AKS 中运行的基本 ASP.NET Core Web 应用程序。应用程序从本地 JSON 文件读取配置数据。在下一部分中，使应用程序能够使用应用配置中的配置数据，而无需更改应用程序代码。

如果已有从文件读取配置的 AKS 应用程序，可以跳过本部分，并转到 “使用 Azure 应用配置 Kubernetes 提供程序”。如果跳过本部分，请确保提供程序生成的配置文件与应用程序使用的文件路径匹配。

创建应用程序

使用 .NET 命令行接口（CLI）运行以下命令。它在新的 MyWebApp 目录中创建一个 ASP.NET 核心 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>

在项目的根目录中创建配置目录。在配置目录中，添加包含以下内容的 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 .
```

将映像推送到容器注册表

若要登录到容器注册表，请运行 az acr login 命令。以下代码登录到名为的注册表。将该注册表名称替换为注册表的名称。
```
az acr login --name myregistry
```
如果成功登录，该命令将 Login Succeeded 返回。
若要为映像创建调用 myregistry.azurecr.cn/aspnetapp:v1 的 aspnetapp 标记，请使用 docker 标记命令。将 myregistry 替换为注册表的名称。
```
docker tag aspnetapp myregistry.azurecr.cn/aspnetapp:v1
```
提示

若要查看现有 Docker 映像和标记的列表，请运行 docker image ls。在此方案中，输出应至少列出两个图像： aspnetapp 和 myregistry.azurecr.cn/aspnetapp。
若要将映像上传到容器注册表，请使用 docker push 命令。例如，以下命令将映像推送到注册表aspnetapp下带有标记v1的myregistry存储库：
```
docker push myregistry.azurecr.cn/aspnetapp:v1
```

部署应用程序

在项目的根目录中创建一个 Deployment 目录。

若要定义部署，请将包含以下内容的 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.cn/aspnetapp:v1
        ports:
        - containerPort: 80

若要定义 LoadBalancer 服务，请将包含以下内容的 service.yaml 文件添加到部署目录：

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，该 ConfigMap 可作为装载到数据卷中的 JSON 文件使用。

设置应用配置存储

将以下键和值添加到应用程序配置存储区。对于每一个，请使用标签和 内容类型的默认值。有关如何使用 Azure 门户或 Azure CLI 将键值添加到存储区的详细信息，请参阅创建键值。

密钥	值
设置：字体颜色	绿色
设置：消息	Azure 应用程序配置问候语

设置 Azure 应用配置 Kubernetes 提供程序

在 AKS 群集上安装 Azure 应用配置 Kubernetes 提供程序。可以将提供程序安装为 AKS 扩展或使用 Helm 图表。 AKS 扩展通过 Azure CLI、Azure 资源管理器模板（ARM 模板）或 Bicep 文件提供无缝安装和管理。此外，使用 AKS 扩展有助于自动进行次要和修补版本更新，帮助确保系统保持最新状态。
- AKS 扩展
- Helm 图表
将添加到 k8s-extension Azure CLI 扩展。
```
az extension add --name k8s-extension
```
注册KubernetesConfiguration资源提供程序。
```
az provider register --namespace Microsoft.KubernetesConfiguration
```
安装适用于应用程序配置的 AKS 扩展。将 cluster-name 和 resource-group 参数值替换为 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 群集的访问凭据。将 name 和 resource-group 参数值替换为 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 文件添加到部署目录。 AzureAppConfigurationProvider 是自定义资源。它定义要从应用程序配置存储区下载的数据。它还会创建 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，则会根据应用配置存储中的当前数据重置。
- 如果卸载 Azure 应用配置 Kubernetes 提供程序，则会删除 ConfigMap。
若要使用应用配置存储进行身份验证，请按照使用工作负荷标识的说明进行作。通过按照说明将字段替换为创建的服务帐户的名称来更新 serviceAccountName 文件。有关其他身份验证方法的详细信息，请参阅身份验证中的示例。

如以下代码所示，更新部署目录中的 deployment.yaml 文件，以使用 ConfigMap configmap-created-by-appconfig-provider 作为装载的数据卷。值与前面创建的 Dockerfile 中指定的值和volumeMounts.mountPath目录匹配WORKDIR非常重要。此外，请确保值 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.cn/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
```
刷新浏览器。该页显示更新后的内容。

故障排除

如果应用程序未从应用程序配置存储中读取数据，请运行以下命令以验证是否已正确创建 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 则输出部分中的属性 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，则不会正确从应用配置存储下载数据。若要访问 Azure 应用配置 Kubernetes 提供程序的日志，请运行以下命令：

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

使用日志以进一步进行故障排除。有关常见问题的解决方案，请参阅常见问题解答。

FAQ

为什么未生成 ConfigMap 或机密？

若要收集包含详细错误信息的日志，请按照故障排除中的步骤作。下面是此问题的一些常见原因：

响应 403：403 禁止访问：配置的标识缺少访问应用程序配置存储区所需的权限。有关与所使用的标识匹配的示例，请参阅 “身份验证”。
Key Vault 引用在应用配置中找到，但未配置“spec.secret”：所选密钥值中包含一个或多个 Key Vault 引用，但未提供 Key Vault 的身份验证信息。为了保持配置的完整性，整个配置无法加载。配置 spec.secret 部分以提供必要的身份验证信息。有关示例和详细信息，请参阅 Key Vault 参考。

为什么生成的 ConfigMap 不包含预期数据？

确保指定的键值选择器与预期数据匹配。如果未指定任何选择器，则不带标签的所有键值都会从应用配置存储区下载。使用密钥筛选器时，请验证它是否与预期的键值前缀匹配。如果键值具有标签，请确保在选择器中指定标签筛选器。有关更多示例，请参阅键值选择。

如何自定义 Azure 应用配置 Kubernetes 提供程序的安装？

安装 Azure 应用配置 Kubernetes 提供程序时，可以通过提供额外的 Helm 值来自定义安装。例如，可以设置日志级别，将提供程序配置为在特定节点上运行，或禁用工作负载标识。有关详细信息，请参阅安装。

如何触发 ConfigMap 和机密的按需刷新？

可以将数据配置为自动刷新。但有时可能需要触发按需刷新，以便从应用配置和 Key Vault 获取最新数据。若要触发刷新，可以修改 metadata.annotations 其部分 AzureAppConfigurationProvider。然后，Kubernetes 提供程序使用应用配置存储和 Key Vault 中的最新数据更新 ConfigMap 和机密。有关示例，请参阅按需刷新。

不建议删除或修改 Kubernetes 提供程序生成的 ConfigMap 和机密。新数据是从最新数据生成的，但这种情况可能会导致应用程序在故障期间停机。

为什么在将提供程序升级到版本 2.0.0 后，无法使用工作负载标识对应用配置进行身份验证？

从版本 2.0.0 开始，需要使用用户提供的服务帐户通过工作负荷标识通过应用配置进行身份验证。此更改通过命名空间隔离增强了安全性。以前，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 开发人员 CLI 设置资源，则可以运行 azd down 命令删除由 azure-appconfig-aks 模板创建的所有资源。

后续步骤

在本快速入门中，请执行以下操作：

创建了 AKS 中运行的应用程序。
使用 Azure 应用配置 Kubernetes 提供程序将 AKS 群集连接到应用配置存储。
使用应用程序配置存储中的数据创建了 ConfigMap。
使用应用程序配置存储中的配置数据运行应用程序，而无需更改应用程序代码。

若要了解如何更新 AKS 工作负载以动态刷新配置数据，请继续学习下一教程。

使用 Azure Kubernetes 服务中的动态配置

有关 Azure 应用配置 Kubernetes 提供程序的详细信息，请参阅 Azure 应用配置 Kubernetes 提供程序参考。