mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-01 19:17:58 +00:00
304 lines
9.7 KiB
Plaintext
304 lines
9.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Vault Secrets Operator
|
|
description: >-
|
|
The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets.
|
|
---
|
|
|
|
# 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](/vault/docs) | 1.11+ |
|
|
| [HCP Vault Dedicated](/hcp/docs/vault) | 1.11+ |
|
|
|
|
## Features
|
|
|
|
Vault Secrets Operator supports the following Vault features:
|
|
|
|
- Sync from multiple instances of Vault.
|
|
- All Vault [secret engines](/vault/docs/secrets) 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](/vault/docs/auth/kubernetes) | Relies on short-lived Kubernetes ServiceAccount tokens for Vault authentication |
|
|
| [JWT](/vault/docs/auth/jwt) | Relies on either static JWT tokens or short-lived Kubernetes ServiceAccount tokens for Vault authentication |
|
|
| [AppRole](/vault/docs/auth/approle) | Relies on static AppRole credentials for Vault authentication |
|
|
| [AWS](/vault/docs/auth/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.
|
|
|
|
```yaml
|
|
---
|
|
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.
|
|
|
|
```yaml
|
|
---
|
|
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: []
|
|
```
|
|
|
|
## 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.<br />
|
|
Supported secrets engines: [kv-v2](/vault/docs/secrets/kv/kv-v2), [kv-v1](/vault/docs/secrets/kv/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](/vault/docs/secrets/kv/kv-v1#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.
|
|
|
|
```yaml
|
|
---
|
|
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](/vault/docs/secrets/kv/kv-v2#setup)
|
|
guide.
|
|
|
|
For example, to send requests to `http://127.0.0.1:8200/v1/kvv2/eng/apikey/google`
|
|
to retrieve secrets:
|
|
|
|
```yaml
|
|
---
|
|
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.<br />
|
|
Supported secrets engines: [pki](/vault/docs/secrets/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](/vault/docs/secrets/pki/setup) 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.
|
|
|
|
```yaml
|
|
---
|
|
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.<br />
|
|
Supported secrets engines *non-exhaustive*: [databases](/vault/docs/secrets/databases), [aws](/vault/docs/secrets/aws),
|
|
[azure](/vault/docs/secrets/azure), [gcp](/vault/docs/secrets/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](/vault/docs/secrets/databases#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:
|
|
|
|
```yaml
|
|
---
|
|
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](/vault/docs/secrets/aws#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:
|
|
|
|
```yaml
|
|
---
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
```
|
|
|
|
@include 'vso/blurb-api-reference.mdx'
|
|
|
|
## Tutorial
|
|
|
|
Refer to the [Vault Secrets Operator on
|
|
Kubernetes](/vault/tutorials/kubernetes/vault-secrets-operator) tutorial to
|
|
learn the end-to-end workflow using the Vault Secrets Operator.
|