# Bring your own key from a hardware security module

This topic explains how you can use your own Azure Key Vault hardware security
module (HSM) key for at-rest encryption on GKE on Azure.

## Before you begin

Before performing these steps, ensure that you're familiar with the
[Security](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/concepts/security.md.txt) architecture of GKE on Azure.

To perform these steps, you must have the following:

- An [Azure-supported HSM](https://docs.microsoft.com/en-us/azure/key-vault/keys/hsm-protected-keys#supported-hsms)

- An Azure Key Vault with the
  [Azure role-based access control](https://docs.microsoft.com/en-us/azure/key-vault/general/rbac-guide)
  permission model.

- An
  [HSM-protected key imported into Azure Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/keys/hsm-protected-keys-byok)

- Your GKE on Azure
  [service principal](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/create-azure-ad-application.md.txt) with
  permissions to manage the Azure Key Vault authorization and encrypt data
  with the provided key.

  The easiest way to grant these permissions is to assign the
  `Key Vault Crypto Officer` and `User Access Administrator`
  [Azure built-in roles](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles)
  to the service principal.

### Bring your own key

To bring your own key, perform the following steps:

1. Save your Azure Key Vault key ID into an environment variable.

   ```bash
   export KEY_VAULT_ID="$(az keyvault show --name ${KEY_VAULT_NAME} \
       --resource-group ${RESOURCE_GROUP} --query id -otsv)"
   export KEY_VAULT_KEY_ID="${KEY_VAULT_ID}/keys/${KEY_NAME}"
   ```
2. Pass the key's IDs in the
   [`--config-encryption-key-id`](https://docs.cloud.google.com/sdk/gcloud/reference/container/azure/clusters/create#--config-encryption-key-id)
   parameter when you [Create a cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/create-cluster.md.txt).

   ```bash
   gcloud container azure clusters create CLUSTER_NAME \
       --config-encryption-key-id  ${KEY_VAULT_KEY_ID} \
       ...
   ```
3. Continue with the steps in
   [Create a cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/create-cluster.md.txt).

## What's next

See [About keys](https://docs.microsoft.com/azure/key-vault/keys/about-keys)
in the Azure documentation.