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

  • 项目

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

配置选项

启用和禁用自动轮换

注意

当启用了适用于机密存储 CSI 驱动程序的 Azure 密钥保管库提供程序时，它会更新 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 -n myAKSCluster2 -g myResourceGroup --enable-addons azure-keyvault-secrets-provider --enable-secret-rotation

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

  • 更新现有群集，以使用 az aks addon update 命令和 enable-secret-rotation 参数启用自动轮换机密。

    az aks addon update -g myResourceGroup -n myAKSCluster2 -a azure-keyvault-secrets-provider --enable-secret-rotation

指定自定义轮换间隔

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

    az aks addon update -g myResourceGroup -n myAKSCluster2 -a azure-keyvault-secrets-provider --enable-secret-rotation --rotation-poll-interval 5m

禁用自动轮换

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

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

    az aks addon disable -g myResourceGroup -n myAKSCluster2 -a azure-keyvault-secrets-provider

  2. 使用 enable-secret-rotation 命令在不带 az aks addon enable 参数的情况下重新启用机密提供程序加载项。

    az aks addon enable -g myResourceGroup -n myAKSCluster2 -a azure-keyvault-secrets-provider

将装载的内容与 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 驱动程序

  1. 使用以下 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

  2. 使用 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 密钥保管库提供程序，请参阅以下资源：