vault

Documentation

Overview

Package vault provides a HashiCorp Vault SecretSource adapter (ADR-0002 §6) for go.dagstack.dev/config.

Sub-module: lives in its own go.mod so the official hashicorp/vault/api dependency does not leak into binaries that only use file sources. Import as `go.dagstack.dev/config/vault` separately from `go.dagstack.dev/config`.

Phase 2 scope (ADR-0002 §6.1 / §6.2):

• KV v2 only.
• Token + AppRole auth (mandatory) + Kubernetes ServiceAccount auth (optional).
• Namespace support (Vault Enterprise).
• ?version=N query.
• #field projection.

Token self-renewal lands alongside the Phase 3 rotation hook in the upstream `config` package.

Stutter-avoidance note: this sub-package extracts secrets out of the main `config` package, so the canonical type name is `vault.Source`, not `vault.VaultSource`. Bindings importing it will write `vault.NewSource(...)` (no stutter at the call site).

Index

• type AppRoleAuth
• type Auth
• type KubernetesAuth
• type Option
  • func WithNamespace(ns string) Option
  • func WithTLSConfig(cfg *vaultapi.TLSConfig) Option
• type Source
  • func NewSource(addr string, auth Auth, opts ...Option) (*Source, error)
  • func (s *Source) Close() error
  • func (s *Source) ID() string
  • func (s *Source) Resolve(ctx context.Context, path string) (config.SecretValue, error)
  • func (*Source) Scheme() string
• type TokenAuth

Types

type AppRoleAuth

type AppRoleAuth struct {
	RoleID     string
	SecretID   string
	MountPoint string // default: "approle"
}

AppRoleAuth — AppRole authentication, the production CI/CD pipeline default.

type Auth

type Auth interface {
	// contains filtered or unexported methods
}

Auth is the discriminated union of supported Vault auth methods. New methods (AWS IAM, JWT/OIDC, TLS client certificate) land per operator demand in Phase 3.

type KubernetesAuth

type KubernetesAuth struct {
	Role       string
	JWTPath    string // default: /var/run/secrets/kubernetes.io/serviceaccount/token
	MountPoint string // default: "kubernetes"
}

KubernetesAuth — Kubernetes ServiceAccount authentication. Reads the SA JWT from the standard projected-token path; one auth/kubernetes/login round-trip per Source lifetime (no in-flight renewal in Phase 2).

type Option

type Option func(*sourceOptions)

Option configures NewSource.

func WithNamespace

func WithNamespace(ns string) Option

WithNamespace sets a Vault Enterprise namespace.

func WithTLSConfig

func WithTLSConfig(cfg *vaultapi.TLSConfig) Option

WithTLSConfig overrides the default TLS configuration.

type Source

type Source struct {
	// contains filtered or unexported fields
}

Source implements config.SecretSource for HashiCorp Vault KV v2.

Path layout: the user-visible path is what `vault kv get` accepts (e.g. `secret/dagstack/prod/openai`). The first segment is the KV v2 mount point (default Vault setup uses `secret`); the remainder is the logical key path. The Vault HTTP API expects `<mount>/data/<path>` — this Source rewrites it internally.

Path also supports the optional ?version=N query (read a specific KV v2 version) and the #field projection (pluck a sub-key from a multi-key secret) per ADR-0002 §6.3.

func NewSource

func NewSource(addr string, auth Auth, opts ...Option) (*Source, error)

NewSource constructs a Vault Source. addr is the base URL of the Vault server (e.g. "https://vault.example.com"). auth selects the authentication method. opts apply additional options (WithNamespace, WithTLSConfig).

func (*Source) Close

func (s *Source) Close() error

Close releases any resources held by the underlying Vault client. hashicorp/vault/api uses an http.Client; we close the underlying transport's idle-connection pool for cleanliness. Token revocation is NOT performed automatically — operators that want it call the raw client API themselves before Close.

func (*Source) ID

func (s *Source) ID() string

ID implements config.SecretSource.

func (*Source) Resolve

func (s *Source) Resolve(ctx context.Context, path string) (config.SecretValue, error)

Resolve implements config.SecretSource.

func (*Source) Scheme

func (*Source) Scheme() string

Scheme implements config.SecretSource. Hard-coded to "vault".

type TokenAuth

type TokenAuth struct{ Token string }

TokenAuth — direct Vault token. Simplest case; covers any deployment that already injects a token via init-container or operator action.