將金鑰管理服務 etcd 加密新增至 Azure Kubernetes Service 叢集

發行項
12/18/2024

本文顯示如何使用 Azure Key Vault 和金鑰管理服務 (KMS) 外掛程式，針對 etcd key-value 存放區中的 Azure Kubernetes Service (AKS) 祕密開啟待用加密。您可以使用 KMS 外掛程式來：

在金鑰保存庫中使用金鑰進行 etcd 加密。
自備金鑰。
針對 etcd 中所儲存的祕密，提供待用加密。
輪替金鑰保存庫中的金鑰。

如需使用 KMS 的詳細資訊，請參閱使用 KMS 提供者進行資料加密。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
Azure CLI 2.39.0 版或更新版本。執行 az --version 來尋找您的版本。如果您需要安裝或升級，請參閱安裝 Azure CLI 模組。

警告

從 2024 年 9 月 15 日起，新的訂用帳戶或先前未使用此設定的訂用帳戶，不再支援 Konnectivity 的私鑰保存庫。對於目前使用此設定或在過去 60 天內使用它的訂用帳戶，支援會持續到 AKS 1.30 版終止社群支持為止。

KMS 支援公鑰保存庫的 Konnectivity 或 API Server VNet 整合（預覽）。

KMS 支援私人和公鑰保存庫的 API Server VNet 整合（預覽）。

您可以使用 kubectl get po -n kube-system 來確認結果，並顯示 konnectivity-agent Pod 正在執行。如果 Pod 正在執行，則 AKS 叢集正在使用 Konnectivity。當您使用 API Server VNet 整合時，可以執行 az aks show -g -n 命令來確認 enableVnetIntegration 設定設定為 true。

限制

您整合 KMS etcd 加密與 AKS 時，適用下列限制：

不支援刪除金鑰、金鑰保存庫或相關聯的身分識別。
KMS etcd 加密不適用於系統指派的受控識別。開啟此功能之前，必須設定金鑰保存庫存取原則。除非在建立叢集之後，否則無法使用系統指派的受控識別。請考慮週期相依性。
不支援具有防火牆設定「允許來自特定虛擬網路和 IP 位址的公用存取」或「停用公用存取」的 Azure Key Vault，因為會封鎖來自 KMS 外掛程式到金鑰保存庫的流量。
已開啟 KMS 的叢集所支援的祕密數目上限為 2,000。不過，請務必注意，KMS v2 不受此限制的限制，而且可以處理較多的祕密數目。
不支援另一個租用戶的自備 (BYO) Azure Key Vault。
開啟 KMS 後，您無法變更相關聯的金鑰保存庫模式 (公用與私人)。若要更新金鑰保存庫模式，您必須先關閉 KMS，然後再將其開啟。
如果叢集已開啟 KMS 且具有私密金鑰保存庫，則必須使用 API Server VNet 整合 (預覽) 通道。不支援 Konnectivity。
使用虛擬機擴展集 API 以將叢集中的節點減小為零，會解除配置節點。叢集接著會關閉，並變成無法復原。
關閉 KMS 之後，您就無法終結金鑰。終結金鑰會導致 API 伺服器停止運作。

KMS 支援公用金鑰保存庫和私人金鑰保存庫。

開啟公用金鑰保存庫的 KMS

下列各節描述如何開啟公用金鑰保存庫的 KMS。

建立私人金鑰保存庫和金鑰

警告

不支援刪除金鑰或金鑰保存庫，這樣做會導致叢集中的祕密無法復原。

如果您需要復原金鑰保存庫或金鑰，則請參閱具有虛刪除和清除保護的 Azure Key Vault 復原管理。

建立非 RBAC 公用金鑰保存庫的金鑰保存庫和金鑰

使用 az keyvault create 來建立金鑰保存庫，而不需要使用 Azure 角色型存取控制 (Azure RBAC)：

az keyvault create --name MyKeyVault --resource-group MyResourceGroup

使用 az keyvault key create 來建立金鑰：

az keyvault key create --name MyKeyName --vault-name MyKeyVault

使用 az keyvault key show 來匯出金鑰識別碼：

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

此範例會將金鑰識別碼儲存至 KEY_ID。

建立 RBAC 公用金鑰保存庫的金鑰保存庫和金鑰

使用 az keyvault create，以使用 Azure RBAC 來建立金鑰保存庫：

export KEYVAULT_RESOURCE_ID=$(az keyvault create --name MyKeyVault --resource-group MyResourceGroup  --enable-rbac-authorization true --query id -o tsv)

為自己指派建立金鑰的權限：

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 $KEYVAULT_RESOURCE_ID

使用 az keyvault key create 來建立金鑰：

az keyvault key create --name MyKeyName --vault-name MyKeyVault

使用 az keyvault key show 來匯出金鑰識別碼：

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

此範例會將金鑰識別碼儲存至 KEY_ID。

建立公用金鑰保存庫的使用者指派受控識別

使用 az identity create 來建立使用者指派的受控識別：

az identity create --name MyIdentity --resource-group MyResourceGroup

使用 az identity show 以取得身分識別物件識別碼：

IDENTITY_OBJECT_ID=$(az identity show --name MyIdentity --resource-group MyResourceGroup --query 'principalId' -o tsv)
echo $IDENTITY_OBJECT_ID

先前範例會將身分識別物件識別碼的值儲存在 IDENTITY_OBJECT_ID 中。

使用 az identity show 以取得身分識別資源識別碼：

IDENTITY_RESOURCE_ID=$(az identity show --name MyIdentity --resource-group MyResourceGroup --query 'id' -o tsv)
echo $IDENTITY_RESOURCE_ID

此範例會將身分識別資源識別碼的值儲存在 IDENTITY_RESOURCE_ID 中。

指派權限以解密和加密公用金鑰保存庫

下列各節描述如何指派私人金鑰保存庫的解密和加密權限。

指派非 RBAC 公用金鑰保存庫的權限

如果未使用 --enable-rbac-authorization 來設定您的金鑰保存庫，則您可以使用 az keyvault set-policy 來建立 Azure 金鑰保存庫原則。

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

指派 RBAC 公用金鑰保存庫的權限

如果您的金鑰保存庫已設定 --enable-rbac-authorization，則請指派「金鑰保存庫密碼編譯使用者」角色以給定解密和加密權限。

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

建立具有公用金鑰保存庫的 AKS 叢集，然後開啟 KMS etcd 加密

若要開啟 KMS etcd 加密，請使用 az aks create 命令來建立 AKS 叢集。您可以搭配使用 --enable-azure-keyvault-kms、--azure-keyvault-kms-key-vault-network-access 和 --azure-keyvault-kms-key-id 參數與 az aks create。

az aks create \
    --name myAKSCluster \
    --resource-group MyResourceGroup \
    --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 etcd 加密

若要開啟現有叢集的 KMS etcd 加密，請使用 az aks update 命令。您可以搭配使用 --enable-azure-keyvault-kms、--azure-keyvault-kms-key-vault-network-access 和 --azure-keyvault-kms-key-id 參數與 az-aks-update。

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

使用下列命令來更新所有祕密。如果您未執行此命令，則無法再加密稍早所建立的祕密。針對較大的叢集，您可能想要依命名空間來細分祕密，或建立更新指令碼。

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

輪替公用金鑰保存庫中的現有金鑰

變更金鑰識別碼 (包括變更金鑰名稱或金鑰版本) 之後，您可以使用 az aks update 命令。您可以搭配使用 --enable-azure-keyvault-kms、--azure-keyvault-kms-key-vault-network-access 和 --azure-keyvault-kms-key-id 參數與 az-aks-update，以輪替 KMS 中的現有金鑰。

警告

請記得在金鑰輪替之後更新所有祕密。如果您未更新所有祕密，則稍早建立的金鑰不存在或不再運作時無法存取祕密。

KMS 會同時使用 2 個金鑰。在第一次金鑰輪替之後，您必須確保舊金鑰和新金鑰在下次金鑰輪替之前都有效 (未過期)。在第二次金鑰輪替之後，最舊的金鑰可以安全地移除/過期

使用新的 keyId輪替 KMS 金鑰版本之後，請檢查 securityProfile.azureKeyVaultKms.keyId AKS 資源 json。請確定正在使用新的金鑰版本。

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

使用下列命令來更新所有祕密。如果您未執行此命令，則仍然會使用上一個金鑰來加密稍早所建立的祕密。針對較大的叢集，您可能想要依命名空間來細分祕密，或建立更新指令碼。

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

開啟私人金鑰保存庫的 KMS

如果您開啟私人金鑰保存庫的 KMS，則 AKS 會自動在節點資源群組中建立私人端點和私人連結。金鑰保存庫會新增與 AKS 叢集的私人端點連線。

警告

KMS 針對私密金鑰保存庫僅支援 API Server VNet 整合 (預覽)。

建立私密金鑰保存庫和金鑰

警告

不支援刪除金鑰或金鑰保存庫，這樣做會導致叢集中的祕密無法復原。

如果您需要復原金鑰保存庫或金鑰，則請參閱具有虛刪除和清除保護的 Azure Key Vault 復原管理。

使用 az keyvault create 來建立私人金鑰保存庫：

az keyvault create --name MyKeyVault --resource-group MyResourceGroup --public-network-access Disabled

使用 az keyvault key create 來建立金鑰：

az keyvault key create --name MyKeyName --vault-name MyKeyVault

不支援建立或更新私人金鑰保存庫中沒有私人端點的金鑰。若要了解如何管理私人金鑰保存庫，請參閱使用 Azure Private Link 來整合金鑰保存庫。

建立私人金鑰保存庫的使用者指派受控識別

使用 az identity create 來建立使用者指派的受控識別：

az identity create --name MyIdentity --resource-group MyResourceGroup

使用 az identity show 以取得身分識別物件識別碼：

IDENTITY_OBJECT_ID=$(az identity show --name MyIdentity --resource-group MyResourceGroup --query 'principalId' -o tsv)
echo $IDENTITY_OBJECT_ID

先前範例會將身分識別物件識別碼的值儲存在 IDENTITY_OBJECT_ID 中。

使用 az identity show 以取得身分識別資源識別碼：

IDENTITY_RESOURCE_ID=$(az identity show --name MyIdentity --resource-group MyResourceGroup --query 'id' -o tsv)
echo $IDENTITY_RESOURCE_ID

此範例會將身分識別資源識別碼的值儲存在 IDENTITY_RESOURCE_ID 中。

指派權限以解密和加密私人金鑰保存庫

下列各節描述如何指派私人金鑰保存庫的解密和加密權限。

指派非 RBAC 私人金鑰保存庫的權限

注意

使用私人金鑰保存庫時，AKS 無法驗證身分識別的權限。啟用 KMS 之前，請確認身分識別已獲授與存取金鑰保存庫的權限。

如果未使用 --enable-rbac-authorization 來設定您的金鑰保存庫，則您可以使用 az keyvault set-policy 以在 Azure 中建立金鑰保存庫原則：

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

指派 RBAC 私人金鑰保存庫的權限

如果您的金鑰保存庫已設定 --enable-rbac-authorization，則請指派包括解密和加密權限的 Azure RBAC 角色：

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

指派私人連結建立權限

針對私人金鑰保存庫，需要「金鑰保存庫參與者」角色，才能建立私人金鑰保存庫與叢集之間的私人連結。

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

建立具有私人金鑰保存庫的 AKS 叢集，然後開啟 KMS etcd 加密

若要開啟私人金鑰保存庫的 KMS etcd 加密，請使用 az aks create 命令來建立 AKS 叢集。您可以搭配使用 --enable-azure-keyvault-kms、--azure-keyvault-kms-key-id、--azure-keyvault-kms-key-vault-network-access 和 --azure-keyvault-kms-key-vault-resource-id 參數與 az-aks-create。

az aks create \
    --name myAKSCluster \
    --resource-group MyResourceGroup \
    --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 $KEYVAULT_RESOURCE_ID \
    --generate-ssh-keys

更新現有的 AKS 叢集，以開啟私人金鑰保存庫的 KMS etcd 加密

若要開啟具有私人金鑰保存庫的現有叢集上的 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 參數與 az-aks-update。

az aks update --name myAKSCluster --resource-group MyResourceGroup --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 $KEYVAULT_RESOURCE_ID

使用下列命令來更新所有祕密。如果您未執行此命令，則不會加密稍早所建立的祕密。針對較大的叢集，您可能想要依命名空間來細分祕密，或建立更新指令碼。

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

輪替私人金鑰保存庫中的現有金鑰

變更金鑰識別碼 (包括金鑰名稱和金鑰版本) 之後，您可以使用 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 參數與 az-aks-update，以輪替 KMS 的現有金鑰。

警告

請記得在金鑰輪替之後更新所有祕密。如果您未更新所有祕密，則稍早建立的金鑰不存在或不再運作時無法存取祕密。

輪替金鑰之後，仍然會快取上一個金鑰 (key1)，而且不應該將其刪除。如果您想要立即刪除上一個金鑰 (key1)，則需要輪替金鑰兩次。接著會快取 key2 和 key3，而且可以刪除 key1，而不會影響現有的叢集。

使用新的 keyId輪替 KMS 金鑰版本之後，請檢查 securityProfile.azureKeyVaultKms.keyId AKS 資源 json。請確定正在使用新的金鑰版本。

az aks update --name myAKSCluster --resource-group MyResourceGroup  --enable-azure-keyvault-kms --azure-keyvault-kms-key-id $NewKEY_ID --azure-keyvault-kms-key-vault-network-access "Private" --azure-keyvault-kms-key-vault-resource-id $KEYVAULT_RESOURCE_ID

使用下列命令來更新所有祕密。如果您未更新所有祕密，則會使用上一個金鑰來加密稍早所建立的祕密。針對較大的叢集，您可能想要依命名空間來細分祕密，或建立更新指令碼。

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

更新金鑰保存庫模式

注意

若要變更具有不同模式的不同金鑰保存庫 (公開還是私人)，您可以直接執行 az aks update。若要變更已連結金鑰保存庫的模式，您必須先關閉 KMS，然後使用新的金鑰保存庫識別碼再次將其開啟。

下列各節描述如何將已連結的公用金鑰保存庫移轉至私人模式。這些步驟也可用來從私人模式遷移至公用模式。

關閉叢集上的 KMS

關閉現有叢集上的 KMS，並釋放金鑰保存庫：

az aks update --name myAKSCluster --resource-group MyResourceGroup --disable-azure-keyvault-kms

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

變更金鑰保存庫模式

將金鑰保存庫從公用更新為私人：

az keyvault update --name MyKeyVault --resource-group MyResourceGroup --public-network-access Disabled

若要從私人模式遷移至公用模式，請將上述命令中的 --public-network-access 設定為 Enabled。

使用已更新的金鑰保存庫來開啟叢集的 KMS

使用已更新的私人金鑰保存庫來開啟 KMS：

az aks update --name myAKSCluster --resource-group MyResourceGroup  --enable-azure-keyvault-kms --azure-keyvault-kms-key-id $NewKEY_ID --azure-keyvault-kms-key-vault-network-access "Private" --azure-keyvault-kms-key-vault-resource-id $KEYVAULT_RESOURCE_ID

設定 KMS 之後，您可以開啟金鑰保存庫的診斷設定來檢查加密記錄。

關閉 TPM

關閉 KMS 之前，您可以使用下列 Azure CLI 命令來檢查是否已開啟 KMS：

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

如果結果確認已開啟 KMS，則請執行下列命令以關閉叢集上的 KMS：

az aks update --name myAKSCluster --resource-group MyResourceGroup --disable-azure-keyvault-kms

使用下列命令來更新所有祕密。如果您未執行此命令，則仍然會使用上一個金鑰來加密稍早所建立的祕密，而且仍然需要金鑰保存庫的加密和解密權限。針對較大的叢集，您可能想要依命名空間來細分祕密，或建立更新指令碼。

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

KMS v2 支援

從 AKS 1.27 版開始，開啟 KMS 功能會設定 KMS v2。使用 KMS v2，不會限制您只能使用舊版本所支援的 2,000 個祕密。如需詳細資訊，請參閱 KMS V2 改善。

移轉至 KMS v2

如果您的叢集版本比 1.27 還要舊，而且您已開啟 KMS，則會封鎖升級至叢集版本 1.27 或更新版本。使用下列步驟來移轉至 KMS v2：

關閉叢集上的 KMS。
執行儲存體移轉。
將叢集升級至 1.27 版或更新版本。
開啟叢集上的 KMS。
執行儲存體移轉。

關閉 KMS 以移轉儲存體

若要關閉現有叢集上的 KMS，請搭配使用 az aks update 命令與 --disable-azure-keyvault-kms 引數：

az aks update --name myAKSCluster --resource-group MyResourceGroup --disable-azure-keyvault-kms

移轉儲存體

若要更新所有祕密，請搭配使用 kubectl get secrets 命令與 --all-namespaces 引數：

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

升級 AKS 叢集

若要升級 AKS 叢集，請使用 az aks upgrade 命令。使用 --kubernetes-version 引數，以將版本設定為 1.27.x 或更新版本。

az aks upgrade --resource-group myResourceGroup --name myAKSCluster --kubernetes-version <AKS version>

以下是範例：

az aks upgrade --resource-group myResourceGroup --name myAKSCluster --kubernetes-version 1.27.1

在儲存體移轉之後開啟 KMS

您可以再次開啟叢集上的 KMS 功能，以加密祕密。之後，AKS 叢集會使用 KMS v2。如果您不想要移轉至 KMS v2，則可以建立版本為 1.27 版或更新版本且已開啟 KMS 的新叢集。

移轉 KMS v2 的儲存體

若要重新加密 KMS v2 中的所有祕密，請搭配使用 kubectl get secrets 命令與 --all-namespaces 引數：

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

KMS 可觀察性

AKS 資源 json

您可以透過下列方式檢查 AKS 資源 json 中的 KMS 設定：

使用 az aks show 命令
透過 Azure 入口網站

本節 securityProfile.azureKeyVaultKms 顯示 KMS 設定，包括金鑰保存庫、金鑰、目前和舊版密鑰。

診斷並解決問題

因為 KMS 外掛程式是 kube-apiserver Pod 的側車，所以您無法直接存取它。若要改善 KMS 的可檢視性，您可以透過下列方式檢查 KMS 狀態：

開啟 AKS 叢集的 Azure 入口網站頁面
移至並 Diagnose and solve problems 搜尋 KMS
在偵測器中 KMS ，您可以看到 KMS 的狀態，以及它是否在某些已知的失敗案例中

以 KeyExpired: Operation encrypt is not allowed on an expired key 下列範例為例：

因為 AKS KMS 外掛程式目前只允許 BYO 金鑰保存庫和金鑰，因此您必須負責管理金鑰生命週期。如果金鑰已過期，KMS 外掛程式將無法解密現有的秘密。您需要

延長金鑰到期日，讓 KMS 運作
輪替金鑰版本

共用方式為

將金鑰管理服務 etcd 加密新增至 Azure Kubernetes Service 叢集

必要條件

限制

開啟公用金鑰保存庫的 KMS

建立私人金鑰保存庫和金鑰

建立非 RBAC 公用金鑰保存庫的金鑰保存庫和金鑰

建立 RBAC 公用金鑰保存庫的金鑰保存庫和金鑰

建立公用金鑰保存庫的使用者指派受控識別

指派權限以解密和加密公用金鑰保存庫

指派非 RBAC 公用金鑰保存庫的權限

指派 RBAC 公用金鑰保存庫的權限

建立具有公用金鑰保存庫的 AKS 叢集，然後開啟 KMS etcd 加密

更新現有的 AKS 叢集，以開啟公用金鑰保存庫的 KMS etcd 加密

輪替公用金鑰保存庫中的現有金鑰

開啟私人金鑰保存庫的 KMS

建立私密金鑰保存庫和金鑰

建立私人金鑰保存庫的使用者指派受控識別

指派權限以解密和加密私人金鑰保存庫

指派非 RBAC 私人金鑰保存庫的權限

指派 RBAC 私人金鑰保存庫的權限

指派私人連結建立權限

建立具有私人金鑰保存庫的 AKS 叢集，然後開啟 KMS etcd 加密

更新現有的 AKS 叢集，以開啟私人金鑰保存庫的 KMS etcd 加密

輪替私人金鑰保存庫中的現有金鑰

更新金鑰保存庫模式

關閉叢集上的 KMS

變更金鑰保存庫模式

使用已更新的金鑰保存庫來開啟叢集的 KMS

關閉 TPM

KMS v2 支援

移轉至 KMS v2

關閉 KMS 以移轉儲存體

移轉儲存體

升級 AKS 叢集

在儲存體移轉之後開啟 KMS

移轉 KMS v2 的儲存體

KMS 可觀察性

AKS 資源 json

診斷並解決問題

其他資源