Install HashiCorp Vault

HashiCorp Vault is an open-source tool that provides secure storage and encryption of confidential data, as well as access to data based on identity through customizable policies.
This article covers:

  1. Installing and configuring of HashiCorp Vault.
  2. Backing up and updating Vault. Optional when upgrading to Vault 2.0.4 from an earlier version.
  3. Removing Vault using Helm in Kubernetes cluster.

Install and configure HashiCorp Vault

The installation of HashiCorp Vault consists of the following steps:

  1. Download the Helm chart and Vault configuration file.
  2. Fill out the Vault configuration file.
  3. Install Vault using Helm in a Kubernetes cluster.
  4. Configure Vault.

Step 1. Download the Helm chart and Vault configuration file

To install via the internet, obtain the configuration file values-vault.yaml by running the command:

helm repo add brix365 https://charts.brix365.com
helm repo update
helm show values brix365/vault > values-vault.yaml

Obtaining the configuration file for installation in an isolated environment without internet access

  1. On a computer with internet access, download the BRIX images and upload them to the local image registry by running the following command.:

helm repo add brix365 https://charts.brix365.com
helm repo update
helm pull brix365/vault

 
To learn more, see Download BRIX images.

  1. Copy the downloaded archive of the chart vault-X.Y.Z.tgz to the server where the installation will take place.
  2. Unpack the chart and copy the default configuration file values.yaml to values-vault.yaml:

tar -xf vault-X.Y.Z.tgz
cp vault/values.yaml values-vault.yaml

Step 2. Fill out the Vault configuration file

Fill out the configuration file values-vault.yaml to install the Vault service.

# Vault settings
vault:
  global:
# if not defined, StorageClass is used by default
    storageClass: ""
...

Filling in the connection parameters for a private registry for installation in an isolated environment without internet access involves the following steps:

 
To connect to a private registry, you need to follow these steps:

  1. Download the BRIX images and upload them to your local image registry. For more details, refer to the article Download BRIX images.
  2. Specify the address and path in the parameters server.image.registry, server.image.repository, injector.image.registry and injector.image.repository.
  3. Specify the name of the secret with access rights to the private registry in the imagePullSecrets parameter. The secret must be manually created and encoded in Base64.

# Vault settings
vault:
...
  server:
# Parameters for connecting to the private registry
    image:
# Address and path for the private registry
      repository: hub.brix365.com/docker/addons/hashicorp/vault
      tag: 2.0.4
# The secret with access permissions to the private registry must be manually created and encoded in Base64
#      pullSecrets:
#        - name: "myRegistryKeySecretName"
  injector:
# Parameters for connecting to the private registry
    image:
# Address and path for the private registry
      repository: hub.brix365.com/docker/addons/hashicorp/vault-k8s
      tag: 1.7.6
# The secret with access permissions to the private registry must be manually created and encrypted in Base64
#      pullSecrets:
#        - name: "myRegistryKeySecretName"

 

Where repository is the path to the image: hub.brix365.com/docker/addons/hashicorp/vault, hub.brix365.com/docker/addons/hashicorp/vault-k8s.

Step 3. Install Vault using Helm in a Kubernetes cluster

Perform the installation of the Vault service in a separate namespace, for example, vault. Namespace will be created during installation if it hasn't been created earlier.

For installation with internet access, run the following command:

helm upgrade --install vault brix365/vault -f values-vault.yaml -n vault --create-namespace

For offline installation (without internet access), navigate to the directory with the downloaded service and run the following command:

helm upgrade --install vault ./vault -f values-vault.yaml -n vault --create-namespace

Step 4. Configure Vault

  1. Make sure that the satus of vault-0 is Running:

kubectl get pods -n vault 

  1. Initialize Vault:

kubectl exec -ti vault-0 -n vault -- vault operator init

  1. After initialization, retrieve the list of  keys (Unseal Key X:) and the root token (Initial Root Token). Use three keys to unlock the Vault service:

kubectl exec vault-0 -n vault -- vault operator unseal <Unseal Key 1>
kubectl exec vault-0 -n vault -- vault operator unseal <Unseal Key 2>
kubectl exec vault-0 -n vault -- vault operator unseal <Unseal Key 3> 

Начало внимание

If the Vault service restarts, it will need to be unsealed again using the keys.

Конец внимание

  1. After initialization and unsealing, connect to vault-0 and authenticate in Vault using the root key (Initial Root Token):

kubectl exec -ti vault-0 -n vault -- /bin/sh
vault login

  1. Check the service state:

vault status   

  1. Enable the secrets mechanism kv-v2 on the path of secret:

vault secrets enable -path=secret kv-v2  

  1. Create a secret at the path secret/brix365/db. For the secret, use the actual connection strings for the database (сonnection strings) and parameters for connecting to the S3 file storage, following the pattern in values-brix365.yaml: PSQL_URL, BRIX365_POOL_POSTGRES_URL, RO_POSTGRES_URL, MONGO_URL, VAHTER_MONGO_URL, REDIS_URL, AMQP_URL, S3_BACKEND_ADDRESS, S3_REGION, S3_KEY, S3_SECRET, S3_BUCKET, S3_SSL_ENABLED, S3_UPLOAD_METHOD, S3_DUMP_URL, S3_VIRTUAL_HOSTED_STYLE_ENABLED.

If a parameter, for example RO_POSTGRES_URL, S3_DUMP_URL, or BRIX365_POOL_POSTGRES_URL is not used, create it with an empty value:

vault kv put secret/brix365/db \
PSQL_URL="postgresql://postgres:pgpassword@postgres.default.svc.cluster.local:5432/brix365?sslmode=disable" \
RO_POSTGRES_URL="" \
BRIX365_POOL_POSTGRES_URL="" \
MONGO_URL="mongodb://brix365:mongopassword@mongo.default.svc.cluster.local:27017/brix365?ssl=false&replicaSet=rs0&readPreference=secondaryPreferred" \
VAHTER_MONGO_URL="mongodb://brix365:mongopassword@mongo.default.svc.cluster.local:27017/brix365?ssl=false&replicaSet=rs0&readPreference=secondaryPreferred" \
REDIS_URL="redis://redis.default.svc.cluster.local:6379/0" \
AMQP_URL="amqp://brix365:rmqpassword@rabbitmq.default.svc.cluster.local:5672/brix365" \
S3_BACKEND_ADDRESS="example.com" \
S3_REGION="us-east-1" \
S3_KEY="PZSF73JG72Ksd955JKU1HIA" \
S3_SECRET="aFDkj28Jbs2JKbnvJH678MNwiz88zKjsuNBHHs" \
S3_BUCKET="s3brix365" \
S3_SSL_ENABLED="false" \
S3_UPLOAD_METHOD="PUT" \
S3_DUMP_URL="" \
S3_VIRTUAL_HOSTED_STYLE_ENABLED="false"  

  1. Make sure the secret is created at the path secret/brix365/db:

vault kv get secret/brix365/db  

  1. Enable the Kubernetes authentication method:

vault auth enable kubernetes    

  1. Configure the Kubernetes authentication method to use the Kubernetes API location:

vault write auth/kubernetes/config \
kubernetes_host="https://$KUBERNETES_PORT_443_TCP_ADDR:443"

  1. Create a policy for reading secrets at the address secret/data/brix365/db:

vault policy write read-secret-brix365 - <<EOF
path "secret/data/brix365/db" {
  capabilities = ["read"]
}
EOF

  1. Create a role named read-secret-brix365, which links the read-secret-brix365 policy to the vault-auth service account in the namespace where BRIX is installed (e.g., brix365). The service account is created with the following command:

vault write auth/kubernetes/role/read-secret-brix365 \
bound_service_account_names=vault-auth \
bound_service_account_namespaces=brix365 \
policies=read-secret-brix365 \
ttl=24h

  1. Exit Vault: 

exit

  1. Create the vault-auth service account in the namespace where BRIX is installed (e.g., brix365):

kubectl create serviceaccount vault-auth -n brix365

Secrets in the Kubernetes cluster can be synchronized using HashiCorp Vault with the External Secrets Operator. Read more in Install External Secrets Operator.

Back up and update Vault (optional)

Начало внимание

Starting with chart version 0.34.1 (Vault 2.0.4), Vault is installed using the official HashiCorp chart instead of the Bitnami chart. As a result, the structure of the values-vault.yaml configuration file has changed.

Конец внимание

To upgrade an earlier version of Vault to version 2.0.4:

  1. Back up the Vault database.
  2. Upgrade the Vault service using Helm.
  3. Restore the Vault data from the backup.

Step 1. Back up Vault

Before upgrading Vault from an earlier version to version 2.0.4, make sure to back up the Vault database. This backup will allow you to restore access to secrets if a failure occurs.

  1. Connect to the vault-server-0 pod in the current Vault service deployment and log in using the root token:

kubectl exec -ti vault-server-0 -n vault -- vault login <Initial Root Token>

Important: Save this root token, as you will need it to restore the data from backup.

  1. Create a backup of the Raft database and save it to a temporary file named backup.snap inside the Vault service pod:

kubectl exec -ti vault-server-0 -n vault -- vault operator raft snapshot save /tmp/backup.snap

  1. Copy the temporary backup.snap file to the local server:

kubectl cp vault/vault-server-0:/tmp/backup.snap ./backup.snap -n vault

Step 2. Upgrade the Vault service using Helm

  1. Uninstall the current Vault Helm release:

helm uninstall vault -n vault

  1. Prepare a new values-vault.yaml configuration file, then install and configure the new version of Vault. For instructions, see steps 1-4 in Install and configure HashiCorp Vault.

Step 3. Restore the data from the backup

Restore the data from the saved backup:

  1. Copy the previously saved backup.snap file to the new Vault service pod:

kubectl cp ./backup.snap vault/vault-0:/tmp/backup.snap -n vault

  1. Log in to the new Vault service pod using the root token:

kubectl exec -ti vault-0 -n vault -- vault login <Initial Root Token>

  1. Restore the database from the backup:

kubectl exec -ti vault-0 -n vault -- vault operator raft snapshot restore -force /tmp/backup.snap

  1. After the forced restore, Vault will enter the sealed state (`Sealed: true`), and the user and token database will revert to its state at the time the backup was created. Unseal Vault using the three unseal keys (Unseal Key) from the previous installation:

kubectl exec vault-0 -n vault -- vault operator unseal <Old Unseal Key 1>
kubectl exec vault-0 -n vault -- vault operator unseal <Old Unseal Key 2>
kubectl exec vault-0 -n vault -- vault operator unseal <Old Unseal Key 3>

  1. Log in using the previous root token that was valid when the backup was created:

kubectl exec -ti vault-0 -n vault -- vault login <Old Initial Root Token>

 

Remove Vault using Helm in the Kubernetes cluster

To uninstall the Vault service in the vault namespace, execute the command:

helm uninstall vault -n vault

install-longhorn.html install-external-secrets-operator.html