Skip to content

Commit f66b876

Browse files
denreadenrea
authored
Merge pull request #192286 from miwithro/kms
kms
2 parents 7ee9883 + af2d685 commit f66b876

File tree

2 files changed

+158
-0
lines changed

2 files changed

+158
-0
lines changed

‎articles/aks/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,8 @@
256256
href: control-kubeconfig-access.md
257257
- name: Define API server authorized IP ranges
258258
href: api-server-authorized-ip-ranges.md
259+
- name: Use KMS etcd encryption
260+
href: use-kms-etcd-encryption.md
259261
- name: Update cluster credentials
260262
href: update-credentials.md
261263
- name: Enable Azure Active Directory integration

‎articles/aks/use-kms-etcd-encryption.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: Use KMS etcd encryption in Azure Kubernetes Service (AKS) (Preview)
3+
description: Learn how to use kms etcd encryption with Azure Kubernetes Service (AKS)
4+
services: container-service
5+
ms.topic: article
6+
ms.date: 04/11/2022
7+
8+
---
9+
10+
# Add KMS etcd encryption to an Azure Kubernetes Service (AKS) cluster (Preview)
11+
12+
This article shows you how to enable encryption at rest for your Kubernetes data in etcd using Azure Key Vault with Key Management Service (KMS) plugin. The KMS plugin allows you to:
13+
14+
* Use a key in Key Vault for etcd encryption
15+
* Bring your own keys
16+
* Provide encryption at rest for secrets stored in etcd
17+
18+
For more details on using the KMS plugin, see [Encrypting Secret Data at Rest](https://kubernetes.io/docs/tasks/administer-cluster/kms-provider/).
19+
20+
[!INCLUDE [preview features callout](./includes/preview/preview-callout.md)]
21+
22+
## Before you begin
23+
24+
* An Azure subscription. If you don't have an Azure subscription, you can create a [free account](https://azure.microsoft.com/free).
25+
* [Azure CLI installed](/cli/azure/install-azure-cli).
26+
27+
### Install the `aks-preview` Azure CLI
28+
29+
You also need the *aks-preview* Azure CLI extension version 0.5.58 or later. Install the *aks-preview* Azure CLI extension by using the [az extension add][az-extension-add] command. Or install any available updates by using the [az extension update][az-extension-update] command.
30+
31+
```azurecli-interactive
32+
# Install the aks-preview extension
33+
az extension add --name aks-preview
34+
# Update the extension to make sure you have the latest version installed
35+
az extension update --name aks-preview
36+
```
37+
38+
### Register the `AzureKeyVaultKmsPreview` preview feature
39+
40+
To use the feature, you must also enable the `AzureKeyVaultKmsPreview` feature flag on your subscription.
41+
42+
Register the `AzureKeyVaultKmsPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:
43+
44+
```azurecli-interactive
45+
az feature register --namespace "Microsoft.ContainerService" --name "AzureKeyVaultKmsPreview"
46+
```
47+
48+
It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature list][az-feature-list] command:
49+
50+
```azurecli-interactive
51+
az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/AzureKeyVaultKmsPreview')].{Name:name,State:properties.state}"
52+
```
53+
54+
When ready, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [az provider register][az-provider-register] command:
55+
56+
```azurecli-interactive
57+
az provider register --namespace Microsoft.ContainerService
58+
```
59+
60+
## Limitations
61+
62+
> [!WARNING]
63+
> Deleting the key or the Azure Key Vault is not supported and will cause your cluster to become unstable.
64+
>
65+
> If you need to recover your Key Vault or key, see the [Azure Key Vault recovery management with soft delete and purge protection](../key-vault/general/key-vault-recovery.md?tabs=azure-cli) documentation.
66+
67+
The following limitations apply when you integrate KMS etcd encryption with AKS:
68+
69+
* Disabling of the KMS etcd encryption feature.
70+
* Changing of key Id, including key name and key version.
71+
* Deletion of the key, Key Vault, or the associated identity.
72+
* KMS etcd encryption does not work with System-Assigned Managed Identity. The keyvault access-policy is required to be set before the feature is enabled. In addition, System-Assigned Managed Identity is not available until cluster creation, thus there is a cycle dependency.
73+
* Using Azure Key Vault with PrivateLink enabled.
74+
* Using more than 2000 secrets in a cluster.
75+
* Managed HSM Support
76+
* Bring your own (BYO) Azure Key Vault from another tenant.
77+
78+
79+
## Create a KeyVault and key
80+
81+
Use `az keyvault create` to create a KeyVault.
82+
83+
```azurecli
84+
az keyvault create --name MyKeyVault --resource-group MyResourceGroup
85+
```
86+
87+
Use `az keyvault key create` to create a key.
88+
89+
```azurecli
90+
az keyvault key create --name MyKeyName --vault-name MyKeyVault
91+
```
92+
93+
Use `az keyvault key show` to export the Key ID.
94+
95+
```azurecli
96+
export KEY_ID=$(az keyvault key show --name MyKeyName --vault-name MyKeyVault --query 'key.kid' -o tsv)
97+
echo $KEY_ID
98+
```
99+
100+
The above example stores the Key ID in *KEY_ID*.
101+
102+
## Create a user-assigned managed identity
103+
104+
Use `az identity create` to create a User-assigned managed identity.
105+
106+
```azurecli
107+
az identity create --name MyIdentity --resource-group MyResourceGroup
108+
```
109+
110+
Use `az identity show` to get Identity Object Id.
111+
112+
```azurecli
113+
IDENTITY_OBJECT_ID=$(az identity show --name MyIdentity --resource-group MyResourceGroup --query 'principalId' -o tsv)
114+
echo $IDENTITY_OBJECT_ID
115+
```
116+
117+
The above example stores the value of the Identity Object Id in *IDENTITY_OBJECT_ID*.
118+
119+
Use `az identity show` to get Identity Resource Id.
120+
121+
```azurecli
122+
IDENTITY_RESOURCE_ID=$(az identity show --name MyIdentity --resource-group MyResourceGroup --query 'id' -o tsv)
123+
echo $IDENTITY_RESOURCE_ID
124+
```
125+
126+
The above example stores the value of the Identity Resource Id in *IDENTITY_RESOURCE_ID*.
127+
128+
## Assign permissions (decrypt and encrypt) to access key vault
129+
130+
Use `az keyvault set-policy` to create an Azure KeyVault policy.
131+
132+
```azurecli-interactive
133+
az keyvault set-policy -n MyKeyVault --key-permissions decrypt encrypt --object-id $IDENTITY_OBJECT_ID
134+
```
135+
136+
## Create an AKS cluster with KMS etcd encryption enabled
137+
138+
Create an AKS cluster using the [az aks create][az-aks-create] command with the `--enable-azure-keyvault-kms` and `--azure-keyvault-kms-key-id` parameters to enable KMS etcd encryption.
139+
140+
```azurecli-interactive
141+
az aks create --name myAKSCluster --resource-group MyResourceGroup --assign-identity $IDENTITY_RESOURCE_ID --enable-azure-keyvault-kms --azure-keyvault-kms-key-id $KEY_ID
142+
```
143+
144+
## Update an exiting AKS cluster to enable KMS etcd encryption
145+
146+
Use `az aks update` with the `--enable-azure-keyvault-kms` and `--azure-keyvault-kms-key-id` parameters to enable KMS etcd encryption on an existing cluster.
147+
148+
```azurecli-interactive
149+
az aks update --name myAKSCluster --resource-group MyResourceGroup --enable-azure-keyvault-kms --azure-keyvault-kms-key-id $KEY_ID
150+
```
151+
152+
<!-- LINKS - Internal -->
153+
[aks-support-policies]: support-policies.md
154+
[aks-faq]: faq.md
155+
[azure-cli-install]: /cli/azure/install-azure-cli
156+
[az-aks-create]: /cli/azure/aks#az-aks-create

0 commit comments

Comments
 (0)