---
layout: docs
page_title: Vault Secrets Operator with HCP Vault Secrets
description: >-
  The Vault Secrets Operator allows pods to consume HCP Vault Secrets natively from Kubernetes Secrets.
---

# Vault Secrets Operator with HCP Vault Secrets

The Vault secrets operator (VSO) syncs your [HCP Vault Secrets app](/hcp/docs/vault-secrets) (HVSA) to
a Kubernetes Secret. Vault syncs each `HCPVaultSecretsApp` custom resource periodically to ensure that
changes to the secret source are properly reflected in the Kubernetes secret.


## Features

- Periodic synchronization of HCP Vault Secrets app to a *destination* Kubernetes Secret.
- Automatic drift detection and remediation when the destination Kubernetes Secret
  is modified or deleted.
- Supports all VSO features, including rollout-restarts on secret rotation or
  during drift remediation.
- Supports authentication to HCP using [HCP service principals](/hcp/docs/hcp/admin/iam/service-principals).
- Supports [static](#static-secrets), [auto-rotating and dynamic secrets](#auto-rotating-and-dynamic-secrets)
  within an HCP Vault Secrets app.


### Supported HCP authentication methods

| Backend                                                              | Description                                            |
|----------------------------------------------------------------------|--------------------------------------------------------|
| [HCP Service Principals](/hcp/docs/hcp/admin/iam/service-principals) | Relies on static credentials for authenticating to HCP |


### HCP Vault Secrets sync example

The following Kubernetes configuration can be used to sync the HCP Vault Secrets app, `vso-example`,
to the Kubernetes Secret, `vso-app-secret`, in the `vso-example-ns` Kubernetes Namespace. It assumes that
you have already setup [service principal Kubernetes secret](/vault/docs/platform/k8s/vso/api-reference#hcpauthserviceprincipal),
and have created the HCP Vault Secrets app.

Use the following Kubernetes configuration to sync your HCP Vault Secrets app, `vso-example`,
to the Kubernetes secret, `vso-app-secret`, in the `vso-example-ns` Kubernetes namespace.
The example configuration assumes you already a HCP Vault Secrets app created and have your
[service principal Kubernetes secret](/vault/docs/platform/k8s/vso/api-reference#hcpauthserviceprincipal)
configured.

Refer to the [Kubernetes VSO installation guide](/vault/docs/platform/k8s/vso/installation)
before applying any of the example configurations below.

```yaml
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: HCPAuth
metadata:
  name: hcp-auth
  namespace: vso-example-ns
spec:
  organizationID: xxxxxxxx-76e9-4e17-b5e9-xxxxxxxx4c33
  projectID: xxxxxxxx-bd16-443f-a266-xxxxxxxxcb52
  servicePrincipal:
    secretRef: vso-app-sp
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: HCPVaultSecretsApp
metadata:
  name: vso-app
  namespace: vso-example-ns
spec:
  appName: vso-app
  hcpAuthRef: hcp-auth
  destination:
    create: true
    name: vso-app-secret
```

### Static Secrets

VSO supports syncing [static secrets](/hcp/docs/vault-secrets/static-secrets/create-static-secret)
from an HCP Vault Secrets app to a Kubernetes Secret. VSO syncs the secrets to
Kubernetes on the [refreshAfter](/vault/docs/platform/k8s/vso/api-reference#hcpvaultsecretsappspec)
interval set in the HCPVaultSecretsApp spec.

### Auto-rotating and Dynamic Secrets

<Tip title="Feature availability">

  VSO v0.9.0

</Tip>

VSO also supports syncing [auto-rotating](/hcp/docs/vault-secrets/auto-rotation)
and [dynamic](/hcp/docs/vault-secrets/dynamic-secrets) secrets from an HCP Vault
Secrets app to a Kubernetes Secret.

VSO syncs auto-rotating secrets along with static secrets on the
[refreshAfter](/vault/docs/platform/k8s/vso/api-reference#hcpvaultsecretsappspec)
interval, and rotation is handled by HCP. VSO syncs dynamic secrets when the
[specified percentage](/vault/docs/platform/k8s/vso/api-reference#hvsdynamicsyncconfig)
of their TTL has elapsed. Each sync of a dynamic secret generates a new set of
credentials.

An auto-rotating or dynamic secret can have multiple key-value pairs, which
are rendered in the destination Kubernetes Secret as both a nested map and
flattened key-value pairs. For example:

```yaml
apiVersion: v1
kind: Secret
data:
  secret_name: {"key_one": "value_one", "key_two": "value_two"}
  secret_name_key_one: "value_one"
  secret_name_key_two: "value_two"
...
```

Transformation [template commands like `get` and `dig`](/vault/docs/platform/k8s/vso/secret-transformation#map-functions)
in the HCPVaultSecretsApp Destination can be used to extract values from the
nested map format:

```yaml
    transformation:
      templates:
        secret_one:
          text: '{{- get (get .Secrets "secret_name") "key_one" -}}'
        secret_two:
          text: '{{- dig "secret_name" "key_two" "<missing>" .Secrets -}}'
```

@include 'vso/blurb-api-reference.mdx'

## Tutorial

Refer to the [HCP Vault Secrets with Vault Secrets Operator for
Kubernetes](/vault/tutorials/hcp-vault-secrets-get-started/kubernetes-vso) tutorial to
learn the end-to-end workflow using the Vault Secrets Operator.