Skip to main content

HashiCorp Vault Secret Sync

vCluster.Pro supports syncing secrets from a HashiCorp Vault instance into both project secrets and global secrets. This feature allows you to use secrets from Vault in your projects, vclusters and global vCluster.Pro tenant without copying them manually or using third-party tools.

This guide will walk you through setting up global and project-based Vault integrations with vCluster.Pro, syncing Vault secrets to global and project secrets, and storing the Vault token in a Kubernetes secret for access by vCluster.Pro.

Prerequisites​

Before you begin, make sure you have the following:

  • A running vCluster.Pro instance
  • A running HashiCorp Vault instance
  • Vault token with appropriate permissions
  • Optional: Admin access to the vCluster.Pro instance, if you intend to set up a global secret sync

Optional: Storing the Vault Token in a Kubernetes Secret​

To store the Vault token in a Kubernetes secret and make it accessible for vCluster.Pro, create a Secret resource:

apiVersion: v1
kind: Secret
metadata:
  name: secret-containing-token
  namespace: vcluster-pro
type: Opaque
data:
  VAULT_TOKEN: <your-base64-encoded-vault-token>
Secret namespace

Line 4 of this secret requires one to either specify the namespace of the vCluster.Pro installation, if the Vault token will be used for global secrets syncing, or the namespace of the project you want to use the Vault Token in.

Setup​

Global Vault Integration​

You must update the vCluster.Pro configuration with the Vault object to set up a global Vault integration.

  1. Log in to the vCluster.Pro UI as admin and navigate to the Admin section using the menu on the left.
  2. Edit the vCluster.Pro configuration by adding the Vault object with the following properties:
    vault:
      enabled: true
      address: https://your-vault-instance:8200
      auth:
        tokenSecretRef:
          name: secret-containing-token
          key: VAULT_TOKEN
    Don't forget to change default values

    Replace https://your-vault-instance:8200 with the address of your Vault instance.

    Replace secret-containing-token with the name of the secret containing the Vault token in the loft namespace.

    For further configuration options, see the vCluster.Pro configuration reference and the Vault configuration options.

  3. Save the changes to the configuration using the button and wait for vCluster.Pro to restart.

Project-Based Vault Integration​

You need to update the project specification with the Vault object to set up a project-based Vault integration.

  1. Navigate to Projects and then select the desired project.
  2. Edit the project specification by adding the Vault object within the spec section:
    vault:
      enabled: true
      address: https://your-vault-instance:8200
      auth:
        tokenSecretRef:
          key: VAULT_TOKEN
          name: secret-containing-token
    Don't forget to change default values

    Replace https://your-vault-instance:8200 with the address of your Vault instance.

    Replace secret-containing-token with the name of the secret containing the Vault token in the project's namespace.

    For further configuration options, see the Project reference and the Vault configuration options.

  3. Save the changes to the project settings by pressing the button.

Syncing Vault Secrets​

Once you have set up the Vault integration, you can sync Vault secrets to global and project secrets.

For the Vault sync to work, one has to add three annotations to the Global Secret or Project Secret of one's choice:

  • loft.sh/vault-kv-version: Defines the KV version of the Vault secret. Can be either kv1 or kv2.
  • loft.sh/vault-kv-mount-path: Defines the mount path of the Vault secret.
  • loft.sh/vault-kv-secret-path: Defines the path of the Vault secret.

Global Secrets​

To sync Vault secrets to global secrets, one can create a SharedSecret resource using the following example specification:

apiVersion: management.loft.sh/v1
kind: SharedSecret
metadata:
  name: my-secret
  namespace: vcluster-pro
  annotations:
    loft.sh/vault-kv-version: kv2
    loft.sh/vault-kv-mount-path: secrets
    loft.sh/vault-kv-secret-path: global_secret
spec:
  access:
    - users:
        - admin
      verbs:
        - "*"
      subresources:
        - "*"
note

Lines 7 to 9 specify the Vault secret sync annotations, which are required for the sync to work.

Please adjust the annotations to your Vault secret accordingly.

Project Secrets​

To sync Vault secrets to project secrets, one can create a ProjectSecret resource using the following example specification:

apiVersion: management.loft.sh/v1
kind: ProjectSecret
metadata:
  name: my-secret
  annotations:
    loft.sh/vault-kv-version: kv2
    loft.sh/vault-kv-mount-path: secrets
    loft.sh/vault-kv-secret-path: my_secret
spec: {}
note

Lines 6 to 8 specify the Vault secret sync annotations, which are required for the sync to work.

Please adjust the annotations to your Vault secret accordingly.

Apply the appropriate YAML configuration using kubectl to create or update the secrets.

Configuration Options​

vault required object ​

VaultIntegration holds information about Vault Integration

enabled required boolean false ​

Enabled indicates if the Vault Integration is enabled for the project -- this knob only enables the syncing of secrets to or from Vault, but does not setup Kubernetes authentication methods or Kubernetes secrets engines for vclusters.

address required string ​

Address defines the address of the Vault instance to use for this project. Will default to the VAULT_ADDR environment variable if not provided.

skipTLSVerify required boolean false ​

SkipTLSVerify defines if TLS verification should be skipped when connecting to Vault.

namespace required string ​

Namespace defines the namespace to use when storing secrets in Vault.

auth required object ​

Auth defines the authentication method to use for this project.

token required string ​

Token defines the token to use for authentication.

tokenSecretRef required object ​

TokenSecretRef defines the Kubernetes secret to use for token authentication. Will be used if token is not provided.

Secret data should contain the token key.

name required string ​

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid?

key required string ​

The key of the secret to select from. Must be a valid secret key.

optional required boolean false ​

Specify whether the Secret or its key must be defined

syncInterval required string ​

SyncInterval defines the interval at which to sync secrets from Vault. Defaults to 1m. See https://pkg.go.dev/time#ParseDuration for supported formats.

Last updated on