Skip to main content
Version: v5.0 Stable

HashiCorp Vault Secret Sync

Enterprise
Available in these plansFreeDevProdScale
HashiCorp Vault Integration

Free, Dev, Prod, and Scale are vCluster Platform license plans. Open source does not need a license or a Platform connection. See Compare open source and free tiers.

vCluster Platform syncs secrets from a HashiCorp Vault instance into project secrets. This lets you use secrets from Vault in your projects and clusters without copying them manually or using third-party tools.

Vault is configured per project

v5.0 removed the platform-wide vault block from the Platform configuration. If an upgraded configuration still contains it, Platform ignores the block and logs a warning. Set up Vault in each project that needs it.

This guide walks you through setting up a project-based Vault integration, syncing Vault secrets to project secrets, and storing the Vault token in a Kubernetes secret that vCluster Platform can read.

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: Store 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: <project-namespace>
type: Opaque
data:
VAULT_TOKEN: <your-base64-encoded-vault-token>
Secret namespace

Line 5 sets the namespace of the project that uses the Vault token. Replace <project-namespace> with that namespace, for example p-my-project.

Setup​

Project-based Vault integration​

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

  1. Select your project in the project switcher in the sidebar.

  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.

Sync Vault secrets​

After you set up the Vault integration, you can sync Vault secrets to project secrets.

For the Vault sync to work, add three annotations to the project secret:

  • 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.

To sync a Vault secret to a project secret, 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.

Adjust the annotations to your Vault secret accordingly.

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

Configuration options​

enabled boolean ​

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

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

namespace string ​

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

auth object ​

Auth defines the authentication method to use for this project.

token string ​

Token defines the token to use for authentication.

tokenSecretRef 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 string ​

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. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

key required string ​

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

optional boolean ​

Specify whether the Secret or its key must be defined

syncInterval 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.