Skip to main content
Version: master

HashiCorp Vault Secret Sync

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

Prerequisites

Before you begin, make sure you have the following:

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

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

  1. Log in to the Loft UI as admin and navigate to the Admin section using the menu on the left.
  2. Edit the Loft 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 Loft configuration reference and the Vault configuration options.

  3. Save the changes to the configuration using the button and wait for Loft 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: loft
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
key required string
optional required boolean true

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.