Home

Appearance

Vault + External Secrets Operator ​

This guide covers deploying HashiCorp Vault as a central secret store and External Secrets Operator (ESO) to sync secrets into Kubernetes automatically.

Architecture ​

[Vault]  namespace: vault
   │  Kubernetes auth method (ServiceAccount token exchange)
   ▼
[ESO ClusterSecretStore]  — cluster-wide, references Vault KV v2
   │  ExternalSecret CRs per namespace
   ▼
[Kubernetes Secrets]  — consumed natively by pods / Helm charts

Storage: Vault uses Raft integrated storage backed by a local-path PVC — no external Consul or etcd required.

Auth: ESO authenticates to Vault via the Kubernetes auth method. ESO's own ServiceAccount token is exchanged for a scoped Vault token at sync time.

UI access: Vault UI is behind the WireGuard vpn-only middleware. Bring up your WireGuard VPN connection before opening the browser.

Secret path layout ​

Vault pathKubernetes SecretNamespace
secret/argocd/oidcargocd-secretargocd
secret/grafana/admingrafana-admin-secretmonitoring
secret/grafana/oauthgrafana-oauth-secretmonitoring
secret/traefik/dashboardtraefik-dashboard-authingress

Prerequisites ​

Add to .env:

bash
VAULT_DOMAIN=vault.example.com

Add DNS A record: vault.example.com → SERVER_IP

Step 1 — Deploy Vault ​

Deploy the platform-vault OCI chart via ArgoCD or directly with Helm:

bash
helm upgrade --install platform-vault \
  oci://ghcr.io/kevindebenedetti/charts/platform-vault \
  --version 0.7.4 \
  --namespace vault --create-namespace \
  --values platform/vault/values.yaml

This installs Vault into the vault namespace with:

  • Single-replica Raft storage (5 Gi PVC on local-path)
  • UI enabled (ClusterIP, exposed via Traefik IngressRoute)
  • VPN-only IngressRoute + Let's Encrypt TLS cert

⚠️ Vault starts sealed and uninitialized — proceed to Step 2.

Step 2 — Initialize Vault ​

bash
task vault:init

This script:

  1. Calls vault operator init (3 key shares, threshold 2)
  2. Unseals Vault with the generated keys
  3. Enables KV v2 at secret/
  4. Enables and configures Kubernetes auth
  5. Creates the eso-read policy and eso role

Output:

════════════════════════════════════════════════════════════════
  ⚠️  VAULT INIT OUTPUT — SAVE THIS IMMEDIATELY
  These keys and token will NEVER be shown again.
════════════════════════════════════════════════════════════════

Unseal Key 1: abc123...
Unseal Key 2: def456...
Unseal Key 3: ghi789...

Root Token:   hvs.XXXXX

📋 Store these in a password manager immediately. You will need 2 of the 3 unseal keys any time the Vault pod restarts (e.g., after a node reboot).

Add to .env for convenience (never commit):

bash
VAULT_ROOT_TOKEN=hvs.XXXXX
VAULT_UNSEAL_KEY_1=abc123...
VAULT_UNSEAL_KEY_2=def456...

Step 3 — Seed secrets into Vault ​

bash
VAULT_ROOT_TOKEN=hvs.XXXXX task vault:seed

The interactive prompt walks you through storing each secret:

  • secret/argocd/oidc — Infomaniak OIDC clientID + clientSecret
  • secret/grafana/admin — Grafana admin username + password
  • secret/grafana/oauth — All GF_AUTH_* OAuth env vars
  • secret/traefik/dashboard — Traefik BasicAuth password

Step 4 — Deploy External Secrets Operator ​

bash
ArgoCD deploys External Secrets Operator from Git. No manual deploy command is needed.

Installs the external-secrets/external-secrets Helm chart into the external-secrets namespace.

Step 5 — Apply ClusterSecretStore + ExternalSecrets ​

bash
# In your infra repo:
kubectl apply -f secrets/cluster-secret-store.yaml
kubectl apply -f secrets/

ESO immediately begins syncing. Check status:

bash
task vault:status

Day 2 — Unsealing after reboot ​

Vault becomes sealed when the pod restarts. Unseal with:

bash
task vault:unseal   # requires VAULT_UNSEAL_KEY_1 + VAULT_UNSEAL_KEY_2 in .env

Or interactively:

bash
kubectl exec -it -n vault vault-0 -- env VAULT_SKIP_VERIFY=true vault operator unseal

Adding new secrets ​

  1. Write to Vault:

    bash
     kubectl exec -n vault vault-0 -- \
   env VAULT_TOKEN="${VAULT_TOKEN:?set-from-vault-init}" VAULT_SKIP_VERIFY=true \
   vault kv put secret/myapp/config \
     DB_PASSWORD=secret123 \
     API_KEY=key456

  2. Create an ExternalSecret manifest:

    yaml
    apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: myapp-secret
  namespace: apps
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault
    kind: ClusterSecretStore
  target:
    name: myapp-secret
    creationPolicy: Owner
  data:
    - secretKey: DB_PASSWORD
      remoteRef:
        key: secret/myapp/config
        property: DB_PASSWORD
    - secretKey: API_KEY
      remoteRef:
        key: secret/myapp/config
        property: API_KEY

  3. Apply: kubectl apply -f myapp-externalsecret.yaml

Taskfile reference ​