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

项目
10/15/2024

在 Kubernetes 中，设置 Pod 以使用 ConfigMap 中的配置。它使你可以将配置与容器映像分离，使应用程序易于移植。 Azure 应用程序配置 Kubernetes 提供程序可以使用 Azure 应用程序配置中的键值和密钥保管库引用构造 ConfigMap 和机密。使你能够充分利用 Azure 应用程序配置集中存储和管理配置，而无需更改应用程序代码。

ConfigMap 可以作为环境变量或装载的文件使用。在本快速入门中，你会将 Azure 应用程序配置 Kubernetes 提供程序整合到 Azure Kubernetes 服务工作负载，其中，你将运行一个简单 ASP.NET Core 应用，该应用使用 JSON 文件中的配置。

提示

请参阅选项，了解在 Kubernetes 中托管的用于访问 Azure 应用配置的工作负荷。

注意

本快速入门将指导你设置 Azure 应用程序配置 Kubernetes 提供程序。可以选择将以下 Azure 开发人员 CLI 命令与 azure-appconfig-aks 模板配合使用来预配 Azure 资源并部署本快速入门使用的示例应用程序。有关此模板的详细信息，请访问 GitHub 上的 azure-appconfig-aks 存储库。

azd init -t azure-appconfig-aks
azd up

先决条件

应用程序配置存储区。创建存储区。
Azure 容器注册表。创建注册表。
获得授权可以从 Azure 容器注册表中拉取映像的 Azure Kubernetes 服务 (AKS) 群集。创建 AKS 群集。
.NET SDK 6.0 或更高版本
Azure CLI
Docker Desktop
Helm
kubectl

创建一个在 AKS 中运行的应用

在本部分中，你将创建一个在 Azure Kubernetes 服务 (AKS) 中运行的简单 ASP.NET Core Web 应用。该应用程序从本地 JSON 文件读取配置。在下一部分中，你将允许应用无需更改应用代码就能使用 Azure 应用程序配置中的配置。如果已经拥有一个可以从文件中读取配置的 AKS 应用，则可以跳过此部分并转到使用应用程序配置 Kubernetes 提供程序。只需确保提供程序生成的配置文件与应用程序使用的文件路径匹配。

创建应用程序

使用 .NET 命令行界面 (CLI) 运行以下命令，在新的 MyWebApp 目录中新建一个 ASP.NET Core Web 应用项目：
```
dotnet new webapp --output MyWebApp --framework net6.0
```

打开“页面”目录中的 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 existing code in program.cs
// ... ...

容器化应用程序

运行 dotnet publish 命令，以便在发布模式下生成应用，并在 published 目录中创建资产。
```
dotnet publish -c Release -o published
```
在项目目录的根目录创建名为 Dockerfile 的文件，在文本编辑器中打开该文件，然后输入以下内容。 Dockerfile 是一个没有扩展名的文本文件，用于创建容器映像。
```
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]
```
运行以下命令，生成名为 aspnetapp 的容器映像。
```
docker build --tag aspnetapp .
```

向 Azure 容器注册表推送映像

运行 az acr login 命令以登录容器注册表。下面的示例登录到名为 myregistry 的注册表。将注册表名称替换为你自己的。
```
az acr login --name myregistry
```
登录成功后，命令将返回 Login Succeeded。
使用 Docker 标记为映像 aspnetapp 创建标记 myregistry.azurecr.cn/aspnetapp:v1。
```
docker tag aspnetapp myregistry.azurecr.cn/aspnetapp:v1
```
提示

若要查看现有 Docker 映像和标记的列表，请运行 docker image ls。在此方案中，应至少显示两个图像：aspnetapp 和 myregistry.azurecr.cn/aspnetapp。
使用 Docker 推送将映像推送到容器注册表。例如，以下命令将映像推送到名为 aspnetapp、注册表 myregistry 下具有标记 v1 的存储库。
```
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

将 service.yaml 文件添加到包含以下内容的“部署”目录，创建 LoadBalancer 服务。

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

运行以下命令，将应用程序部署到 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 地址。 Web 页面如下所示：

使用应用程序配置 Kubernetes 提供程序

你已经拥有在 AKS 中运行的应用，接下来，将应用程序配置 Kubernetes 提供程序部署到作为 Kubernetes 控制器的 AKS 群集。提供程序从应用程序配置存储中检查数据并创建 ConfigMap，该 ConfigMap 可作为装载到数据卷中的 JSON 文件使用。

设置 Azure 应用程序配置存储

将以下键值添加到应用程序配置存储区，并让“标签”和“内容类型”保留默认值。有关如何使用 Azure 门户或 CLI 将键值添加到存储区的详细信息，请转到创建键值。

Key	值
Settings:FontColor	绿色
Settings:Message	Azure 应用程序配置问候语

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

运行以下命令，获取 AKS 群集的访问凭据。将 name 和 resource-group 参数的值替换为你的 AKS 实例：
```
az aks get-credentials --name <your-aks-instance-name> --resource-group <your-aks-resource-group>
```

使用 helm 将 Azure 应用程序配置 Kubernetes 提供程序安装到 AKS 群集：

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

将 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:
      managedIdentityClientId: <your-managed-identity-client-id>
```
将 endpoint 字段的值替换为 Azure 应用程序配置存储的终结点。按照使用工作负载标识中的步骤操作，并使用你创建的用户分配托管标识的客户端 ID 更新 auth 部分。
注意

AzureAppConfigurationProvider 是声明性 API 对象。负责定义使用 Azure 应用程序配置存储中的数据创建的 ConfigMap 的所需状态，具有以下行为：
- 如果同一命名空间中已存在同名的 ConfigMap，则无法创建该 ConfigMap。
- 如果通过任何其他方式删除或修改了 ConfigMap，则会根据应用程序配置存储中的现有数据重置该 ConfigMap。
- 如果已卸载应用程序配置 Kubernetes 提供程序，则将删除 ConfigMap。

更新 Deployment 目录中的 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.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 属性应为 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 值来自定义安装。例如，可以设置日志级别，将提供程序配置为在特定节点上运行，或禁用工作负载标识。有关更多信息，请参阅安装指南。

清理资源

若要保留 AKS 群集，请从 AKS 群集卸载应用程序配置 Kubernetes 提供程序。

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

如果不想继续使用本文中创建的资源，请删除此处创建的资源组以避免产生费用。

重要

删除资源组的操作不可逆。将永久删除资源组以及其中的所有资源。请确保不要意外删除错误的资源组或资源。如果在包含要保留的其他资源的资源组中创建了本文的资源，请从相应的窗格中单独删除每个资源，而不是删除该资源组。

登录到 Azure 门户，然后选择“资源组”。
在“按名称筛选”框中，输入资源组的名称。
在结果列表中，选择资源组名称以查看概述。
选择“删除资源组”。
系统会要求确认是否删除资源组。重新键入资源组的名称进行确认，然后选择“删除” 。

片刻之后，将会删除该资源组及其所有资源。

注意

如果使用 Azure 开发人员 CLI 设置资源，则可以运行 azd down 命令删除由 azure-appconfig-aks 模板创建的所有资源。

后续步骤

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

已创建在 Azure Kubernetes 服务 (AKS) 中运行的应用。
使用应用程序配置 Kubernetes 提供程序将 AKS 群集连接到了应用程序配置存储。
使用应用程序配置存储中的数据创建了 ConfigMap。
没有更改应用代码，运行了使用应用程序配置存储中的配置的应用。

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

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

要详细了解 Azure 应用程序配置 Kubernetes 提供程序，请参阅 Azure 应用程序配置 Kubernetes 提供程序参考。