将 Azure 身份提供商与 Azure Kubernetes 服务（AKS）中的 Azure 密钥保管库 Secrets Store CSI 驱动程序相连接

Azure Kubernetes Service（AKS）上的机密存储库容器存储接口（CSI）驱动程序为Azure 密钥保管库提供各种基于标识的访问方法。 本文概述了在访问您的密钥保管库和 AKS 群集时，何时使用 Azure 基于角色的访问控制（Azure RBAC）或 OpenID Connect（OIDC）安全模型的这些方法和最佳实践。

可以使用以下访问方法之一：

  • 具有托管标识的服务连接器
  • 工作负载 ID
  • 用户分配的托管标识

了解如何使用服务连接器，在 Azure Kubernetes Service（AKS）集群中通过 Secrets Store CSI 驱动程序，连接至 Azure 密钥保管库。 在本文中，你将完成以下任务：

  • 注册所需的 Azure 资源提供程序。
  • 使用服务连接器在 AKS 群集与Azure 密钥保管库之间创建连接。
  • 创建一个 SecretProviderClass CRD 和一个使用 CSI 提供程序的 Pod 来测试连接。
  • 验证 Pod 是否可以访问密钥保管库中的机密。

先决条件

  • 具有活动订阅的Azure帐户。 创建帐户。
  • Azure CLI。 使用 az login 命令登录。
  • Docker 和 kubectl。 若要在本地安装 kubectl，请使用 az aks install-cli 命令。
  • 对容器和 AKS 具备基础概念的了解。 从为 AKS 准备应用程序 开始。
  • 在开始之前，请确保完成《在 Azure Kubernetes 服务 (AKS) 群集上，使用 Secrets Store CSI 驱动程序的 Azure 密钥保管库 提供程序》中的步骤，以便在您的 AKS 群集上启用 Azure 密钥保管库 Secrets Store CSI 驱动程序。

初始设置

  1. 如果您是第一次使用 Service Connector，请首先运行命令 az provider register 来注册 Service Connector 和 Kubernetes 配置资源提供程序。

    az provider register -n Microsoft.ServiceLinker

    az provider register -n Microsoft.KubernetesConfiguration

    提示

    你可以通过运行命令 az provider show -n "Microsoft.ServiceLinker" --query registrationState 和 az provider show -n "Microsoft.KubernetesConfiguration" --query registrationState 来检查是否已注册这些资源提供程序。

  2. （可选）使用 Azure CLI 命令获取 AKS 群集支持的目标服务列表。

    az aks connection list-support-types --output table

使用服务连接器在 AKS 中创建服务连接

可以使用Azure portal或Azure CLI创建到Azure 密钥保管库的服务连接。

  1. 在Azure portal中，导航到 AKS 群集资源。

  2. 在服务菜单中的“设置”下，选择“服务连接器”“创建”。>

  3. 在“创建连接”页面上的“基本信息”选项卡中，配置以下设置：

    • Kubernetes 命名空间：选择“默认”。
    • Service type：选择密钥保管库复选框以启用Azure 密钥保管库 CSI 提供程序。
    • 连接名称：输入此连接的名称。
    • Subscription：选择包含密钥保管库的订阅。
    • Key vault：选择创建的key vault。
    • 客户端类型：选择“无”。

  4. 选择“查看 + 创建”，然后选择“创建”以创建连接。

测试连接

克隆示例存储库并部署清单文件

  1. 使用 git clone 命令克隆示例存储库。

    git clone https://github.com/Azure-Samples/serviceconnector-aks-samples.git

  2. 将目录更改为 Azure 密钥保管库 CSI 提供程序示例。

    cd serviceconnector-aks-samples/azure-keyvault-csi-provider

  3. 在 secret_provider_class.yaml 文件中，将以下的占位符替换为你的 Azure 密钥保管库 信息：

    • 将 <AZURE_KEYVAULT_NAME> 替换为您创建并连接的密钥库的名称。
    • 将 <AZURE_KEYVAULT_TENANTID> 替换为密钥保管库的租户 ID。
    • 用 <AZURE_KEYVAULT_CLIENTID> 加载项的身份客户端 ID 替换 azureKeyvaultSecretsProvider。
    • 将 <KEYVAULT_SECRET_NAME> 替换为您创建的密钥库机密。 例如，ExampleSecret。

  4. 使用 SecretProviderClass 命令部署 kubectl apply CRD。

    kubectl apply -f secret_provider_class.yaml

  5. 使用 Pod 命令部署 kubectl apply 清单文件。

    该命令在 AKS 群集的默认命名空间中创建名为 sc-demo-keyvault-csi 的 Pod。

    kubectl apply -f pod.yaml

验证连接

  1. 使用 kubectl get 命令验证是否已成功创建 Pod。

    kubectl get pod/sc-demo-keyvault-csi

    Pod 启动后，在部署 YAML 中指定的卷路径上装载的内容便可用了。

  2. 使用 kubectl exec 命令显示机密存储中保存的机密。

    kubectl exec sc-demo-keyvault-csi -- ls /mnt/secrets-store/

  3. 使用 kubectl exec 命令显示一个机密。

    此示例命令显示名为 ExampleSecret 的测试机密。

    kubectl exec sc-demo-keyvault-csi -- cat /mnt/secrets-store/ExampleSecret

具有工作负荷标识的 CSI 驱动程序的先决条件

  • 在开始之前，请确保完成《在 Azure Kubernetes 服务 (AKS) 群集上，使用 Secrets Store CSI 驱动程序的 Azure 密钥保管库 提供程序》中的步骤，以便在您的 AKS 群集上启用 Azure 密钥保管库 Secrets Store CSI 驱动程序。
  • Microsoft Entra Workload ID同时支持 Windows 和 Linux 群集。

通过 Microsoft Entra Workload ID 进行访问

Microsoft Entra Workload ID是应用程序或服务用来针对其他Azure服务（例如软件中的工作负载）进行身份验证的标识。 机密存储 CSI 驱动程序与 Kubernetes 原生功能集成，以实现与外部身份提供程序的联合身份验证。

在此安全模型中，AKS 群集充当令牌颁发者。 当 Secrets Store CSI 驱动程序挂载卷时，它会请求 Kubernetes 服务账户令牌，而 Azure 密钥保管库 提供程序会用该令牌换取 Microsoft Entra 令牌。 应用程序读取已挂载的文件，在这种卷挂载流程中不需要 Azure 标识客户端库或 Microsoft 身份验证库 (MSAL)。 如果应用程序需要自行请求 Microsoft Entra 令牌来调用受保护的 API，请在应用程序中使用 Azure Identity 或 MSAL。

注意事项

  • 此身份验证方法取代了 Microsoft Entra Pod 托管标识（预览版）。 自 2022 年 10 月 24 日起，Azure Kubernetes 服务 中的开源 Microsoft Entra 由 pod 管理的标识（预览版）已被弃用。
  • Microsoft Entra Workload ID同时支持 Windows 和 Linux 群集。

配置工作负载标识

  1. 使用 az account set 命令设置订阅。

    export SUBSCRIPTION_ID=<subscription id>
export RESOURCE_GROUP=<resource group name>
export UAMI=<name for user assigned identity>
export KEYVAULT_NAME=<existing keyvault name>
export CLUSTER_NAME=<aks cluster name>

az account set --subscription $SUBSCRIPTION_ID

  2. 使用 az identity create 命令创建托管标识。

    注意事项

    此步骤假定你拥有已启用工作负荷标识的现有 AKS 群集。 如果未启用工作负荷标识，请参阅 在现有 AKS 群集上启用工作负荷标识 以启用它。

    az identity create --name $UAMI --resource-group $RESOURCE_GROUP

export USER_ASSIGNED_CLIENT_ID="$(az identity show --resource-group $RESOURCE_GROUP --name $UAMI --query 'clientId' -o tsv)"
export KEYVAULT_TENANT_ID="$(az keyvault show --name $KEYVAULT_NAME --query properties.tenantId -o tsv)"

  3. 创建一个角色分配，通过 az role assignment create 命令授予工作负载身份访问机密、密钥保管库的密钥和证书的权限。

    重要

    • 如果你将密钥保管库设置为 --enable-rbac-authorization，并且使用的是 key 或 cert 类型，请分配 密钥保管库 Certificate User 角色以授予权限。
    • 如果将密钥库设置为--enable-rbac-authorization，并且使用secret 类型，请分配密钥保管库 Secrets User 角色。
    • 如果未使用 --enable-rbac-authorization 设置密钥保管库，则可以将 az keyvault set-policy 命令与 --key-permissions get、--certificate-permissions get 或 --secret-permissions get 参数一起使用，以创建密钥保管库策略来为密钥、证书或机密授予访问权限。 例如：
    az keyvault set-policy --name $KEYVAULT_NAME --key-permissions get --secret-permissions get --object-id <identity-object-id>

    export KEYVAULT_SCOPE=$(az keyvault show --name $KEYVAULT_NAME --query id -o tsv)

# Example commands for a key vault with Azure RBAC enabled using `key` and `secret` types
az role assignment create --role "Key Vault Certificate User" --assignee $USER_ASSIGNED_CLIENT_ID --scope $KEYVAULT_SCOPE
az role assignment create --role "Key Vault Secrets User" --assignee $USER_ASSIGNED_CLIENT_ID --scope $KEYVAULT_SCOPE

  4. 使用 az aks show 命令获取 AKS 群集 OIDC 颁发者 URL。

    注意事项

    此步骤假定你已有启用了 OIDC 颁发者 URL 的现有 AKS 群集。 如果 OIDC 颁发者 URL 尚未启用，请参阅 更新 AKS 群集以启用 OIDC 颁发者。

    export AKS_OIDC_ISSUER="$(az aks show --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --query "oidcIssuerProfile.issuerUrl" -o tsv)"
echo $AKS_OIDC_ISSUER

  5. 为工作负荷创建 Kubernetes 服务帐户。 将 SERVICE_ACCOUNT_NAME 和 SERVICE_ACCOUNT_NAMESPACE 的值分别更新为 Kubernetes 服务账号名称及其命名空间。

    export SERVICE_ACCOUNT_NAME="workload-identity-sa"  # sample name; can be changed
export SERVICE_ACCOUNT_NAMESPACE="default" # can be changed to namespace of your workload

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    azure.workload.identity/client-id: ${USER_ASSIGNED_CLIENT_ID}
  name: ${SERVICE_ACCOUNT_NAME}
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
EOF

  6. 使用 az identity federated-credential create 命令在托管标识、服务帐户颁发者和使用者之间创建联合标识凭据。

    export FEDERATED_IDENTITY_NAME="aksfederatedidentity" # can be changed as needed

az identity federated-credential create --name $FEDERATED_IDENTITY_NAME --identity-name $UAMI --resource-group $RESOURCE_GROUP --issuer ${AKS_OIDC_ISSUER} --subject system:serviceaccount:${SERVICE_ACCOUNT_NAMESPACE}:${SERVICE_ACCOUNT_NAME}

  7. 使用 SecretProviderClass 命令和以下 YAML 脚本部署 kubectl apply。

以下参数用于配置工作负载身份访问：

  • usePodIdentity：使用工作负载标识时，将其设置为 "false"。

  • clientID：设置为 ${USER_ASSIGNED_CLIENT_ID}，用于工作负荷标识的用户分配托管标识的客户端 ID。

  • cloudName：可选。 留空以使用默认 AzurePublicCloud 环境。

  • objectType：设置为要装载密钥保管库对象的类型。 有效值为：secret、key 和 cert。

  • tenantId：设置为包含密钥保管库的租户 ID。

    cat <<EOF | kubectl apply -f -
# This is a SecretProviderClass example using workload identity to access your key vault
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: azure-kvname-wi # needs to be unique per namespace
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    clientID: "${USER_ASSIGNED_CLIENT_ID}" # Setting this to use workload identity
    keyvaultName: ${KEYVAULT_NAME}       # Set to the name of your key vault
    cloudName: ""                         # [OPTIONAL for Azure] if not provided, the Azure environment defaults to AzurePublicCloud
    objects:  |
      array:
        - |
          objectName: secret1             # Set to the name of your secret
          objectType: secret              # object types: secret, key, or cert
          objectVersion: ""               # [OPTIONAL] object versions, default to latest if empty
        - |
          objectName: key1                # Set to the name of your key
          objectType: key
          objectVersion: ""
    tenantId: "${KEYVAULT_TENANT_ID}"     # The tenant ID of the key vault
EOF

    注意事项

    如果使用 objectAlias 而不是 objectName，请更新 YAML 脚本以进行解释。

    注意事项

    为了使 SecretProviderClass 正常工作，请确保先使用机密、密钥或证书填充 Azure 密钥保管库，然后再在 objects 节中引用它们。

  1. 使用 kubectl apply 命令和以下 YAML 脚本部署一个示例 pod。

    cat <<EOF | kubectl apply -f -
# This is a sample pod definition for using SecretProviderClass and workload identity to access your key vault
kind: Pod
apiVersion: v1
metadata:
  name: busybox-secrets-store-inline-wi
  namespace: ${SERVICE_ACCOUNT_NAMESPACE}
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: ${SERVICE_ACCOUNT_NAME}
  containers:
    - name: busybox
      image: k8sgcr.azk8s.cn/e2e-test-images/busybox:1.29-4
      command:
        - "/bin/sleep"
        - "10000"
      volumeMounts:
      - name: secrets-store01-inline
        mountPath: "/mnt/secrets-store"
        readOnly: true
  volumes:
    - name: secrets-store01-inline
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: "azure-kvname-wi"
EOF

使用工作负荷标识验证密钥保管库机密

Pod 启动后，挂载到 /mnt/secrets-store 的内容即可使用。 使用以下命令验证机密并打印测试机密。

  1. 使用以下命令显示机密存储中保存的机密。

    kubectl exec --namespace $SERVICE_ACCOUNT_NAMESPACE busybox-secrets-store-inline-wi -- ls /mnt/secrets-store/

  2. 使用以下命令显示存储库中的机密。 此示例命令会显示测试机密 secret1。

    kubectl exec --namespace $SERVICE_ACCOUNT_NAMESPACE busybox-secrets-store-inline-wi -- cat /mnt/secrets-store/secret1

具有托管标识的 CSI 驱动程序的先决条件

  • 在开始之前，请确保完成《在 Azure Kubernetes 服务 (AKS) 群集上，使用 Secrets Store CSI 驱动程序的 Azure 密钥保管库 提供程序》中的步骤，以便在您的 AKS 群集上启用 Azure 密钥保管库 Secrets Store CSI 驱动程序。

使用托管标识的访问

此方法使用的是用户在为 Secrets Store CSI Driver 启用 Azure 密钥保管库 提供程序时，AKS 自动创建的用户分配的托管标识。 标识命名 azurekeyvaultsecretsprovider-xxxxx，存储在节点资源组中，并分配给虚拟机规模集。

Microsoft Entra托管标识使Azure资源或工作负荷能够向支持Microsoft Entra身份验证的服务进行身份验证，而无需在代码中存储凭据。 通过 Azure RBAC 或访问策略向此标识授予适当的 密钥保管库 数据平面权限，然后在以下步骤中使用该标识。

配置托管标识

  1. 使用加载项创建的用户分配的托管标识，通过 az aks show 命令访问您的密钥保管库。 你还应检索标识的 clientId，以便在后续步骤中在创建 SecretProviderClass 时使用。

    export RESOURCE_GROUP=<resource-group>
export CLUSTER_NAME=<cluster-name>
export KEYVAULT_NAME=<key-vault-name>

export IDENTITY_OBJECT_ID=$(az aks show --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --query addonProfiles.azureKeyvaultSecretsProvider.identity.objectId -o tsv)
export USER_ASSIGNED_CLIENT_ID=$(az aks show --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --query addonProfiles.azureKeyvaultSecretsProvider.identity.clientId -o tsv)

    或者，可以创建新的托管标识，并将其分配给虚拟机（VM）规模集或可用性集中的每个 VM 实例。

    export USER_ASSIGNED_IDENTITY_NAME=<identity-name>

az identity create --resource-group $RESOURCE_GROUP --name $USER_ASSIGNED_IDENTITY_NAME

export IDENTITY_RESOURCE_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $USER_ASSIGNED_IDENTITY_NAME --query id -o tsv)
export IDENTITY_OBJECT_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $USER_ASSIGNED_IDENTITY_NAME --query principalId -o tsv)
export USER_ASSIGNED_CLIENT_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $USER_ASSIGNED_IDENTITY_NAME --query clientId -o tsv)

    对于基于虚拟机规模集的群集，请将标识分配给虚拟机规模集。

    az vmss identity assign --resource-group <node-resource-group> --name <agent-pool-vmss> --identities $IDENTITY_RESOURCE_ID

    对于基于可用性集的群集，请将标识分配给可用性集中的每个 VM 实例。

    az vm identity assign --resource-group <node-resource-group> --name <agent-pool-vm> --identities $IDENTITY_RESOURCE_ID

  2. 创建一个角色分配，该角色分配使用 az role assignment create 命令授予标识访问 key vault 机密、访问密钥和证书的权限。

    重要

    • 如果你使用 --enable-rbac-authorization 设置了密钥保管库，并且使用的是 key 或 cert 类型，请分配 密钥保管库 Certificate User 角色。
    • 如果将密钥库设置为--enable-rbac-authorization，并且使用secret 类型，请分配密钥保管库 Secrets User 角色。
    • 如果未使用 --enable-rbac-authorization 设置密钥保管库，则可以将 az keyvault set-policy 命令与 --key-permissions get、--certificate-permissions get 或 --secret-permissions get 参数一起使用，以创建密钥保管库策略来为密钥、证书或机密授予访问权限。 例如：
    az keyvault set-policy --name $KEYVAULT_NAME --key-permissions get --secret-permissions get --object-id $IDENTITY_OBJECT_ID

    export KEYVAULT_SCOPE=$(az keyvault show --name $KEYVAULT_NAME --query id -o tsv)

# Example commands for a key vault with Azure RBAC enabled using `key` and `secret` types
az role assignment create --role "Key Vault Certificate User" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type ServicePrincipal --scope $KEYVAULT_SCOPE
az role assignment create --role "Key Vault Secrets User" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type ServicePrincipal --scope $KEYVAULT_SCOPE

  3. 使用标识客户端 ID 创建一个 SecretProviderClass 。 请确保对要从密钥保管库中检索的对象使用自己的值。

    以下参数用于配置对用户分配的托管标识的访问：

    • usePodIdentity：使用托管标识时，将其设置为 "false"。
    • useVMManagedIdentity：将其设置为 "true" 以启用托管标识模式。
    • userAssignedIdentityID：设置为用户分配的托管标识的客户端 ID。
    • tenantId：设置为包含密钥保管库的租户 ID。
    export KEYVAULT_TENANT_ID=$(az keyvault show --name $KEYVAULT_NAME --query properties.tenantId -o tsv)

cat <<EOF > secretproviderclass.yaml
# This is a SecretProviderClass example using user-assigned identity to access your key vault
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: azure-kvname-user-msi
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    useVMManagedIdentity: "true"          # Set to true for using managed identity
    userAssignedIdentityID: ${USER_ASSIGNED_CLIENT_ID} # Set the client ID of the user-assigned managed identity to use
    keyvaultName: ${KEYVAULT_NAME}         # Set to the name of your key vault
    cloudName: ""                         # [OPTIONAL for Azure] if not provided, the Azure environment defaults to AzurePublicCloud
    objects:  |
      array:
        - |
          objectName: secret1
          objectType: secret              # object types: secret, key, or cert
          objectVersion: ""               # [OPTIONAL] object versions, default to latest if empty
        - |
          objectName: key1
          objectType: key
          objectVersion: ""
    tenantId: ${KEYVAULT_TENANT_ID}       # The tenant ID of the key vault
EOF

    注意事项

    如果使用 objectAlias 而不是 objectName，请务必更新 YAML 脚本。

    注意事项

    为了使 SecretProviderClass 正常工作，请确保先使用机密、密钥或证书填充 Azure 密钥保管库，然后再在 objects 节中引用它们。

  4. 使用 SecretProviderClass 命令将 kubectl apply 应用到群集。

    kubectl apply -f secretproviderclass.yaml

  5. 使用以下命令创建名为 pod.yaml 的 Pod 清单。

    cat <<EOF > pod.yaml
# This is a sample pod definition for using SecretProviderClass and the user-assigned identity to access your key vault
kind: Pod
apiVersion: v1
metadata:
  name: busybox-secrets-store-inline-user-msi
spec:
  containers:
    - name: busybox
      image: k8sgcr.azk8s.cn/e2e-test-images/busybox:1.29-4
      command:
        - "/bin/sleep"
        - "10000"
      volumeMounts:
      - name: secrets-store01-inline
        mountPath: "/mnt/secrets-store"
        readOnly: true
  volumes:
    - name: secrets-store01-inline
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: "azure-kvname-user-msi"
EOF

  6. 使用 kubectl apply 命令将 Pod 应用到群集。

    kubectl apply -f pod.yaml

使用托管标识验证密钥保管库机密

Pod 启动后，即可使用挂载到 /mnt/secrets-store 的内容。 使用以下命令验证机密并打印测试机密。

  1. 使用以下命令显示机密存储中保存的机密。

    kubectl exec busybox-secrets-store-inline-user-msi -- ls /mnt/secrets-store/

  2. 使用以下命令显示存储库中的机密。 此示例命令会显示测试机密 secret1。

    kubectl exec busybox-secrets-store-inline-user-msi -- cat /mnt/secrets-store/secret1

获取证书和密钥

Azure 密钥保管库设计区分密钥、机密和证书。 密钥保管库服务的证书功能旨在利用密钥和机密功能。 创建密钥库证书时，它会创建一个具有相同名称的可寻址密钥和机密。 密钥允许身份验证操作，机密允许以机密形式检索证书值。

key vault证书还包含公开的 x509 证书元数据。 密钥保管库将证书的公用和私用组件存储在机密存储中。 可以通过在 objectType 中指定 SecretProviderClass 来获取每个单独的组成部分。 下表显示了可在 SecretProviderClass 中指定的 objectType 值，用于检索密钥保管库证书的不同组成部分，以及每个值返回的内容：

objectType 值 返回值 返回整个证书链
key 采用隐私增强邮件 (PEM) 格式的公钥。 不可用
cert 采用 PEM 格式的证书。 否
secret 采用 PEM 格式的私钥和证书。 是

在现有群集上禁用加载项

注意事项

在禁用该加载项之前，请确保没有人使用它。 当存在 SecretProviderClass 时尝试禁用该加载项会导致出错。

使用 az aks disable-addons 命令和 azure-keyvault-secrets-provider 加载项，在现有集群中禁用 Azure 密钥保管库 提供程序的 Secrets Store CSI 驱动程序功能。

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

注意事项

在禁用加载项时，现有工作负载不应该遇到问题，也不应看到已装载的机密有任何更新。 如果 Pod 重启，或作为纵向扩展事件的一部分创建新 Pod，该 Pod 将无法启动，因为驱动程序已不再运行。

后续步骤

本文介绍了如何创建和配置身份以访问 Azure 密钥库。

若要配置额外的配置选项或进行故障排除，请参阅 关于在 AKS 中使用 Secrets Store CSI 驱动程序的 Azure 密钥保管库 提供程序的配置选项和故障排除资源。

  • Last updated on