你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

用于适用于 Azure Kubernetes 服务 (AKS) 的机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序的配置和故障排除选项

项目
01/03/2025

请按照在 AKS 群集中使用适用于机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序和在 AKS 中提供用于访问适用于机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序的标识中的步骤进行操作。完成这些步骤后，可以应用额外配置或执行故障排除。

配置选项

启用和禁用自动轮换

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

当初始 Pod 部署后在外部机密存储中更新机密时，将根据应用程序使用机密数据的方式定期更新 Kubernetes 机密和 Pod 装载。

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

在新 AKS 群集上启用自动轮换

使用 az aks create 命令在新群集上启用机密的自动轮换，并启用 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

指定自定义轮换间隔

使用带有 rotation-poll-interval 参数的 az aks addon update 命令指定自定义轮换间隔。

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

禁用自动轮换

要禁用自动轮换，首先需要禁用加载项。然后，可以在没有 enable-secret-rotation 参数的情况下重新启用加载项。

使用 az aks addon disable 命令禁用机密提供程序加载项。

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 参数无需先禁用加载项即可更新加载项。

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

注意

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

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

在创建 SecretProviderClass 以定义 Kubernetes 机密的所需状态时，使用 secretObjects 字段将已装载的内容与 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)

注意

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

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

注意

示例 YAML 演示了如何通过 env 变量和 volume/volumeMount 访问机密。此示例用于说明用途。典型的应用程序将使用一种方法或另一种方法。但是，请注意，为了可通过 env 变量使用机密，它首先必须由至少一个 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"

访问指标

Azure 密钥保管库提供程序

指标是通过 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

适用于机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序提供的指标

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

机密存储 CSI 驱动程序

指标是从端口 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>`
total_rotation_reconcile_error	为 Pod 轮换机密存储内容所花费的时间的分布。	`os_type=<runtime os>`

从开源迁移到 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 提供程序。

后续步骤

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

通过