|
| 1 | +--- |
| 2 | +title: Use a customer-managed key to encrypt Azure disks in Azure Kubernetes Service (AKS) |
| 3 | +description: Bring your own keys (BYOK) to encrypt AKS OS and Data disks. |
| 4 | +services: container-service |
| 5 | +author: mlearned |
| 6 | + |
| 7 | +ms.service: container-service |
| 8 | +ms.topic: article |
| 9 | +ms.date: 01/12/2020 |
| 10 | +ms.author: mlearned |
| 11 | +--- |
| 12 | + |
| 13 | +# Bring your own keys (BYOK) with Azure disks in Azure Kubernetes Service (AKS) |
| 14 | + |
| 15 | +Azure Storage encrypts all data in a storage account at rest. By default, data is encrypted with Microsoft-managed keys. For additional control over encryption keys, you can supply [customer-managed keys][customer-managed-keys] to use for encryption of both the OS and data disks for your AKS clusters. |
| 16 | + |
| 17 | +> [!NOTE] |
| 18 | +> Linux and Windows based AKS clusters are both supported. |
| 19 | +
|
| 20 | +## Before you begin |
| 21 | + |
| 22 | +* This article assumes that you are creating a *new AKS cluster*. You will also need to use or create an instance of Azure Key Vault to store your encryption keys. |
| 23 | + |
| 24 | +* You must enable soft delete and purge protection for *Azure Key Vault* when using Key Vault to encrypt managed disks. |
| 25 | + |
| 26 | +* You need the Azure CLI version 2.0.79 or later and the aks-preview 0.4.26 extension |
| 27 | + |
| 28 | +> [!IMPORTANT] |
| 29 | +> AKS preview features are self-service opt-in. Previews are provided "as-is" and "as available" and are excluded from the service level agreements and limited warranty. AKS Previews are partially covered by customer support on best effort basis. As such, these features are not meant for production use. For additional infromation, please see the following support articles: |
| 30 | +> |
| 31 | +> * [AKS Support Policies](support-policies.md) |
| 32 | +> * [Azure Support FAQ](faq.md) |
| 33 | +
|
| 34 | +## Install latest AKS CLI preview extension |
| 35 | + |
| 36 | +To use customer-managed keys, you need the *aks-preview* CLI extension version 0.4.26 or higher. Install the *aks-preview* Azure CLI extension using the [az extension add][az-extension-add] command, then check for any available updates using the [az extension update][az-extension-update] command: |
| 37 | + |
| 38 | +```azurecli-interactive |
| 39 | +# Install the aks-preview extension |
| 40 | +az extension add --name aks-preview |
| 41 | +
|
| 42 | +# Update the extension to make sure you have the latest version installed |
| 43 | +az extension update --name aks-preview |
| 44 | +``` |
| 45 | + |
| 46 | +## Create an Azure Key Vault instance to store your keys |
| 47 | + |
| 48 | +You can optionally use the Azure portal to [Configure customer-managed keys with Azure Key Vault][byok-azure-portal] |
| 49 | + |
| 50 | +Create a new *resource group*, then create a new *Key Vault* instance and enable soft delete and purge protection. |
| 51 | + |
| 52 | +```azurecli-interactive |
| 53 | +# Optionally retrieve Azure region short names for use on upcoming commands |
| 54 | +az account list-locations |
| 55 | +
|
| 56 | +# Create new resource group in a supported Azure region |
| 57 | +az group create -l myAzureRegionName -n myResourceGroup |
| 58 | +
|
| 59 | +# Create an Azure Key Vault resource in a supported Azure region |
| 60 | +az keyvault create -n myKeyVaultName -g myResourceGroup -l myAzureRegionName --enable-purge-protection true --enable-soft-delete true |
| 61 | +``` |
| 62 | + |
| 63 | +## Create an instance of a DiskEncryptionSet |
| 64 | + |
| 65 | +You will need a *key* stored in Azure Key Vault to complete the following steps. Either store your existing Key in the Key Vault you created, or [generate a key][key-vault-generate] |
| 66 | + |
| 67 | +```azurecli-interactive |
| 68 | +# Retrieve the Key Vault Id and store it in a variable |
| 69 | +keyVaultId=$(az keyvault show --name myKeyVaultName --query [id] -o tsv) |
| 70 | +
|
| 71 | +# Retrieve the Key Vault key URL and store it in a variable |
| 72 | +keyVaultKeyUrl=$(az keyvault key show --vault-name myKeyVaultName --name myKeyName --query [key.kid] -o tsv) |
| 73 | +
|
| 74 | +# Create a DiskEncryptionSet |
| 75 | +az disk-encryption-set create -n myDiskEncryptionSetName -l myAzureRegionName -g myResourceGroup --source-vault $keyVaultId --key-url $keyVaultKeyUrl |
| 76 | +``` |
| 77 | + |
| 78 | +## Grant the DiskEncryptionSet resource access to the key vault |
| 79 | + |
| 80 | +Use the DiskEncryptionSet and resource groups you created on the prior steps, and grant the DiskEncryptionSet resource access to the Azure Key Vault. |
| 81 | + |
| 82 | +```azurecli-interactive |
| 83 | +# Retrieve the DiskEncryptionSet value and set a variable |
| 84 | +desIdentity=$(az disk-encryption-set show -n myDiskEncryptionSetName -g myResourceGroup --query [identity.principalId] -o tsv) |
| 85 | +
|
| 86 | +# Update security policy settings |
| 87 | +az keyvault set-policy -n myKeyVaultName -g myResourceGroup --object-id $desIdentity --key-permissions wrapkey unwrapkey get |
| 88 | +
|
| 89 | +# Assign the reader role |
| 90 | +az role assignment create --assignee $desIdentity --role Reader --scope $keyVaultId |
| 91 | +``` |
| 92 | + |
| 93 | +## Create a new AKS cluster and encrypt the OS disk with a customer-manged key |
| 94 | + |
| 95 | +Create a new resource group and AKS cluster, then use your key to encrypt the OS disk. Customer managed key is only supported in kubernetes versions greater than 1.17 |
| 96 | + |
| 97 | +```azurecli-interactive |
| 98 | +# Retrieve the DiskEncryptionSet value and set a variable |
| 99 | +diskEncryptionSetId=$(az resource show -n diskEncryptionSetName -g myResourceGroup --resource-type "Microsoft.Compute/diskEncryptionSets" --query [id] -o tsv) |
| 100 | +
|
| 101 | +# Create a resource group for the AKS cluster |
| 102 | +az group create -n myResourceGroup-l myAzureRegionName |
| 103 | +
|
| 104 | +# Create the AKS cluster |
| 105 | +az aks create -n myAKSCluster -g myResourceGroup --node-osdisk-diskencryptionset-id $diskEncryptionSetId --kubernetes-version 1.17.0 |
| 106 | +``` |
| 107 | + |
| 108 | +When new node pools are added to the cluster created above, the customer managed key provided during the create is used to encrypt the OS disk |
| 109 | + |
| 110 | +## Encrypt your AKS cluster data disk with a customer-managed key |
| 111 | + |
| 112 | +You can also encrypt the AKS data disks with your own keys. Replace myResourceGroup and myDiskEncryptionSetName with your real values, and apply the yaml. |
| 113 | + |
| 114 | +Ensure you have the proper AKS credentials. The Service principal will need to have contributor access to the resource group where the diskencryptionset is present. Otherwise, you will get an error suggesting that the service principal does not have permissions. |
| 115 | + |
| 116 | +Create a file called **byok-azure-disk.yaml** that contains the following information. Replace myResourceGroup and myDiskEncrptionSetName with your values. |
| 117 | + |
| 118 | +``` |
| 119 | +kind: StorageClass |
| 120 | +apiVersion: storage.k8s.io/v1 |
| 121 | +metadata: |
| 122 | + name: hdd |
| 123 | +provisioner: kubernetes.io/azure-disk |
| 124 | +parameters: |
| 125 | + skuname: Standard_LRS |
| 126 | + kind: managed |
| 127 | + diskEncryptionSetID: "/subscriptions/{subs-id}/resourceGroups/{myResourceGroup}/providers/Microsoft.Compute/diskEncryptionSets/{myDiskEncryptionSetName}" |
| 128 | +``` |
| 129 | +Next, run this deployment in your AKS cluster: |
| 130 | +```azurecli-interactive |
| 131 | +kubectl apply -f byok-azure-disk.yaml |
| 132 | +``` |
| 133 | + |
| 134 | +## Limitations |
| 135 | + |
| 136 | +* OS Disk Encryption supported with Kubernetes version 1.17 and above |
| 137 | +* Available only in regions where BYOK is supported |
| 138 | +* This is currently for new AKS clusters only, existing clusters cannot be upgraded |
| 139 | +* AKS cluster using Virtual Machine Scale Sets are required, no support for Virtual Machine Availability Sets |
| 140 | + |
| 141 | + |
| 142 | +## Next steps |
| 143 | + |
| 144 | +Review [best practices for AKS cluster security][best-practices-security] |
| 145 | + |
| 146 | +<!-- LINKS - external --> |
| 147 | + |
| 148 | +<!-- LINKS - internal --> |
| 149 | +[az-extension-add]: /cli/azure/extension#az-extension-add |
| 150 | +[az-extension-update]: /cli/azure/extension#az-extension-update |
| 151 | +[best-practices-security]: /azure/aks/operator-best-practices-cluster-security |
| 152 | +[byok-azure-portal]: /azure/storage/common/storage-encryption-keys-portal |
| 153 | +[customer-managed-keys]: /azure/virtual-machines/windows/disk-encryption#customer-managed-keys-public-preview |
| 154 | +[key-vault-generate]: /azure/key-vault/key-vault-manage-with-cli2 |
0 commit comments