Installing HashiCorp Vault with Key Management Service support

HashiCorp Vault is an open-source tool for securely storing and accessing secrets (e.g., passwords, certificates, and tokens).

The application image contains a pre-installed build of HashiCorp Vault with added support for Auto Unseal via Yandex Key Management Service. The build is based on HashiCorp Vault of the appropriate version.

To install HashiCorp Vault:

1. Prepare everything you need to get started.
2. Install HashiCorp Vault using Yandex Cloud Marketplace or Helm.
3. Initialize the vault.

Getting startedGetting started

To use HashiCorp Vault, you need:

• Service account with the kms.keys.encrypterDecrypter role.
• Authorized key.
• Symmetric encryption key.

1. Create a service account:

   yc iam service-account create --name vault-kms
   

2. Create an authorized key for the service account and save it to the authorized-key.json file:

   yc iam key create \
     --service-account-name vault-kms \
     --output authorized-key.json
   

3. Create a Key Management Service symmetric key:

   yc kms symmetric-key create \
     --name example-key \
     --default-algorithm aes-256 \
     --rotation-period 24h
   

   Save the key id. You will need it when installing the application.

4. Assign the kms.keys.encrypterDecrypter role to the service account you created previously:

   yc resource-manager folder add-access-binding \
     --id <folder_ID> \
     --service-account-name vault-kms \
     --role kms.keys.encrypterDecrypter
   

   You can fetch the folder ID with the list of folders.

5. Make sure that the security groups for the Managed Service for Kubernetes cluster and its node groups are configured correctly. If any rule is missing, add it.

   Warning

   The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.

6. Install kubect and configure it to work with the new cluster.

Installation using Yandex Cloud MarketplaceInstallation using Yandex Cloud Marketplace

1. Navigate to the folder dashboard and select Managed Service for Kubernetes.
2. Click the name of the Managed Service for Kubernetes cluster you need and select the Marketplace tab.
3. Under Application available for installation, select HashiCorp Vault with Key Management Service support and click Go to install.
4. Configure the application:
   • Namespace: Create a new namespace, e.g., hashicorp-vault-space. If you leave the default namespace, HashiCorp Vault may work incorrectly.
   • Application name: Specify the application name.
   • Service account key for Vault: Copy the contents of the authorized-key.json file to this field.
   • KMS key ID for Vault: Specify the previously obtained Key Management Service key ID.
5. Click Install.
6. Wait for the application to change its status to Deployed.

Installation using a Helm chartInstallation using a Helm chart

1. Install Helm v3.8.0 or higher.

2. Install kubect and configure it to work with the new cluster.

3. To install a Helm chart with HashiCorp Vault, run the following command, specifying the parameters of the resources you created earlier:

   cat <path_to_file_with_authorized_key> | helm registry login cr.yandex \
     --username 'json_key' \
     --password-stdin && \
   helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/vault/chart/vault \
     --version 0.28.1+yckms \
     --untar && \
   helm install \
     --namespace <namespace> \
     --create-namespace \
     --set-file yandexKmsAuthJson=<path_to_file_with_authorized_key> \
     --set yandexKmsKeyId=<KMS_key_ID> \
     hashicorp ./vault/
   

   Note

   If you are using a Helm version below 3.8.0, append the export HELM_EXPERIMENTAL_OCI=1 && \ string to the command to enable Open Container Initiative (OCI) support in the Helm client.

   Command parameters:

   • <path_to_file_with_authorized_key>: Path to the authorized-key.json file you saved earlier.
   • <namespace>: New namespace that will be created for HashiCorp Vault. If you specify the default namespace, HashiCorp Vault may work incorrectly. We recommend you to specify a value different from all existing namespaces (e.g., hashicorp-vault-space).
   • <KMS_key_ID>: Previously obtained Key Management Service key ID.

   This command will install HashiCorp Vault with KMS support and the Agent injector secret delivery tool to the cluster. To use the alternative Vault CSI provider mechanism, add the following parameters to the command:

   --set "injector.enabled=false" \
   --set "csi.enabled=true"
   

   For more information about the differences between these mechanisms, see the Hashicorp documentation.

Initializing the vaultInitializing the vault

Once HashiCorp Vault is installed, you need to initialize one of its servers. The initialization process generates credentials required to unseal all the vault servers.

To initialize the vault:

1. Make sure that the application switched to Running and has 0/1 ready pods:

   kubectl get pods \
     --namespace=<namespace> \
     --selector='app.kubernetes.io/name=vault'
   

   Result:

   NAME              READY  STATUS   RESTARTS  AGE
   <vault_pod_name>  0/1    Running  0         58s
   

2. Initialize the vault:

   kubectl exec \
     --namespace=<namespace> \
     --stdin=true \
     --tty=true <vault_pod_name> \
     -- vault operator init
   

   Result:

   Recovery Key 1: ulbugw4IKttmCCPprF6JwmUCyx1YfieCQPQi********
   Recovery Key 2: S0kcValC6qSfEI4WJBovSbJWZntBUwtTrtis********
   Recovery Key 3: t44ZRqbzLZNzfChinZNzLCNnwvFN/R52vbD*/*******
   ...
   
   Recovery key initialized with 5 key shares and a key threshold of 3. Please
   securely distribute the key shares printed above.
   

   Save the resulting data in a secure location.

3. Query the list of application pods again and make sure that one pod is ready:

   kubectl get pods \
     --namespace=<namespace> \
     --selector='app.kubernetes.io/name=vault'
   

   Result:

   NAME               READY  STATUS   RESTARTS  AGE
   vault-yckms-k8s-0  1/1    Running  0         5m
   

See alsoSee also

• HashiCorp Vault documentation
• Key Management Service documentation
• Using HashiCorp Vault to store secrets
• Installing the External Secrets Operator with Yandex Lockbox support
• Syncing with Yandex Lockbox secrets