Auto Unseal in Hashicorp Vault
A Hashicorp Vault build with Yandex Key Management Service support is available as a VM image in Cloud Marketplace and as a Docker image. It differs from the primary version by a single binary Vault file with Key Management Service support added to it.
This build will enable you to use Key Management Service as a trusted service for encrypting secrets. This is implemented through the Auto Unseal mechanism.
In this guide, you will learn how to set up the Auto Unseal feature to work with KMS.
To set up Auto Unseal:
Get your cloud ready
-
Download the most recent Docker image using the command below:
docker pull cr.yandex/yc/vault -
Select one of the methods to authenticate Vault requests to KMS. You can authenticate via:
Service account linked to your VMAny service accountYandex or federated accountAuthentication is performed using an IAM token that is automatically extracted from the VM metadata. For more information, see Using Yandex Cloud from within a VM.
Tip
This option is the most preferable for security reasons. When configuring settings using the service account linked to the VM, you do not need to specify your credentials.
An authorized key is used for authentication. For more information about how to use authorized keys, see Get an IAM token using the CLI.
Authentication is done using an OAuth token or IAM token.
Tip
This option is the least preferable for security reasons. We recommend that you only use it for testing.
-
Create a separate Key Management Service key for Vault (recommended).
-
Grant access to the key only to the user or service account that will be used to authenticate Vault requests to KMS. When interacting with KMS, Vault performs only encryption and decryption operations, so the
kms.keys.encrypterDecrypterrole will be enough.
Required paid resources
The infrastructure support costs include:
- Fee for a continuously running VM (see Yandex Compute Cloud pricing).
- Fee for a dynamic or static external IP address (see Yandex Virtual Private Cloud pricing).
- Fee for the number of active KMS key versions and completed cryptographic operations (see Yandex Virtual Private Cloud pricing).
Set up Auto Unseal
To set up the Auto Unseal feature, make the following changes to the Vault configuration file:
Warning
If Vault has already been initialized, you have to run a migration procedure to modify the configuration.
-
Under seal, enter
"yandexcloudkms"as the value. -
Add the
kms_key_idparameter with the KMS encryption key ID. -
Authenticate using one the following methods:
Service account linked to your VMAny service accountYandex or federated accountLink a service account to a VM by following the instructions.
In the
service_account_key_fileparameter, specify the path to the file with the service account's authorized key.If using a Yandex account, specify the OAuth token in the
oauth_tokenparameter. For a federated account, specify the IAM token. -
Change the configuration when performing migration based on the Vault version in use.
Note
You can use environment variables instead of the configuration file to set parameter values:
YANDEXCLOUD_KMS_KEY_IDinstead of thekms_key_idconfiguration file parameter.YANDEXCLOUD_SERVICE_ACCOUNT_KEY_FILEinstead of theservice_account_key_fileparameter.YANDEXCLOUD_OAUTH_TOKENinstead of theoauth_tokenparameter.
The environment variable values prevail over those from the configuration file.
Configuration examples
...
seal "yandexcloudkms" {
kms_key_id = "<KMS_key_ID>"
}
...
...
seal "yandexcloudkms" {
kms_key_id = "<KMS_key_ID>"
service_account_key_file = "<JSON_file_path>"
}
...
Where service_account_key_file is the path to the JSON file with the authorized key.
...
seal "yandexcloudkms" {
kms_key_id = "<KMS_key_ID>"
oauth_token = "<user_token>"
}
...
Key rotation
When the Vault master key is encrypted with a KMS key, Vault also saves the key version it was encrypted with.
When the Vault master key is decrypted (at Vault restart), the saved version of the KMS key used to encrypt the Vault master key is compared with the primary version of the KMS key. If the key versions are different, the Vault master key is re-encrypted with the new primary version of the KMS key.
This way you can rotate the Vault master key through key rotation in KMS. Rotating the key in Key Management Service will automatically rotate the master key when Vault is restarted the next time.
How to delete the resources you created
To stop paying for the resources you created:
- Delete the VM if you created one to run Vault.
- Delete the static public IP if you reserved one.
- Delete the Key Management Service key.