Vault Secrets Operator

The Vault Secrets Operator (VSO) supports Vault as a secret source, which lets you seamlessly integrate VSO with a Vault instance running on any platform.

Supported Vault platform and version

Features

Vault Secrets Operator supports the following Vault features:

• Sync from multiple instances of Vault.
• All Vault secret engines supported.
• TLS/mTLS communications with Vault.
• Support for all VSO features, including performing a rollout-restart upon secret rotation or during drift remediation.
• Cross Vault namespace authentication for Vault Enterprise 1.13+.
• Encrypted Vault client cache storage for improved performance and security.
• Instant updates for VaultStaticSecret's with Vault Enterprise 1.16.3+.

Supported Vault authentication methods

Vault access and custom resource definitions

VaultConnection and VaultAuth CRDs provide Vault connection and authentication configuration information for the operator. Consider VaultConnection and VaultAuth as foundational resources used by all secret replication type resources.

VaultConnection custom resource

Provides the required configuration details for connecting to a single Vault server instance.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultConnection
metadata:
  namespace: vso-example
  name: vault-connection
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: vault-auth
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: vault-connection
  # 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: []

VaultAuthGlobal custom resource

Namespaced resource that provides shared Vault authentication configuration that can be inherited by multiple VaultAuth custom resources. It supports multiple authentication methods and allows you to define a default authentication method that can be overridden by individual VaultAuth custom resources. See vaultAuthGlobalRef in the VaultAuth spec for more details. The VaultAuthGlobal custom resource is optional and can be used to simplify the configuration of multiple VaultAuth custom resources by reducing config duplication. Like other namespaced VSO custom resources, there can be many VaultAuthGlobal resources configured in a single Kubernetes cluster.

For more details on how to integrate VaultAuthGlobals into your workflow, see the detailed Authentication docs.

The example below demonstrates how to define a VaultAuthGlobal custom resource with a default authentication method of kubernetes, along with a VaultAuth custom resource that inherits its global configuration.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuthGlobal
metadata:
  namespace: vso-example
  name: vault-auth-global
spec:
  defaultAuthMethod: kubernetes
  kubernetes:
    audiences:
    - vault
    mount: kubernetes
    namespace: example-ns
    role: auth-role
    serviceAccount: default
    tokenExpirationSeconds: 600
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
  namespace: vso-example
  name: vault-auth
spec:
  vaultAuthGlobalRef:
    name: vault-auth-global
  kubernetes:
    role: local-role

Explanation

• The VaultAuthGlobal custom resource defines a default authentication method of kubernetes with the defaultAuthMethod field.
• The VaultAuth custom resource inherits the global configuration by referencing the VaultAuthGlobal custom resource with the vaultAuthGlobalRef field.
• The kubernetes.role field in the VaultAuth custom resource spec overrides the value of the corresponding field in the VaultAuthGlobal custom resource. All other fields are inherited from the VaultAuthGlobal custom resource spec.kubernetes field, e.g., audiences, mount, serviceAccount, namespace, etc.

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: vault-static-secret-v1
spec:
  vaultAuthRef: vault-auth
  mount: kvv1
  type: kv-v1
  path: eng/apikey/google
  refreshAfter: 60s
  destination:
    create: true
    name: static-secret1

KV version 2 secret example

Set the KV secrets engine (kvv2) mount path with the spec.mount parameter of your VaultStaticSecret custom resource. For more advanced KV secrets engine version 2 configuration options, consult the KV Secrets Engine - Version 2 - Setup guide.

For example, to send requests to http://127.0.0.1:8200/v1/kvv2/eng/apikey/google to retrieve secrets:

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  namespace: vso-example
  name: vault-static-secret-v2
spec:
  vaultAuthRef: vault-auth
  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: vault-pki
spec:
  vaultAuthRef: vault-auth
  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

Set the database secret engine mount path (db) with the spec.mount of your VaultDynamicSecret custom resource. For more advanced database secrets engine configuration options, consult the Database Secrets Engine - Setup guide.

For example, to send requests 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: vault-dynamic-secret-db
spec:
  vaultAuthRef: vault-auth
  mount: db
  path: creds/my-postgresql-role
  destination:
    create: true
    name: dynamic-db

AWS secret example

Set the AWS secrets engine mount path (aws) with the spec.mount parameter of your VaultDynamicSecret custom resource. For more advanced AWS secrets engine configuration options, consult the AWS Secrets Engine - Setup guide.

For example, to send requests 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: vault-dynamic-secret-aws-iam
spec:
  vaultAuthRef: vault-auth
  mount: aws
  path: creds/my-iam-role
  destination:
    create: true
    name: dynamic-aws-iam

To send requests 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: vault-dynamic-secret-aws-sts
spec:
  vaultAuthRef: vault-auth
  mount: aws
  path: sts/my-sts-role
  destination:
    create: true
    name: dynamic-aws-sts

HCP Vault Secrets Example

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

For more details on any of the custom resources mentioned here, please see the api-reference.

Vault client cache

The Vault Secrets Operator can optionally cache Vault client information such as Vault tokens and leases in Kubernetes Secrets within its own namespace. The client cache enables seamless upgrades because Vault tokens and dynamic secret leases can continue to be tracked and renewed through leadership changes. Client cache persistence and encryption is not enabled by default because it requires extra configuration and Vault Server setup. VSO supports encrypting the client cache using Vault Server's transit secrets engine.

The Encrypted client cache guide will walk you through the steps to enable and configure client cache encryption.

Instant updates EnterpriseEnterprise

The Vault Secrets Operator can instantly update Kubernetes Secrets when changes are made in Vault, by subscribing to Vault Events for change notification. Setting a refresh interval (e.g. refreshAfter) is still recommended since event message delivery is not guaranteed.

Supported secret types:

• VaultStaticSecret (kv-v1, kv-v2)

The Instant updates guide will walk you through the steps to enable instant updates for a VaultStaticSecret.

Tutorial

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