Access Management Architecture · Topic 2 of 2

Vault Secrets Operator

Vault Associate 003: how the Vault Secrets Operator syncs Vault secrets into Kubernetes Secrets, its custom resources, instant updates and client cache.

  • 4 min
In a nutshell
  • VSO syncs Vault secrets into Kubernetes Secrets so Pods consume them natively.
  • It is driven by custom resources: VaultConnection, VaultAuth, VaultStaticSecret, VaultDynamicSecret and VaultPKISecret.
  • VSO keeps the Kubernetes Secret in sync and remediates drift.

What it is

The Vault Secrets Operator (VSO) lets Kubernetes Pods consume Vault secrets natively as Kubernetes Secrets. It runs as an operator in the cluster and is a supported component of HashiCorp Vault.

The challenge it solves is that applications in Kubernetes already know how to read a Kubernetes Secret, but the source of truth should be Vault. VSO copies the data from Vault into the Secret and keeps the two in sync, so the application never needs Vault access.

Vaultsource of truthVSOwatches custom resourcesKubernetes Secretsynced copyPodreads the Secret

How it works

Why an operator

Without VSO, each team must write code or run a sidecar to authenticate to Vault and fetch secrets. With VSO, platform engineers declare what to sync in YAML, and developers consume ordinary Kubernetes Secrets.

The operator also does the repeated work: it refreshes secrets and keeps its Vault tokens and leases tracked.

Custom resources

VSO watches custom resource definitions (CRDs). Each one tells the operator what to sync.

CRDPurpose
VaultConnectionHow to reach a Vault server: address, TLS settings
VaultAuthHow VSO authenticates, with the auth method, mount and role
VaultStaticSecretSyncs a static secret from KV v1 or KV v2
VaultDynamicSecretSyncs dynamic credentials, such as from the database or AWS engines
VaultPKISecretSyncs a certificate issued by the PKI secrets engine

VSO can authenticate with Kubernetes, JWT, AppRole, AWS or GCP. It is installed with Helm or Kustomize.

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: app-config
spec:
  vaultAuthRef: default
  mount: kvv2
  type: kv-v2
  path: app/config
  destination:
    name: app-config
    create: true

This resource reads app/config from the KV v2 mount kvv2 and writes it into a Kubernetes Secret named app-config. Add refreshAfter to set how often VSO reads it again.

Features to know

Drift and rotation. VSO remediates drift when someone changes the Kubernetes Secret by hand. It can also trigger a rollout restart of Deployments, ReplicaSets and StatefulSets when a secret changes.

Instant updates. VSO subscribes to Vault events and updates the Kubernetes Secret as soon as the secret changes, instead of waiting for the next refresh. This needs Vault Enterprise. Event delivery is not guaranteed, so the docs still recommend setting a refreshAfter interval.

Encrypted client cache. VSO can cache its Vault client data, such as tokens and leases, in Kubernetes Secrets in the operator's namespace. Persistence and encryption are off by default because they need extra setup: encryption uses the transit secrets engine, with a key and a policy allowing encrypt and decrypt on it.

Secret transformation. VSO can transform secret data before it is written to the destination Secret. Transformations can sit inside the secret custom resource, in a separate SecretTransformation resource, or both.

Secret changes in VaulteventVSOupdatesKubernetes Secret

Agent or Operator

QuestionVault AgentVault Secrets Operator
Runs asDaemon or sidecarKubernetes operator
Delivers secrets asFiles or environment variablesKubernetes Secrets
Configured withA config fileKubernetes custom resources

How the exam asks about this

  • "Applications on Kubernetes should consume Vault secrets as native Kubernetes Secrets without Vault code." Vault Secrets Operator.
  • "Which feature updates a Kubernetes Secret as soon as the secret changes in Vault?" Instant updates, which require Vault Enterprise.
  • "Which resource tells VSO how to log in to Vault?" VaultAuth, which refers to a VaultConnection.

What to remember for the exam

  • VSO syncs Vault secrets into Kubernetes Secrets so Pods consume them natively.
  • It is driven by custom resources: VaultConnection, VaultAuth, VaultStaticSecret, VaultDynamicSecret and VaultPKISecret.
  • VSO keeps the Kubernetes Secret in sync and remediates drift.
  • Instant updates use Vault events and need Vault Enterprise.
  • The client cache can store tokens and leases and encrypt them with the transit engine, but it is off by default.
  • Secret transformation reshapes the data before it lands in the Kubernetes Secret.
Watch out

A Kubernetes Secret is not Vault. The synced copy lives in the cluster, by default in etcd, so protect access to Secrets in that namespace.

Common mistakes

Choosing VSO for non-Kubernetes workloads. VSO exists to serve Kubernetes. For a virtual machine or a legacy application, Vault Agent is the fit.

Expecting instant updates in Community Edition. The feature depends on Vault Enterprise. Without it, VSO relies on the periodic refresh.

Thinking VSO stores secrets in Vault. VSO only reads from Vault and copies data into Kubernetes Secrets. Vault stays the source of truth.

Check yourself

  • What does the Vault Secrets Operator do?

    It watches custom resources and syncs secrets from Vault into Kubernetes Secrets, keeping them up to date for Pods.

  • Which VSO feature needs Vault Enterprise?

    Instant updates, which subscribe to Vault events so Kubernetes Secrets change right away.

  • How is the VSO client cache protected?

    Persistence and encryption are optional, and encryption uses Vault's transit secrets engine.

Topic 2 of 2 in Access Management Architecture

Test yourself on Access Management Architecture

The full HashiCorp Vault Associate 003 question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.