---
layout: docs
page_title: Vault Secrets Operator
description: >-
  The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets.
---
@include 'vso/common-links.mdx'

# 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.
- Cross Vault namespace authentication for Vault Enterprise 1.13+.
- [Encrypted Vault client cache storage](/vault/docs/platform/k8s/vso/sources/vault#vault-client-cache) for improved performance and security.
- [Instant updates](/vault/docs/platform/k8s/vso/sources/vault#instant-updates)
  for VaultStaticSecret's with Vault Enterprise 1.16.3+.

### Supported Vault authentication methods

| Backend                                                                            | Description                                                                                                 |
|------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| [Kubernetes](/vault/docs/platform/k8s/vso/api-reference#vaultauthconfigkubernetes) | Relies on short-lived Kubernetes ServiceAccount tokens for Vault authentication                             |
| [JWT](/vault/docs/platform/k8s/vso/api-reference#vaultauthconfigjwt)               | Relies on either static JWT tokens or short-lived Kubernetes ServiceAccount tokens for Vault authentication |
| [AppRole](/vault/docs/platform/k8s/vso/api-reference#vaultauthconfigapprole)       | Relies on static AppRole credentials for Vault authentication                                               |
| [AWS](/vault/docs/platform/k8s/vso/sources/vault/auth/aws)                         | Relies on AWS credentials for Vault authentication                                                          |
| [GCP](/vault/docs/platform/k8s/vso/sources/vault/auth/gcp)                         | Relies on GCP 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: []
```

### VaultAuthGlobal custom resource

<Tip title="Feature availability">

VSO v0.8.0

</Tip>

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][va-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][auth]
docs.

<Tip>

  The VaultAuthGlobal resources shares many of the same fields as the VaultAuth custom resource, but cannot be used
  for authentication directly. It is only used to define shared Vault authentication configuration within a Kubernetes
  cluster.

</Tip>

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.

```yaml
---
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.<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'

## 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](/vault/docs/secrets/transit).

The [Encrypted client cache](/vault/docs/platform/k8s/vso/sources/vault/client-cache) guide will walk you through the steps to enable and configure client cache encryption.

## Instant updates <EnterpriseAlert inline="true" />
<Tip title="Feature availability">

  VSO v0.8.0

</Tip>

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

**Supported secret types:**
- [VaultStaticSecret](#vaultstaticsecret-custom-resource) ([kv-v1](/vault/docs/secrets/kv/kv-v1),
  [kv-v2](/vault/docs/secrets/kv/kv-v2))

<Note title="Requires Vault Enterprise 1.16.3+">

The instant updates option requires [Vault Enterprise](/vault/docs/enterprise)
1.16.3+ due to the use of [Vault Event Notifications][vault-events].

</Note>

The [Instant updates](/vault/docs/platform/k8s/vso/sources/vault/instant-updates) guide
will walk you through the steps to enable instant updates for a VaultStaticSecret.

[vss-spec]: /vault/docs/platform/k8s/vso/api-reference#vaultstaticsecretspec
[vault-events]: /vault/docs/concepts/events

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