HCP Vault Secrets Centralized secrets lifecycle management for developers. Learn More
Vault
Vault Home

Vault secrets operator

The Vault Secrets Operator (VSO) allows Pods to consume Vault secrets natively from Kubernetes Secrets.

Overview

The Vault Secrets Operator operates by watching for changes to its supported set of Custom Resource Definitions (CRD). Each CRD provides the specification required to allow the Operator to synchronize a Vault Secrets to a Kubernetes Secret. The Operator writes the source Vault secret data directly to the destination Kubernetes Secret, ensuring that any changes made to the source are replicated to the destination over its lifetime. In this way, an application only needs to have access to the destination secret in order to make use of the secret data contained within.

Features

The following features are supported by the Vault Secrets Operator:

  • All Vault secret engines supported.
  • TLS/mTLS communications with Vault.
  • Authentication to Vault with any of the following Auth Methods:
  • Secret rotation for Deployment, ReplicaSet, StatefulSet Kubernetes resource types.
  • Prometheus instrumentation for monitoring the Operator
  • Support for installing using: Helm or Kustomize
    see the installation docs for more details

Supported Vault versions

Supported kubernetes versions

The following Kubernetes minor releases are currently supported. The latest version is tested against each Kubernetes version. It may work with other versions of Kubernetes, but those are not supported.

  • 1.27
  • 1.26
  • 1.25
  • 1.24
  • 1.23

Supported Cloud providers

The Vault Secrets Operator has been tested successfully in the following hosted Kubernetes environments:

  • Amazon Elastic Kubernetes Service (EKS)
  • Google Kubernetes Engine (GKE)
  • Microsoft Azure Kubernetes Service (AKS)
  • Red Hat OpenShift

Basic integration tests are available in the project repository. Please report any incompatibilities via a Github Issue.

Vault access and custom resource definitions

The Vault connection and authentication configuration is provided by the VaultConnection and VaultAuth CRDs. These can be considered as foundational Custom Resources that all secret replication type resources will reference.

VaultConnection custom resource

Provides the configuration necessary for the Operator to connect to a single Vault server instance.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultConnection
metadata:
  namespace: vso-example
  name: example
spec:
  # required configuration
  # address to the Vault server.
  address: http://vault.vault.svc.cluster.local:8200

  # optional configuration
  # HTTP headers to be included in all Vault requests.
  # headers: []
  # TLS server name to use as the SNI host for TLS connections.
  # tlsServerName: ""
  # skip TLS verification for TLS connections to Vault.
  # skipTLSVerify: false
  # the trusted PEM encoded CA certificate chain stored in a Kubernetes Secret
  # caCertSecretRef: ""

VaultAuth custom resource

Provide the configuration necessary for the Operator to authenticate to a single Vault server instance as specified in a VaultConnection Custom Resource.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
  namespace: vso-example
  name: example
spec:
  # required configuration
  # VaultConnectionRef of the corresponding VaultConnection CustomResource.
  # If no value is specified the Operator will default to the `default` VaultConnection,
  # configured in its own Kubernetes namespace.
  vaultConnectionRef: example
  # Method to use when authenticating to Vault.
  method: kubernetes
  # Mount to use when authenticating to auth method.
  mount: kubernetes
  # Kubernetes specific auth configuration, requires that the Method be set to kubernetes.
  kubernetes:
    # role to use when authenticating to Vault
    role: example
    # ServiceAccount to use when authenticating to Vault
    # it is recommended to always provide a unique serviceAccount per Pod/application
    serviceAccount: default

  # optional configuration
  # Vault namespace where the auth backend is mounted (requires Vault Enterprise)
  # namespace: ""
  # Params to use when authenticating to Vault
  # params: []
  # HTTP headers to be included in all Vault authentication requests.
  # headers: []

Vault secret custom resource definitions

Provide the configuration necessary for the Operator to replicate a single Vault Secret to a single Kubernetes Secret. Each supported CRD is specialized to a class of Vault secret, documented below.

VaultStaticSecret custom resource

Provides the configuration necessary for the Operator to synchronize a single Vault static Secret to a single Kubernetes Secret.
Supported secrets engines: kv-v2, kv-v1

KV version 1 secret example

The KV secrets engine's kvv1 mount path is specified under spec.mount of VaultStaticSecret custom resource. Please consult KV Secrets Engine - Version 1 - Setup for configuring KV secrets engine version 1. The following results in a request to http://127.0.0.1:8200/v1/kvv1/eng/apikey/google to retrieve the secret.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  namespace: vso-example
  name: example
spec:
  vaultAuthRef: example
  mount: kvv1
  type: kv-v1
  path: eng/apikey/google
  refreshAfter: 60s
  destination:
    create: true
    name: static-secret1
KV version 2 secret example

The KV secrets engine's kvv2 mount path is specified under spec.mount of VaultStaticSecret custom resource. Please consult KV Secrets Engine - Version 2 - Setup for configuring KV secrets engine version 2. The following results in a request to http://127.0.0.1:8200/v1/kvv2/data/eng/apikey/google?version=2 to retrieve the secret.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  namespace: vso-example
  name: example
spec:
  vaultAuthRef: example
  mount: kvv2
  type: kv-v2
  path: eng/apikey/google
  version: 2
  refreshAfter: 60s
  destination:
    create: true
    name: static-secret2

VaultPKISecret custom resource

Provides the configuration necessary for the Operator to synchronize a single Vault PKI Secret to a single Kubernetes Secret.
Supported secrets engines: pki

The PKI secrets engine's mount path is specified under spec.mount of VaultPKISecret custom resource. Please consult PKI Secrets Engine - Setup and Usage for configuring PKI secrets engine. The following results in a request to http://127.0.0.1:8200/v1/pki/issue/default to generate TLS certificates.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultPKISecret
metadata:
  namespace: vso-example
  name: example
spec:
  vaultAuthRef: example
  mount: pki
  role: default
  commonName: example.com
  format: pem
  expiryOffset: 1s
  ttl: 60s
  namespace: tenant-1
  destination:
    create: true
    name: pki1

VaultDynamicSecret custom resource

Provides the configuration necessary for the Operator to synchronize a single Vault dynamic Secret to a single Kubernetes Secret.
Supported secrets engines non-exhaustive: databases, aws, azure, gcp, ...

Database secret example

The database secret engine's db mount path is specified under spec.mount of VaultDynamicSecret custom resource. Please consult Database Secrets Engine - Setup for configuring the database secrets engine. The following results in a request to http://127.0.0.1:8200/v1/db/creds/my-postgresql-role to generate a new credential.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  namespace: vso-example
  name: example
spec:
  vaultAuthRef: example
  mount: db
  path: creds/my-postgresql-role
  destination:
    create: true
    name: dynamic1
AWS secret example

The AWS secrets engine's aws mount path is specified under spec.mount of VaultDynamicSecret custom resource. Please consult AWS Secrets Engine - Setup for configuring AWS secrets engine.

The following results in a request to http://127.0.0.1:8200/v1/aws/creds/my-iam-role to generate a new IAM credential.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  namespace: vso-example
  name: example
spec:
  vaultAuthRef: example
  mount: aws
  path: creds/my-iam-role
  destination:
    create: true
    name: dynamic1

The following results in a request to http://127.0.0.1:8200/v1/aws/sts/my-sts-role to generate a new STS credential.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  namespace: vso-example
  name: example
spec:
  vaultAuthRef: example
  mount: aws
  path: sts/my-sts-role
  destination:
    create: true
    name: dynamic2

Tutorial

Refer to the The Vault Secrets Operator on Kubernetes tutorial to learn the end-to-end workflow using the Vault Secrets Operator.

Edit this page on GitHub