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.