Azure Key Vault 提供程序适用于 Azure Kubernetes 服务（AKS）的 Secrets Store CSI 驱动程序的配置选项

本文介绍 Azure Kubernetes 服务（AKS）中用于机密存储 CSI 驱动程序的 Azure Key Vault 提供程序的配置选项，包括如何启用和自定义机密的自动轮换、将装载的内容与 Kubernetes 机密同步以及访问指标。

先决条件

在开始之前，请完成在 AKS 群集中使用用于机密存储 CSI 驱动程序的 Azure Key Vault 提供程序的步骤，并提供用于在 AKS 中访问机密存储 CSI 驱动程序的 Azure Key Vault 提供程序的标识。

自动轮换和机密同步概述

启用自动轮换后，Azure Key Vault 提供程序将更新 Secrets Store CSI 驱动程序的 Pod 挂载和字段secretObjects中定义的SecretProviderClass Kubernetes 机密。它通过根据你定义的轮换轮询间隔定期轮询更改来实现此目的。默认的轮换轮询间隔为两分钟。

在最初的 Pod 部署后，当您更新外部机密存储库中的机密时，Kubernetes 机密和 Pod 挂载会根据应用程序如何使用机密数据定期更新。

将 Kubernetes Secret 作为卷挂载：使用 Secrets Store CSI Driver 的自动更新和同步 K8s Secret 功能。应用程序需要监视已装载的 Kubernetes 机密卷的更改。当 CSI 驱动程序更新 Kubernetes 机密时，相应的卷内容也会自动更新。
应用程序从容器的文件系统读取数据：使用机密存储 CSI 驱动程序的轮换功能。应用程序需要监视由 CSI 驱动程序装载的卷中的文件更改。
将 Kubernetes 机密用于环境变量：重启 Pod 以将最新机密作为环境变量获取。使用重载程序等工具来监视同步的 Kubernetes 机密的更改，并在 Pod 上执行滚动升级。

在新 AKS 群集上启用自动旋转

使用az aks create命令，并通过--enable-secret-rotation标志和设置--enable-addons标志为azure-keyvault-secrets-provider，在新群集上启用机密的自动轮换。以下示例在资源组myAKSCluster中创建一个名为myResourceGroup的新 AKS 群集：

az aks create \
    --name myAKSCluster \
    --resource-group myResourceGroup \
    --enable-addons azure-keyvault-secrets-provider \
    --enable-secret-rotation \
    --generate-ssh-keys

精简示例输出：

{
  "aadProfile": null,
  "addonProfiles": {
    "azureKeyvaultSecretsProvider": {
      "config": {
        "enableSecretRotation": "true",
        "rotationPollInterval": "2m"
      },
      "enabled": true,
...

在现有 AKS 群集上启用自动轮换

更新现有群集，以启用机密自动轮换，使用az aks addon update命令以及enable-secret-rotation参数，并将--addon标志设置为azure-keyvault-secrets-provider。以下示例更新资源组myAKSCluster中名为myResourceGroup的现有 AKS 群集：
```
az aks addon update --resource-group myResourceGroup --name myAKSCluster --addon azure-keyvault-secrets-provider --enable-secret-rotation
```

自定义旋转间隔

使用az aks addon update命令和rotation-poll-interval参数指定自定义旋转间隔。以下示例将资源组myAKSCluster中的现有 AKS 群集myResourceGroup的轮转轮询间隔设置为 5 分钟：
```
az aks addon update --resource-group myResourceGroup --name myAKSCluster --addon azure-keyvault-secrets-provider --enable-secret-rotation --rotation-poll-interval 5m
```
精简示例输出：
```
...
        "rotationPollInterval": "5m"
...
```

在现有 AKS 群集上禁用自动旋转

小窍门

如果您已在使用SecretProviderClass，可以在无需先禁用的情况下，通过不带az aks addon enable参数的--enable-secret-rotation命令更新加载项。

使用 az aks addon disable 命令禁用 Azure Key Vault 提供程序以用于机密存储驱动程序加载项。以下示例禁用资源组myAKSCluster中的现有 AKS 群集myResourceGroup的加载项：

az aks addon disable --resource-group myResourceGroup --name myAKSCluster --addon azure-keyvault-secrets-provider

精简示例输出：

...
    "azureKeyvaultSecretsProvider": {
      "config": null,
      "enabled": false,
      "identity": null
...

不使用enable-secret-rotation参数的情况下，使用az aks addon enable命令重新启用机密存储驱动程序附加组件的 Azure Key Vault 提供程序。以下示例为资源组 myAKSCluster 中命名为 myResourceGroup 的现有 AKS 群集重新启用加载项：
```
az aks addon enable --resource-group myResourceGroup --name myAKSCluster --addon azure-keyvault-secrets-provider
```
精简示例输出：
```
...
        "enableSecretRotation": "false",
        "rotationPollInterval": "2m"
      },
      "enabled": true,
...
```

将装载的内容与 Kubernetes 机密同步

注意

使用本部分中的 YAML 示例之前，需要对其进行修改，以支持你选择的访问密钥保管库标识的方法。有关详细信息，请参阅提供身份验证以访问 Secrets Store CSI 驱动程序的 Azure Key Vault 提供程序。

你可能想要创建一个 Kubernetes 机密来镜像装载的机密内容。启动 Pod 来装载机密后，机密将会同步。在删除使用机密的 Pod 时，也会删除 Kubernetes 机密。

在创建 secretObjects 以定义 Kubernetes 机密的所需状态时，使用 SecretProviderClass 字段将已装载的内容与 Kubernetes 机密同步，如以下示例 YAML 所示。

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: azure-sync
spec:
  provider: azure
  secretObjects:                              # [OPTIONAL] SecretObjects defines the desired state of synced Kubernetes secret objects
  - data:
    - key: username                           # data field to populate
      objectName: foo1                        # name of the mounted content to sync; this could be the object name or the object alias
    secretName: foosecret                     # name of the Kubernetes secret object
    type: Opaque                              # type of Kubernetes secret object (for example, Opaque, kubernetes.io/tls)

注意

确保 objectName 字段中的 secretObjects 与所装载内容的文件名匹配。如果改用 objectAlias，则它应匹配对象别名。

设置环境变量以引用 Kubernetes 机密

注意

示例 YAML 演示如何通过 env 变量和 volume/volumeMount 访问机密。典型的应用程序将使用一种方法或其他方法。请记住，至少需要由一个 Pod 装载机密才能通过 env 变量提供。

通过在 Pod 中设置环境变量来引用新创建的 Kubernetes 机密，如以下示例 YAML 所示：

kind: Pod
apiVersion: v1
metadata:
  name: busybox-secrets-store-inline
spec:
  containers:
    - name: busybox
      image: registry.k8s.io/e2e-test-images/busybox:1.29-1
      command:
        - "/bin/sleep"
        - "10000"
      volumeMounts:
      - name: secrets-store01-inline
        mountPath: "/mnt/secrets-store"
        readOnly: true
      env:
      - name: SECRET_USERNAME
        valueFrom:
          secretKeyRef:
            name: foosecret
            key: username
  volumes:
    - name: secrets-store01-inline
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: "azure-sync"

访问 Azure Key Vault 提供程序和 Secrets Store CSI 驱动程序的指标

可以访问机密存储 CSI 驱动程序的 Azure Key Vault 提供程序和机密存储 CSI 驱动程序本身提供的指标。这些指标可帮助你监视机密管理解决方案的性能和运行状况。

Azure Key Vault 提供程序指标

Azure Key Vault 提供程序公开以下指标：

指标	说明	Tags
`keyvault_request`	从密钥保管库获取密钥所花费时间的分布。	`os_type=<runtime os>`，`provider=azure`，`object_name=<keyvault object name>`，`object_type=<keyvault object type>`，`error=<error if failed>`
`grpc_request`	gRPC 请求所花费时间的分布。	`os_type=<runtime os>`，`provider=azure`，`grpc_method=<rpc full method>`，`grpc_code=<grpc status code>`，`grpc_message=<grpc status message>`

指标是通过 Prometheus 从端口 8898 提供的，但默认情况下此端口不会在 Pod 外部公开。

使用 kubectl port-forward 命令通过 localhost 访问 Azure Key Vault 提供程序指标。

kubectl port-forward -n kube-system ds/aks-secrets-store-provider-azure 8898:8898 & curl localhost:8898/metrics

机密存储 CSI 驱动程序指标

机密存储 CSI 驱动程序公开了以下指标：

指标	说明	Tags
`total_node_publish`	成功的卷装载请求总数。	`os_type=<runtime os>`，`provider=<provider name>`
`total_node_unpublish`	成功的卷卸载请求总数。	`os_type=<runtime os>`
`total_node_publish_error`	卷装载请求的错误总数。	`os_type=<runtime os>`，`provider=<provider name>`，`error_type=<error code>`
`total_node_unpublish_error`	卷卸载请求的错误总数。	`os_type=<runtime os>`
`total_sync_k8s_secret`	同步的 Kubernetes 机密总数。	`os_type=<runtime os>`，`provider=<provider name>`
`sync_k8s_secret_duration_sec`	同步 Kubernetes 机密所花费时间的分布。	`os_type=<runtime os>`
`total_rotation_reconcile`	轮换协调总数。	`os_type=<runtime os>`，`rotated=<true or false>`
`total_rotation_reconcile_error`	总旋转次数与错误吻合。	`os_type=<runtime os>`，`rotated=<true or false>`，`error_type=<error code>`
`rotation_reconcile_duration_sec`	为 Pod 轮换机密存储内容所花费的时间的分布。	`os_type=<runtime os>`

指标是从端口 8095 提供的，但默认情况下，此端口不在 Pod 外部公开。

使用 kubectl port-forward 命令通过 localhost 访问 Secrets Store CSI 驱动程序指标。

kubectl port-forward -n kube-system ds/aks-secrets-store-csi-driver 8095:8095 &
curl localhost:8095/metrics

从开源迁移到 AKS 托管的机密存储 CSI 驱动程序

使用以下命令 helm delete 卸载开源机密存储 CSI 驱动程序。

helm delete <release name>

注意

如果使用部署 YAML 安装了驱动程序和提供程序，则可以使用 kubectl delete 以下命令删除组件：

# Delete AKV provider pods from Linux nodes
kubectl delete -f https://raw.githubusercontent.com/Azure/secrets-store-csi-driver-provider-azure/master/deployment/provider-azure-installer.yaml

# Delete AKV provider pods from Windows nodes
kubectl delete -f https://raw.githubusercontent.com/Azure/secrets-store-csi-driver-provider-azure/master/deployment/provider-azure-installer-windows.yaml

使用命令az aks enable-addons并将参数--addons设置为azure-keyvault-secrets-provider，以升级现有 AKS 群集并启用该功能。以下示例为资源组myAKSCluster中命名myResourceGroup的现有 AKS 群集启用加载项：
```
az aks enable-addons --addons azure-keyvault-secrets-provider --name myAKSCluster --resource-group myResourceGroup
```

若要详细了解或排查适用于机密存储 CSI 驱动程序的 Azure Key Vault 提供程序的问题，请参阅以下资源：

Last updated on 2026-02-05

Condividi tramite