用于机密存储 CSI 驱动程序的 Azure Key Vault 提供程序，用于 AKS 配置和故障排除选项

用于机密存储容器存储接口（CSI）驱动程序的 Azure Key Vault 提供程序能够在 Azure Kubernetes 服务（AKS）中安全地、自动化地管理机密。本文提供有关在 AKS 环境中配置提供程序、排查常见问题和优化机密处理的指导。

先决条件

在继续阅读本指南之前，请按照以下文章中的步骤进行并完成这些步骤，然后再继续阅读本指南。完成这些步骤后，可以在 AKS 群集上应用额外配置或执行故障排除。

配置选项

管理自动轮换

启用 Azure Key Vault Secrets 提供程序的自动轮换后，它会更新 Pod 挂载和 Kubernetes 中secretObjects字段内定义的SecretProviderClass 机密。它通过根据你定义的轮换轮询间隔定期轮询更改来实现此目的。默认的轮换轮询间隔为两分钟。在初始 Pod 部署后，如果外部机密存储中的机密被更新，Kubernetes Secret 和 Pod 的挂载会定期刷新。更新频率和方法取决于应用程序访问机密数据的方式。

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

若要使用 az aks create 命令在新 AKS 群集上启用机密自动轮换并启用 enable-secret-rotation 加载项，请运行以下命令：

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

若要更新现有 AKS 群集以使用 az aks addon update 命令和 enable-secret-rotation 参数自动轮换机密，请运行以下命令：

az aks addon update --resource-group myResourceGroup --name myAKSCluster2 --addon azure-keyvault-secrets-provider --enable-secret-rotation

若要关闭自动旋转功能，首先需要禁用插件。然后，可以在没有 enable-secret-rotation 参数的情况下重新启用加载项。

使用 az aks addon disable 命令禁用 Secrets Provider 插件：

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

在不使用enable-secret-rotation参数的情况下，使用az aks addon enable命令重新启用机密提供程序加载项：
```
az aks addon enable --resource-group myResourceGroup --name myAKSCluster2 --addon azure-keyvault-secrets-provider
```

如果你正在使用SecretProviderClass，可以在不指定az aks addon enable参数的情况下使用enable-secret-rotation更新加载项，而无需先禁用它。

若要使用具有参数的az aks addon updaterotation-poll-interval命令指定自定义旋转间隔，请运行以下命令：

az aks addon update --resource-group myResourceGroup --name myAKSCluster2 --addon azure-keyvault-secrets-provider --enable-secret-rotation --rotation-poll-interval 5m

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

注意

本部分中的 YAML 示例不是完整的。需要对其进行修改以支持所选的密钥保管库标识访问方法。有关详细信息，请参阅提供标识以访问适用于机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序。

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

在创建 secretObjects 以定义 Kubernetes 机密的所需状态时，使用 SecretProviderClass 字段将已装载的内容与 Kubernetes 机密同步，如以下示例 YAML 所示。确保 objectName 字段中的 secretObjects 与所装载内容的文件名匹配。如果改用 objectAlias，则它应匹配对象别名。

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)

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

注意

示例 YAML 演示如何通过环境变量或 volume/volumeMount 来访问秘密。通常，应用程序使用一种方法或其他方法。但是，若要通过环境变量提供机密，至少一个 Pod 必须装载机密。

通过在 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"

从开源迁移到 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 命令，通过特性升级现有的 AKS 群集。

az aks enable-addons --addons azure-keyvault-secrets-provider --name myAKSCluster --resource-group myResourceGroup

可以通过收集它公开的指标来监视适用于机密存储 CSI 驱动程序的 Azure Key Vault 提供程序的运行状况和性能。这些指标提供对请求持续时间、错误率和提供程序和驱动程序组件的整体作的见解，帮助你排查问题并优化 AKS 群集的机密管理。

指标是通过 Prometheus 从端口 8898 提供的，但默认情况下此端口不会在 Pod 外部公开。使用 kubectl port-forward 命令，通过 localhost 访问度量数据：

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

这些指标有助于监视 Azure Key Vault 提供程序的性能和可靠性，包括密钥保管库和 gRPC 操作的请求延迟和错误跟踪。

指标	说明	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>`

指标是从端口 8095 提供的，但默认情况下，此端口不在 Pod 外部公开。使用 kubectl port-forward 命令，通过 localhost 访问度量数据：

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

这些指标提供对 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>`

疑难解答

有关故障排除步骤，请参阅故障排除适用于机密存储 CSI 驱动程序的 Azure Key Vault 提供程序。

后续步骤

要详细了解适用于机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序，请参阅以下资源：

Last updated on 2025-12-31

通过