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
Platform | Version |
---|---|
Vault Enterprise/Community | 1.11+ |
HCP Vault Dedicated | 1.11+ |
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.
Supported Vault authentication methods
Backend | Description |
---|---|
Kubernetes | Relies on short-lived Kubernetes ServiceAccount tokens for Vault authentication |
JWT | Relies on either static JWT tokens or short-lived Kubernetes ServiceAccount tokens for Vault authentication |
AppRole | Relies on static AppRole credentials for Vault authentication |
AWS | Relies on AWS credentials for Vault authentication |
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/v1beta1kind: VaultConnectionmetadata: namespace: vso-example name: vault-connectionspec: # 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/v1beta1kind: VaultAuthmetadata: namespace: vso-example name: vault-authspec: # 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: []
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/v1beta1kind: VaultStaticSecretmetadata: namespace: vso-example name: vault-static-secret-v1spec: 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/v1beta1kind: VaultStaticSecretmetadata: namespace: vso-example name: vault-static-secret-v2spec: 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/v1beta1kind: VaultPKISecretmetadata: namespace: vso-example name: vault-pkispec: 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/v1beta1kind: VaultDynamicSecretmetadata: namespace: vso-example name: vault-dynamic-secret-dbspec: 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/v1beta1kind: VaultDynamicSecretmetadata: namespace: vso-example name: vault-dynamic-secret-aws-iamspec: 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/v1beta1kind: VaultDynamicSecretmetadata: namespace: vso-example name: vault-dynamic-secret-aws-stsspec: 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/v1beta1kind: VaultDynamicSecretmetadata: namespace: vso-example name: vault-dynamic-secret-aws-iam-rolespec: 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.
Tutorial
Refer to the Vault Secrets Operator on Kubernetes tutorial to learn the end-to-end workflow using the Vault Secrets Operator.