FerrVault

The FerrVault operator reads the secrets of one vault environment and writes them into an ordinary Kubernetes Secret. Your workloads read that Secret as usual. The operator keeps it in sync, deletes it with the resource that declared it, and can restart the workloads that consume it when a value changes.

It needs a service-account token with the viewer role on the vault environment you want to sync. Mint one per cluster.

1. Install the operator

The chart is published as an OCI artifact on GHCR:

helm install ferrvault-operator oci://ghcr.io/ferrlabs/charts/ferrvault-operator \
  --namespace ferrvault-system --create-namespace

Upgrade with helm upgrade against the same release. The CRDs are kept on uninstall, so removing the chart never deletes your resources or the Secrets they manage.

2. Store the token

Put the token in a Secret, in the namespace of the workload that needs it:

kubectl -n my-app create secret generic ferrvault-sat --from-literal=token='fvsat_...'

3. Declare the connection and the secret

apiVersion: ferrvault.com/v1alpha1
kind: FerrVaultConnection
metadata:
  name: ferrvault
  namespace: my-app
spec:
  url: https://api.ferrvault.com
  organization: acme
  tokenSecretRef:
    name: ferrvault-sat
    key: token
---
apiVersion: ferrvault.com/v1alpha1
kind: FerrVaultSecret
metadata:
  name: web-env
  namespace: my-app
spec:
  connectionRef:
    name: ferrvault
  project: web
  vault: web
  selector:
    names: [DATABASE_URL, STRIPE_KEY]
  target:
    name: web-env
  refreshInterval: 30m
  rolloutRestart:
    - kind: Deployment
      name: api
  • vault is the vault's slug, and must match the vault the token is bound to. The environment comes from the token, so there is no field for it.
  • organization and project are required by the CRDs today but not used: the token already decides what the operator can read. Any non-empty value works.
  • selector.names lists the secrets to sync. Leave it out to sync every secret of the environment.
  • target.name is the Secret to write. It defaults to the resource's own name.
  • refreshInterval is how often values are pulled again. A change to the resource is applied immediately.
  • rolloutRestart names the workloads to restart when the synced values change.

4. Check it

kubectl -n my-app get ferrvaultsecrets
kubectl -n my-app describe ferrvaultsecret web-env

A healthy resource is Ready and shows when it last synced. If some requested names do not exist in the environment, it stays Ready=False and lists them, and the other keys are still written.

Reshaping values

spec.transforms rewrites values before they land in the Secret, in order:

type Fields Effect
prefix value Prepends value to every key.
suffix value Appends value to every key.
rename from, to Renames one key.
base64Decode keys (optional) Decodes the listed keys, or all of them, from base64.
jsonExpand key Flattens a JSON object into <KEY>_<SUB> keys.

A transform that fails leaves the resource Ready=False with Reason=TransformError, and the Secret keeps its last good value.