Skip to main content

HashiCorp Vault Secret Sync

vCluster Platform 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, virtual clusters and global vCluster Platform 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 Platform, syncing Vault secrets to global and project secrets, and storing the Vault token in a Kubernetes secret for access by vCluster Platform.

Prerequisites​

Before you begin, make sure you have the following:

  • A running vCluster Platform instance
  • A running HashiCorp Vault instance
  • Vault token with appropriate permissions
  • Optional: Admin access to the vCluster Platform 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 Platform, create a Secret resource:

apiVersion: v1
kind: Secret
metadata:
  name: secret-containing-token
  namespace: vcluster-platform
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 Platform 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 Platform configuration with the Vault object to set up a global Vault integration.

  1. Log in to the vCluster Platform UI as admin and navigate to the Admin section using the menu on the left.

  2. Edit the vCluster Platform 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 Platform configuration reference and the Vault configuration options.

  3. Save the changes to the configuration using the button and wait for vCluster Platform 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-platform
  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​

enabled required boolean pro​

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 virtual clusters.

address required string pro​

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 pro​

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

namespace required string pro​

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

auth required object pro​

Auth defines the authentication method to use for this project.

token required string pro​

Token defines the token to use for authentication.

tokenSecretRef required object pro​

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 pro​

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. TODO: Add other useful fields. apiVersion, kind, uid? More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Drop kubebuilder:default when controller-gen doesn't need it https://github.com/kubernetes-sigs/kubebuilder/issues/3896.

key required string pro​

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

optional required boolean pro​

Specify whether the Secret or its key must be defined

syncInterval required string pro​

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