---
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.