Secret Store Vault

Vault-backed secret store proxy for UXP. This Upbound AddOn deploys a TLS-secured proxy that presents a Kubernetes Secrets-compatible API backed by HashiCorp Vault, allowing controllers like Crossplane and its providers to store and retrieve secrets from Vault without any code changes.

Overview

Secret Store Vault runs as a separate deployment in the control plane. It watches a cluster-scoped StoreConfig custom resource for Vault connection details and exposes the standard Kubernetes Secret API endpoints (/api/v1/namespaces/{namespace}/secrets/...). Secrets are transparently read from and written to a Vault KV secrets engine (v1 or v2).

Key capabilities:

• Kubernetes-native API - GET, PUT, POST, DELETE, and LIST on Secrets with JSON and Protobuf support.
• Vault KV v1 and v2 - Configurable secrets engine version with optimistic concurrency on v2.
• Authentication - Kubernetes service account auth (recommended) or static token auth with automatic re-authentication on token expiry.
• TLS - Mutual TLS, custom CA bundles, or skip-verify for development.
• Garbage collection - Automatic cleanup of orphaned secrets via owner-reference tracking with watch, poll, or hybrid GC modes.
• Observability - Prometheus metrics, structured logging, health and readiness endpoints.

Compatibility

Installation

Save the following manifest and apply it to your control plane:

apiVersion: pkg.upbound.io/v1alpha1
kind: AddOn
metadata:
  name: secret-store-vault
spec:
  package: xpkg.upbound.io/upbound/secret-store-vault-addon:v0.1.0

kubectl apply -f addon.yaml

Configuration

Once the AddOn is installed, create a StoreConfig resource to connect to your Vault instance:

apiVersion: vault.secrets.upbound.io/v1alpha1
kind: StoreConfig
metadata:
  name: vault
spec:
  address: https://vault.example.com:8200
  kvVersion: KVv2
  mountPath: secret
  auth:
    method: kubernetes
    kubernetes:
      role: secret-store-vault
  tls:
    caBundleSecretRef:
      name: vault-tls
      namespace: vault-system
      key: ca.crt

Only one StoreConfig is supported per control plane. The controller reconciles it and reports readiness via status conditions:

kubectl get storeconfigs

StoreConfig Reference

Garbage Collection

Orphaned secrets (whose Kubernetes owner resources no longer exist) are automatically cleaned up. Configure the mode with these flags:

Development

# Build
make build

# Run tests
make test

# Build container image
make docker-build