将密钥管理服务（KMS）etcd 加密添加到 Azure Kubernetes 服务（AKS）群集（旧版）

重要

本文介绍 AKS 的旧 KMS 体验。对于运行 Kubernetes 版本 1.33 或更高版本的新群集，我们建议使用新的 KMS 数据加密体验，该体验提供平台管理的密钥、具有自动密钥轮换的客户管理的密钥以及简化的配置体验。

有关数据加密选项的概念信息，请参阅 AKS 的静态数据加密概念。

本文介绍如何使用 Azure Key Vault 和 AKS 上的密钥管理服务（KMS）插件为公钥或私钥保管库启用静态加密。可以使用 KMS 插件执行以下操作：

使用密钥保管库中的密钥进行 etcd 加密。
自带密钥。
为存储在 etcd 中的机密提供静态加密。
轮换密钥保管库中的密钥。

有关使用 KMS 的详细信息，请参阅使用 KMS 提供程序进行数据加密。

先决条件

具有活动订阅的 Azure 帐户。创建账户。
Azure CLI 2.39.0 或更高版本。使用 az --version 命令查找版本。如需进行安装或升级，请参阅安装 Azure CLI。

警告

从 2024 年 9 月 15 日起，新订阅或以前未使用此配置的订阅的私钥保管库不再支持 Konnectivity。对于当前使用此配置或在过去 60 天内使用它的订阅，支持会持续到 AKS 版本 1.30 终止社区支持为止。

可以使用 kubectl get pods -n kube-system 来验证结果并显示 konnectivity-agent Pod 正在运行。如果 Pod 正在运行，则表示 AKS 群集正在使用 Konnectivity。使用 API 服务器 VNet 集成时，可以运行 az aks show --resource-group <resource-group-name> --name <cluster-name> 命令来验证 enableVnetIntegration 设置是否设置为 true。

限制

将 KMS etcd 加密与 AKS 集成时存在以下限制：

不支持删除密钥、密钥保管库或关联的标识。
KMS etcd 加密不适用于系统分配的托管标识。在启用该功能之前，必须设置密钥保管库访问策略。在创建群集之前，系统分配的托管标识不可用。请考虑循环依赖项。
由于防火墙阻止从 KMS 插件到 Key Vault 的流量，因此不支持两种方案。无法使用防火墙选项配置 Azure Key Vault ，允许从特定虚拟网络和 IP 地址进行公共访问。
启用了 KMS 的群集支持的最大机密数为 2,000。但是，请务必注意，KMS v2 不受此限制的限制，它可以处理更多机密。
不支持来自其他租户的自带 (BYO) Azure Key Vault。
启用 KMS 后，无法更改关联的密钥保管库模式（公共模式与专用模式）。若要更新密钥保管库模式，必须先禁用 KMS，然后再次启用它。
如果群集已启用 KMS 并且具有私钥保管库，则必须使用 [API Server VNet 集成][api-server-vnet-integration] 隧道。不支持 Konnectivity。
使用 Microsoft Azure 虚拟机规模集 API 将群集中的节点纵向缩减为零会解除分配节点。然后，群集将出现故障并变得不可恢复。
关闭 KMS 后，无法删除或过期密钥。此类行为会导致 API 服务器停止工作。
对于启用了 KMS 的专用群集和使用私钥保管库的虚拟网络集成，网络安全组（NSG）必须允许从 API 服务器到私钥保管库的专用终结点 IP 地址的 TCP 端口 443。在 API 子网 NSG 或群集子网 NSG 中使用其他规则时，需要考虑此限制。

为公共密钥保管库创建密钥保管库和密钥

以下部分介绍如何为公共密钥保管库启用 KMS。可以在使用或不使用 Azure 基于角色的访问控制（Azure RBAC）的情况下使用公钥保管库。

警告

不支持删除密钥或密钥保管库，导致群集中的机密无法恢复。

如果需要恢复密钥保管库或密钥，请参阅使用软删除和清除保护进行 Azure Key Vault 恢复管理。

使用 Azure RBAC 创建密钥保管库和密钥
在没有 Azure RBAC 的情况下创建密钥保管库和密钥

使用 az keyvault create 命令通过 Azure RBAC 创建密钥保管库。此示例命令还会将密钥保管库资源 ID 导出到环境变量。

export KEY_VAULT_RESOURCE_ID=$(az keyvault create --name $KEY_VAULT --resource-group $RESOURCE_GROUP  --enable-rbac-authorization true --query id -o tsv)

使用 az role assignment create 命令为自己分配创建密钥的权限。此示例将 Key Vault Crypto Officer 角色分配给已登录用户。

az role assignment create --role "Key Vault Crypto Officer" --assignee-object-id $(az ad signed-in-user show --query id -o tsv) --assignee-principal-type "User" --scope $KEY_VAULT_RESOURCE_ID

使用 az keyvault key create 命令创建密钥。

az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT

获取密钥 ID，并使用命令将其另存为环境变量 az keyvault key show 。

export KEY_ID=$(az keyvault key show --name $KEY_NAME --vault-name $KEY_VAULT --query 'key.kid' -o tsv)
echo $KEY_ID

使用命令创建没有 Azure RBAC 的 az keyvault create 密钥保管库。
```
az keyvault create --name $KEY_VAULT --resource-group $RESOURCE_GROUP
```

使用 az keyvault key create 命令创建密钥。

az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT

使用 az keyvault key show 命令将密钥 ID 导出到环境变量。

export KEY_ID=$(az keyvault key show --name $KEY_NAME --vault-name $KEY_VAULT --query 'key.kid' -o tsv)
echo $KEY_ID

为公共密钥保管库创建用户分配的托管标识

使用 az identity create 命令创建用户分配的托管标识。

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

获取标识对象 ID，并使用命令将其另存为环境变量 az identity show 。

export IDENTITY_OBJECT_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'principalId' -o tsv)
echo $IDENTITY_OBJECT_ID

获取标识资源 ID，并使用命令将其另存为环境变量 az identity show 。

export IDENTITY_RESOURCE_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'id' -o tsv)
echo $IDENTITY_RESOURCE_ID

分配用于解密和加密公共密钥保管库的权限

以下部分介绍如何使用或不使用 Azure RBAC 分配公钥保管库的解密和加密权限。

使用 Azure RBAC 分配公钥保管库的权限
在没有 Azure RBAC 的情况下为公钥保管库分配权限

分配 Key Vault Crypto User 角色，以使用 az role assignment create 命令授予解密和加密权限。

az role assignment create --role "Key Vault Crypto User" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type "ServicePrincipal" --scope $KEY_VAULT_RESOURCE_ID

创建 Azure Key Vault 策略，以使用 az keyvault set-policy 命令授予解密和加密权限。

az keyvault set-policy --name $KEY_VAULT --key-permissions decrypt encrypt --object-id $IDENTITY_OBJECT_ID

为 AKS 群集上的公钥保管库启用 KMS

以下部分介绍如何在新的或现有的 AKS 群集上为公钥保管库启用 KMS。

使用公钥保管库和 KMS 创建 AKS 群集

使用 az aks create 命令和参数 --enable-azure-keyvault-kms、--azure-keyvault-kms-key-vault-network-access、--azure-keyvault-kms-key-id 创建一个包含公钥库和 KMS 的 AKS 集群。

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --assign-identity $IDENTITY_RESOURCE_ID \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-vault-network-access "Public" \
    --azure-keyvault-kms-key-id $KEY_ID \
    --generate-ssh-keys

在现有 AKS 群集上启用公钥保管库和 KMS

使用az aks update命令和--enable-azure-keyvault-kms--azure-keyvault-kms-key-vault-network-access--azure-keyvault-kms-key-id参数在现有群集上的公钥保管库上启用 KMS。

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-vault-network-access "Public" \
    --azure-keyvault-kms-key-id $KEY_ID

使用 kubectl get secrets 命令更新所有机密，以确保之前创建的机密不再加密。对于较大的群集，可能需要按命名空间细分机密或创建更新脚本。如果上一个更新 KMS 命令失败，仍运行以下命令以避免 KMS 插件出现意外状态。
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
运行命令时，可以忽略以下错误：
```
The object has been modified; please apply your changes to the latest version and try again.
```

轮换公共密钥保管库中的现有密钥

更改密钥 ID（包括更改密钥名称或密钥版本）后，可以轮换公钥保管库中的现有密钥。

警告

请记住在密钥轮换后更新所有机密。如果未更新所有机密，则如果之前创建的密钥不存在或不再有效，则无法访问这些机密。

KMS 同时使用两个密钥。第一次密钥轮换后，需要确保旧密钥和新密钥在下次密钥轮换之前有效（未过期）。第二个密钥轮换后，可以安全地删除/过期最早的密钥。

在使用新 keyId 版本轮换 KMS 密钥版本后，请检查 AKS 资源 json 中的 securityProfile.azureKeyVaultKms.keyId。确保使用新的密钥版本。

使用az aks update命令和--enable-azure-keyvault-kms--azure-keyvault-kms-key-vault-network-access--azure-keyvault-kms-key-id参数轮换现有密钥。

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-vault-network-access "Public" \
    --azure-keyvault-kms-key-id $NEW_KEY_ID

使用 kubectl get secrets 命令更新所有机密，以确保之前创建的机密不再加密。对于较大的群集，可能需要按命名空间细分机密或创建更新脚本。如果上一个更新 KMS 命令失败，仍运行以下命令以避免 KMS 插件出现意外状态。
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
运行命令时，可以忽略以下错误：
```
The object has been modified; please apply your changes to the latest version and try again.
```

为私钥保管库创建密钥保管库和密钥

如果已为专用密钥保管库启用 KMS，则 AKS 会自动在节点资源组中创建专用终结点和专用链接。密钥保管库通过专用端点与 AKS 群集连接。

警告

使用私钥保管库时，请记住以下信息：

KMS 仅在使用私钥保管库时支持 [API 服务器 VNet 集成][api-server-vnet-integration]。
不支持在没有专用终结点的专用密钥保管库中创建或更新密钥。若要了解如何管理专用密钥保管库，请参阅使用 Azure 专用链接集成密钥保管库。
不支持删除密钥或密钥保管库，导致群集中的机密无法恢复。如果需要恢复密钥保管库或密钥，请参阅使用软删除和清除保护进行 Azure Key Vault 恢复管理。

使用具有参数的az keyvault create--public-network-access Disabled命令创建私钥保管库。

az keyvault create --name $KEY_VAULT --resource-group $RESOURCE_GROUP --public-network-access Disabled

使用 az keyvault key create 命令创建密钥。

az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT

为专用密钥保管库创建用户分配的托管标识

使用 az identity create 命令创建用户分配的托管标识。

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

获取标识对象 ID，并使用命令将其另存为环境变量 az identity show 。

export IDENTITY_OBJECT_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'principalId' -o tsv)
echo $IDENTITY_OBJECT_ID

获取标识资源 ID，并使用命令将其另存为环境变量 az identity show 。

export IDENTITY_RESOURCE_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'id' -o tsv)
echo $IDENTITY_RESOURCE_ID

分配用于解密和加密专用密钥保管库的权限

以下部分介绍如何使用或不使用 Azure RBAC 分配私钥保管库的解密和加密权限。

使用 Azure RBAC 分配私钥保管库的权限
在没有 Azure RBAC 的情况下为私钥保管库分配权限

分配 Key Vault Crypto User 角色，以使用 az role assignment create 命令授予解密和加密权限。

az role assignment create --role "Key Vault Crypto User" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type "ServicePrincipal" --scope $KEY_VAULT_RESOURCE_ID

注意

使用私钥保管库时，AKS 无法验证身份权限。在启用 KMS 之前，验证标识是否有权访问密钥保管库。

创建 Azure Key Vault 策略，以使用 az keyvault set-policy 命令授予解密和加密权限。

az keyvault set-policy --name $KEY_VAULT --key-permissions decrypt encrypt --object-id $IDENTITY_OBJECT_ID

分配用于创建专用链接的权限

对于专用密钥保管库，需要密钥保管库参与者角色才能在专用密钥保管库和群集之间创建专用链接。

使用 az role assignment create 命令分配 Key Vault 参与者角色。

az role assignment create --role "Key Vault Contributor" --assignee-object-id $IDENTITY_OBJECT_ID --assignee-principal-type "ServicePrincipal" --scope $KEY_VAULT_RESOURCE_ID

为 AKS 群集上的私钥保管库启用 KMS

以下部分介绍如何在新的或现有的 AKS 群集上为私钥保管库启用 KMS。

使用私钥保管库和 KMS 创建 AKS 群集

使用az aks create命令和--enable-azure-keyvault-kms、--azure-keyvault-kms-key-id、--azure-keyvault-kms-key-vault-network-access、--azure-keyvault-kms-key-vault-resource-id参数创建一个包含私钥保管库和 KMS 的 AKS 群集。

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --assign-identity $IDENTITY_RESOURCE_ID \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID \
    --azure-keyvault-kms-key-vault-network-access "Private" \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID \
    --generate-ssh-keys

更新现有的 AKS 群集以启用专用密钥保管库的 KMS etcd 加密

使用az aks update命令和--enable-azure-keyvault-kms--azure-keyvault-kms-key-id--azure-keyvault-kms-key-vault-network-access--azure-keyvault-kms-key-vault-resource-id参数在现有群集上的私钥保管库上启用 KMS。

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID \
    --azure-keyvault-kms-key-vault-network-access "Private" \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID

使用 kubectl get secrets 命令更新所有机密，以确保之前创建的机密不再加密。对于较大的群集，可能需要按命名空间细分机密或创建更新脚本。如果上一个更新 KMS 命令失败，仍运行以下命令以避免 KMS 插件出现意外状态。
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
运行命令时，可以忽略以下错误：
```
The object has been modified; please apply your changes to the latest version and try again.
```

轮换专用密钥保管库中的现有密钥

更改密钥 ID（包括更改密钥名称或密钥版本）后，可以轮换私钥保管库中的现有密钥。

警告

请记住在密钥轮换后更新所有机密。如果未更新所有机密，则如果之前创建的密钥不存在或不再有效，则无法访问这些机密。

轮换密钥后，仍会缓存上一个密钥 (key1)，不应删除它。如果要立即删除上一个密钥 (key1)，则需要轮换密钥两次。然后缓存 key2 和 key3，并且可以删除 key1，而不会影响现有群集。

在使用新 keyId 版本轮换 KMS 密钥版本后，请检查 AKS 资源 json 中的 securityProfile.azureKeyVaultKms.keyId。确保使用新的密钥版本。

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP  \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $NEW_KEY_ID \
    --azure-keyvault-kms-key-vault-network-access "Private" \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID

使用 kubectl get secrets 命令更新所有机密，以确保之前创建的机密不再加密。对于较大的群集，可能需要按命名空间细分机密或创建更新脚本。如果上一个更新 KMS 命令失败，仍运行以下命令以避免 KMS 插件出现意外状态。
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
运行命令时，可以忽略以下错误：
```
The object has been modified; please apply your changes to the latest version and try again.
```

在 AKS 群集上禁用 KMS

在关闭 KMS 之前，请使用 az aks list 命令验证是否已在群集上启用 KMS。

az aks list --query "[].{Name:name, KmsEnabled:securityProfile.azureKeyVaultKms.enabled, KeyId:securityProfile.azureKeyVaultKms.keyId}" -o table

确认后，可以使用带参数的az aks update--disable-azure-keyvault-kms命令禁用 KMS。

az aks update --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --disable-azure-keyvault-kms

使用 kubectl get secrets 命令更新所有机密，以确保之前创建的机密不再加密。对于较大的群集，可能需要按命名空间细分机密或创建更新脚本。如果上一个更新 KMS 命令失败，仍运行以下命令以避免 KMS 插件出现意外状态。
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
运行命令时，可以忽略以下错误：
```
The object has been modified; please apply your changes to the latest version and try again.
```

后续步骤

有关将 KMS 与 AKS 配合使用的详细信息，请参阅以下文章：

在 AKS 中启用 KMS 数据加密 - 使用平台管理的密钥和自动密钥轮换的新 KMS 体验
AKS 的数据静态加密概念
使用 KMS etcd 加密更新 Azure Kubernetes 服务（AKS）群集的密钥保管库模式
在 Azure Kubernetes 服务 (AKS) 中迁移到 KMS v2 以进行 etcd 加密
Azure Kubernetes 服务 (AKS) 中 KMS etcd 加密的可观察性

Last updated on 2026-02-05

Compartilhar via

将密钥管理服务（KMS）etcd 加密添加到 Azure Kubernetes 服务（AKS）群集（旧版）

先决条件

限制

为公共密钥保管库创建密钥保管库和密钥

为公共密钥保管库创建用户分配的托管标识

分配用于解密和加密公共密钥保管库的权限

为 AKS 群集上的公钥保管库启用 KMS

使用公钥保管库和 KMS 创建 AKS 群集

在现有 AKS 群集上启用公钥保管库和 KMS

轮换公共密钥保管库中的现有密钥

为私钥保管库创建密钥保管库和密钥

为专用密钥保管库创建用户分配的托管标识

分配用于解密和加密专用密钥保管库的权限

分配用于创建专用链接的权限

为 AKS 群集上的私钥保管库启用 KMS

使用私钥保管库和 KMS 创建 AKS 群集

更新现有的 AKS 群集以启用专用密钥保管库的 KMS etcd 加密

轮换专用密钥保管库中的现有密钥

在 AKS 群集上禁用 KMS

后续步骤

Recursos adicionais