luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

backport of commit 9ffea8aee557da186bfa142af6fb217c2b967699 (#23395) 

Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com>
This commit is contained in:
hc-github-team-secure-vault-core 2023-09-28 16:42:17 -04:00 committed by GitHub
parent f761e5c1ee
commit b81816ce08
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 614 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/content/docs/platform/k8s/index.mdx
View File

@ -65,7 +65,7 @@ There are currently 3 different integrations to help Kubernetes workloads seamle
- More mature solution, with proven production record and advanced features like templating,
wider array of auth methods, etc.
#### Vault secrets operator
#### Vault Secrets Operator
- More native UX for app developers. Workloads can mount Kubernetes secrets without adding any Vault-specific configuration.
- Reduced load on Vault. Secrets are synced per CRD instead of per consuming pod.

133
website/content/docs/platform/k8s/vso/api-reference.mdx
View File

@ -7,7 +7,7 @@ description: >-
<!--
copied from docs/api/api-reference.md in the vault-secrets-operator repo.
commit SHA=06bc1738beb805455cc875f1b41e96ec35ecb514
commit SHA=787fa70aa4ef1b8c118e15991bd3b712eed4479c
-->
# API Reference
@ -20,6 +20,10 @@ description: >-
Package v1beta1 contains API Schema definitions for the secrets v1beta1 API group
### Resource Types
- [HCPAuth](#hcpauth)
- [HCPAuthList](#hcpauthlist)
- [HCPVaultSecretsApp](#hcpvaultsecretsapp)
- [HCPVaultSecretsAppList](#hcpvaultsecretsapplist)
- [VaultAuth](#vaultauth)
- [VaultAuthList](#vaultauthlist)
- [VaultConnection](#vaultconnection)
@ -40,6 +44,7 @@ Package v1beta1 contains API Schema definitions for the secrets v1beta1 API grou
Destination provides the configuration that will be applied to the destination Kubernetes Secret during a Vault Secret -> K8s Secret sync.
_Appears in:_
- [HCPVaultSecretsAppSpec](#hcpvaultsecretsappspec)
- [VaultDynamicSecretSpec](#vaultdynamicsecretspec)
- [VaultPKISecretSpec](#vaultpkisecretspec)
- [VaultStaticSecretSpec](#vaultstaticsecretspec)
@ -53,6 +58,126 @@ _Appears in:_
| `type` _[SecretType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#secrettype-v1-core)_ | Type of Kubernetes Secret. Requires Create to be set to true. Defaults to Opaque. |
#### HCPAuth
HCPAuth is the Schema for the hcpauths API
_Appears in:_
- [HCPAuthList](#hcpauthlist)
| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1`
| `kind` _string_ | `HCPAuth`
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `spec` _[HCPAuthSpec](#hcpauthspec)_ | |
#### HCPAuthList
HCPAuthList contains a list of HCPAuth
| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1`
| `kind` _string_ | `HCPAuthList`
| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `items` _[HCPAuth](#hcpauth) array_ | |
#### HCPAuthServicePrincipal
HCPAuthServicePrincipal provides HCPAuth configuration options needed for authenticating to HCP using a service principal configured in SecretRef.
_Appears in:_
- [HCPAuthSpec](#hcpauthspec)
| Field | Description |
| --- | --- |
| `secretRef` _string_ | SecretRef is the name of a Kubernetes secret in the consumer's (VDS/VSS/PKI/HCP) namespace which provides the HCP ServicePrincipal clientID, and clientSecret. The secret data must have the following structure { "clientID": "clientID", "clientSecret": "clientSecret", } |
#### HCPAuthSpec
HCPAuthSpec defines the desired state of HCPAuth
_Appears in:_
- [HCPAuth](#hcpauth)
| Field | Description |
| --- | --- |
| `organizationID` _string_ | OrganizationID of the HCP organization. |
| `projectID` _string_ | ProjectID of the HCP project. |
| `allowedNamespaces` _string array_ | AllowedNamespaces Kubernetes Namespaces which are allow-listed for use with this AuthMethod. This field allows administrators to customize which Kubernetes namespaces are authorized to use with this AuthMethod. While Vault will still enforce its own rules, this has the added configurability of restricting which HCPAuthMethods can be used by which namespaces. Accepted values: []{"*"} - wildcard, all namespaces. []{"a", "b"} - list of namespaces. unset - disallow all namespaces except the Operator's the HCPAuthMethod's namespace, this is the default behavior. |
| `method` _string_ | Method to use when authenticating to Vault. |
| `servicePrincipal` _[HCPAuthServicePrincipal](#hcpauthserviceprincipal)_ | ServicePrincipal provides the necessary configuration for authenticating to HCP using a service principal. For security reasons, only project-level service principals should ever be used. |
#### HCPVaultSecretsApp
HCPVaultSecretsApp is the Schema for the hcpvaultsecretsapps API
_Appears in:_
- [HCPVaultSecretsAppList](#hcpvaultsecretsapplist)
| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1`
| `kind` _string_ | `HCPVaultSecretsApp`
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `spec` _[HCPVaultSecretsAppSpec](#hcpvaultsecretsappspec)_ | |
#### HCPVaultSecretsAppList
HCPVaultSecretsAppList contains a list of HCPVaultSecretsApp
| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1`
| `kind` _string_ | `HCPVaultSecretsAppList`
| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `items` _[HCPVaultSecretsApp](#hcpvaultsecretsapp) array_ | |
#### HCPVaultSecretsAppSpec
HCPVaultSecretsAppSpec defines the desired state of HCPVaultSecretsApp
_Appears in:_
- [HCPVaultSecretsApp](#hcpvaultsecretsapp)
| Field | Description |
| --- | --- |
| `appName` _string_ | AppName of the Vault Secrets Application that is to be synced. |
| `hcpAuthRef` _string_ | HCPAuthRef to the HCPAuth resource, can be prefixed with a namespace, eg: `namespaceA/vaultAuthRefB`. If no namespace prefix is provided it will default to the namespace of the HCPAuth CR. If no value is specified for HCPAuthRef the Operator will default to the `default` HCPAuth, configured in its own Kubernetes namespace. HCPAuthRef string `json:"hcpAuthRef,omitempty"` |
| `refreshAfter` _string_ | RefreshAfter a period of time, in duration notation e.g. 30s, 1m, 24h |
| `rolloutRestartTargets` _[RolloutRestartTarget](#rolloutrestarttarget) array_ | RolloutRestartTargets should be configured whenever the application(s) consuming the HCP Vault Secrets App does not support dynamically reloading a rotated secret. In that case one, or more RolloutRestartTarget(s) can be configured here. The Operator will trigger a "rollout-restart" for each target whenever the Vault secret changes between reconciliation events. See RolloutRestartTarget for more details. |
| `destination` _[Destination](#destination)_ | Destination provides configuration necessary for syncing the HCP Vault Application secrets to Kubernetes. |
#### RolloutRestartTarget
@ -61,6 +186,7 @@ RolloutRestartTarget provides the configuration required to perform a rollout-re
Supported resources: Deployment, DaemonSet, StatefulSet
_Appears in:_
- [HCPVaultSecretsAppSpec](#hcpvaultsecretsappspec)
- [VaultDynamicSecretSpec](#vaultdynamicsecretspec)
- [VaultPKISecretSpec](#vaultpkisecretspec)
- [VaultStaticSecretSpec](#vaultstaticsecretspec)
@ -212,7 +338,7 @@ _Appears in:_
| `appRole` _[VaultAuthConfigAppRole](#vaultauthconfigapprole)_ | AppRole specific auth configuration, requires that the Method be set to `appRole`. |
| `jwt` _[VaultAuthConfigJWT](#vaultauthconfigjwt)_ | JWT specific auth configuration, requires that the Method be set to `jwt`. |
| `aws` _[VaultAuthConfigAWS](#vaultauthconfigaws)_ | AWS specific auth configuration, requires that Method be set to `aws`. |
| `storageEncryption` _[StorageEncryption](#storageencryption)_ | StorageEncryption provides the necessary configuration to encrypt the client storage cache. This should only be configured when client cache persistence with encryption is enabled. This is done by passing setting the manager's commandline argument --client-cache-persistence-model=direct-encrypted. Typically there should only ever be one VaultAuth configured with StorageEncryption in the Cluster, and it should have the label: cacheStorageEncryption=true |
| `storageEncryption` _[StorageEncryption](#storageencryption)_ | StorageEncryption provides the necessary configuration to encrypt the client storage cache. This should only be configured when client cache persistence with encryption is enabled. This is done by passing setting the manager's commandline argument --client-cache-persistence-model=direct-encrypted. Typically, there should only ever be one VaultAuth configured with StorageEncryption in the Cluster, and it should have the label: cacheStorageEncryption=true |
@ -427,6 +553,7 @@ _Appears in:_
| --- | --- |
| `lastVaultRotation` _integer_ | LastVaultRotation represents the last time Vault rotated the password |
| `rotationPeriod` _integer_ | RotationPeriod is number in seconds between each rotation, effectively a "time to live". This value is compared to the LastVaultRotation to determine if a password needs to be rotated |
| `rotationSchedule` _string_ | RotationSchedule is a "cron style" string representing the allowed schedule for each rotation. e.g. "1 0 * * *" would rotate at one minute past midnight (00:01) every day. |
| `ttl` _integer_ | TTL is the seconds remaining before the next rotation. |
@ -480,7 +607,7 @@ _Appears in:_
| `path` _string_ | Path of the secret in Vault, corresponds to the `path` parameter for, [kv-v1](/vault/api-docs/secret/kv/kv-v1#read-secret) [kv-v2](/vault/api-docs/secret/kv/kv-v2#read-secret-version) |
| `version` _integer_ | Version of the secret to fetch. Only valid for type kv-v2. Corresponds to version query parameter: [version](/vault/api-docs/secret/kv/kv-v2#version) |
| `type` _string_ | Type of the Vault static secret |
| `refreshAfter` _string_ | RefreshAfter a period of time, in duration notation |
| `refreshAfter` _string_ | RefreshAfter a period of time, in duration notation e.g. 30s, 1m, 24h |
| `hmacSecretData` _boolean_ | HMACSecretData determines whether the Operator computes the HMAC of the Secret's data. The MAC value will be stored in the resource's Status.SecretMac field, and will be used for drift detection and during incoming Vault secret comparison. Enabling this feature is recommended to ensure that Secret's data stays consistent with Vault. |
| `rolloutRestartTargets` _[RolloutRestartTarget](#rolloutrestarttarget) array_ | RolloutRestartTargets should be configured whenever the application(s) consuming the Vault secret does not support dynamically reloading a rotated secret. In that case one, or more RolloutRestartTarget(s) can be configured here. The Operator will trigger a "rollout-restart" for each target whenever the Vault secret changes between reconciliation events. All configured targets wil be ignored if HMACSecretData is set to false. See RolloutRestartTarget for more details. |
| `destination` _[Destination](#destination)_ | Destination provides configuration necessary for syncing the Vault secret to Kubernetes. |

2
website/content/docs/platform/k8s/vso/examples.mdx
View File

@ -5,7 +5,7 @@ description: >-
The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets.
---
# Vault secrets operator examples
# Vault Secrets Operator examples
The Operator project provides the following examples:
- Sample use-cases are documented [here](https://github.com/hashicorp/vault-secrets-operator#samples)

48
website/content/docs/platform/k8s/vso/helm.mdx
View File

@ -5,7 +5,7 @@ description: >-
Configuration for the Vault Secrets Operator Helm chart.
---
# Vault secrets operator helm chart
# Vault Secrets Operator helm chart
The chart is customizable using
[Helm configuration values](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing).
@ -34,6 +34,15 @@ Use these links to navigate to a particular top-level stanza.
- `replicas` ((#v-controller-replicas)) (`integer: 1`) - Set the number of replicas for the operator.
- `hostAliases` ((#v-controller-hostaliases)) (`array<map>`) - Host Aliases settings for vault-secrets-operator pod.
The value is an array of PodSpec HostAlias maps.
ref: https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/
Example:
hostAliases:
- ip: 192.168.1.100
hostnames:
- vault.example.com
- `nodeSelector` ((#v-controller-nodeselector)) (`map`) - nodeSelector labels for vault-secrets-operator pod assignment.
ref: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector
Example:
@ -50,6 +59,21 @@ Use these links to navigate to a particular top-level stanza.
value: "value1"
effect: "NoSchedule"
- `affinity` ((#v-controller-affinity)) - Affinity settings for vault-secrets-operator pod.
The value is a map of PodSpec Affinity maps.
ref: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
Example:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: topology.kubernetes.io/zone
operator: In
values:
- antarctica-east1
- antarctica-west1
- `kubeRbacProxy` ((#v-controller-kuberbacproxy)) - Settings related to the kubeRbacProxy container. This container is an HTTP proxy for the
controller manager which performs RBAC authorization against the Kubernetes API using SubjectAccessReviews.
@ -95,7 +119,7 @@ Use these links to navigate to a particular top-level stanza.
- `repository` ((#v-controller-manager-image-repository)) (`string: hashicorp/vault-secrets-operator`)
- `tag` ((#v-controller-manager-image-tag)) (`string: 0.2.0`)
- `tag` ((#v-controller-manager-image-tag)) (`string: 0.3.0-rc.1`)
- `clientCache` ((#v-controller-manager-clientcache)) - Configures the client cache which is used by the controller to cache (and potentially persist) vault tokens that
are the result of using the VaultAuthMethod. This enables re-use of Vault Tokens
@ -230,6 +254,11 @@ Use these links to navigate to a particular top-level stanza.
- name: HTTP_PROXY
value: http://proxy.example.com
- `extraArgs` ((#v-controller-manager-extraargs)) (`array: []`) - Defines additional commandline arguments to be passed to the
vault-secrets-operator manager container.
extraArgs:
- -zap-log-level=5
- `resources` ((#v-controller-manager-resources)) (`map`) - Configures the default resources for the vault-secrets-operator container.
For more information on configuring resources, see the K8s documentation:
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
@ -246,6 +275,16 @@ Use these links to navigate to a particular top-level stanza.
- `memory` ((#v-controller-manager-resources-requests-memory)) (`string: 64Mi`)
- `podSecurityContext` ((#v-controller-podsecuritycontext)) - Configures the Pod security context
https://kubernetes.io/docs/tasks/configure-pod-container/security-context
- `runAsNonRoot` ((#v-controller-podsecuritycontext-runasnonroot)) (`boolean: true`)
- `securityContext` ((#v-controller-securitycontext)) - Configures the container security context
https://kubernetes.io/docs/tasks/configure-pod-container/security-context
- `allowPrivilegeEscalation` ((#v-controller-securitycontext-allowprivilegeescalation)) (`boolean: false`)
- `controllerConfigMapYaml` ((#v-controller-controllerconfigmapyaml)) (`map`) - Sets the configuration settings used by the controller. Any custom changes will be reflected in the
data field of the configmap.
For more information on configuring resources, see the K8s documentation:
@ -271,6 +310,11 @@ Use these links to navigate to a particular top-level stanza.
- `kubernetesClusterDomain` ((#v-controller-kubernetesclusterdomain)) (`string: cluster.local`) - Configures the environment variable KUBERNETES_CLUSTER_DOMAIN used by KubeDNS.
- `terminationGracePeriodSeconds` ((#v-controller-terminationgraceperiodseconds)) (`integer: 120`) - Duration in seconds the pod needs to terminate gracefully.
See: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/
- `preDeleteHookTimeoutSeconds` ((#v-controller-predeletehooktimeoutseconds)) (`integer: 120`) - Timeout in seconds for the pre-delete hook
### metricsService ((#h-metricsservice))
- `metricsService` ((#v-metricsservice)) (`map`) - Configure the metrics service ports used by the metrics service.

259
website/content/docs/platform/k8s/vso/index.mdx
View File

@ -2,18 +2,18 @@
layout: docs
page_title: Vault Secrets Operator
description: >-
The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets.
The Vault Secrets Operator allows Pods to consume HashiCorp secrets natively from Kubernetes Secrets.
---
# Vault secrets operator
# Vault Secrets Operator
The Vault Secrets Operator (VSO) allows Pods to consume Vault secrets natively from Kubernetes Secrets.
The Vault Secrets Operator (VSO) allows Pods to consume Vault secrets and HCP Vault Secrets Apps natively from Kubernetes Secrets.
## Overview
The Vault Secrets Operator operates by watching for changes to its supported set of Custom Resource Definitions (CRD).
Each CRD provides the specification required to allow the Operator to synchronize a Vault Secrets to a Kubernetes Secret.
The Operator writes the *source* Vault secret data directly to the *destination* Kubernetes Secret, ensuring that any
Each CRD provides the specification required to allow the operator to synchronize from one of the supported sources for secrets to a Kubernetes Secret.
The operator writes the *source* secret data directly to the *destination* Kubernetes Secret, ensuring that any
changes made to the *source* are replicated to the *destination* over its lifetime. In this way, an application only needs
to have access to the *destination* secret in order to make use of the secret data contained within.
@ -21,27 +21,21 @@ to have access to the *destination* secret in order to make use of the secret da
The following features are supported by the Vault Secrets Operator:
- All Vault [secret engines](/vault/docs/secrets) supported.
- TLS/mTLS communications with Vault.
- Authentication to Vault with any of the following Auth Methods:
- [Kubernetes](/vault/docs/auth/kubernetes)
- [JWT](/vault/docs/auth/jwt)
- [AppRole](/vault/docs/auth/approle)
- [AWS](/vault/docs/auth/aws)
- Support for additional Auth Methods coming soon.
- Secret rotation for `Deployment`, `ReplicaSet`, `StatefulSet` Kubernetes resource types.
- Prometheus instrumentation for [monitoring](/vault/docs/platform/k8s/vso/telemetry) the Operator
- Support for syncing from multiple secret sources.
- Automatic secret drift and remediation.
- Automatic secret rotation for `Deployment`, `ReplicaSet`, `StatefulSet` Kubernetes resource types.
- Prometheus specific instrumentation for [monitoring](/vault/docs/platform/k8s/vso/telemetry) the Operator.
- Support for installing using: `Helm` or `Kustomize`<br />
*see the [installation](/vault/docs/platform/k8s/vso/installation) docs for more details*
## Supported Vault versions
## Supported secret sources
- Vault 1.11+
- [HCP Vault](https://www.hashicorp.com/cloud)
The Vault Secrets Operator supports syncing from multiple secret sources.
Refer to the [secret sources overview](/vault/docs/platform/k8s/vso/sources) for more details.
@include 'kubernetes-supported-versions.mdx'
## Supported Cloud providers
## Supported Kubernetes distributions
The Vault Secrets Operator has been tested successfully in the following hosted Kubernetes environments:
- Amazon Elastic Kubernetes Service (EKS)
@ -50,231 +44,10 @@ The Vault Secrets Operator has been tested successfully in the following hosted
- Red Hat OpenShift
Basic integration tests are available in the project repository.
Please report any incompatibilities via a [Github Issue](https://github.com/hashicorp/vault-secrets-operator/issues).
## Vault access and custom resource definitions
The Vault connection and authentication configuration is provided by the `VaultConnection` and `VaultAuth` CRDs. These can be considered as
foundational Custom Resources that all secret replication type resources will reference.
### VaultConnection custom resource
Provides the configuration necessary for the Operator to connect to a single Vault server instance.
```yaml
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultConnection
metadata:
namespace: vso-example
name: example
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: example
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: example
# 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: example
spec:
vaultAuthRef: example
mount: kvv1
type: kv-v1
path: eng/apikey/google
refreshAfter: 60s
destination:
create: true
name: static-secret1
```
##### KV version 2 secret example
The KV secrets engine's `kvv2` mount path is specified under `spec.mount` of `VaultStaticSecret` custom resource. Please consult [KV Secrets Engine - Version 2 - Setup](/vault/docs/secrets/kv/kv-v2#setup) for configuring KV secrets engine version 2. The following results in a request to `http://127.0.0.1:8200/v1/kvv2/data/eng/apikey/google?version=2` to retrieve the secret.
```yaml
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
namespace: vso-example
name: example
spec:
vaultAuthRef: example
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: example
spec:
vaultAuthRef: example
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
The database secret engine's `db` mount path is specified under `spec.mount` of `VaultDynamicSecret` custom resource. Please consult [Database Secrets Engine - Setup](/vault/docs/secrets/databases#setup) for configuring the database secrets engine. The following results in a request 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: example
spec:
vaultAuthRef: example
mount: db
path: creds/my-postgresql-role
destination:
create: true
name: dynamic1
```
##### AWS secret example
The AWS secrets engine's `aws` mount path is specified under `spec.mount` of `VaultDynamicSecret` custom resource. Please consult [AWS Secrets Engine - Setup](/vault/docs/secrets/aws#setup) for configuring AWS secrets engine.
The following results in a request 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: example
spec:
vaultAuthRef: example
mount: aws
path: creds/my-iam-role
destination:
create: true
name: dynamic1
```
The following results in a request 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: example
spec:
vaultAuthRef: example
mount: aws
path: sts/my-sts-role
destination:
create: true
name: dynamic2
```
Please report any issues [here](https://github.com/hashicorp/vault-secrets-operator/issues).
## Tutorial
Refer to the [The Vault Secrets Operator on
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.
learn the end-to-end workflow using the Vault Secrets Operator.

12
website/content/docs/platform/k8s/vso/installation.mdx
View File

@ -5,15 +5,17 @@ description: >-
The Vault Secrets Operator can be installed using Helm.
---
# Installing the Vault secrets operator
# Installing the Vault Secrets Operator
## Prerequisites
- Kubernetes 1.22+
- Vault 1.11+ or [HCP Vault](https://www.hashicorp.com/cloud)
- A Kubernetes cluster running 1.23+
- Helm 3.7+
## Installation using helm
[Install Helm](https://helm.sh/docs/intro/install) before beginning.
The [Vault Secrets Operator Helm chart](/vault/docs/platform/k8s/vso/helm) is the recommended way of
installing and configuring the Vault Secrets Operator.
@ -26,13 +28,13 @@ $ helm repo add hashicorp https://helm.releases.hashicorp.com
$ helm search repo hashicorp/vault-secrets-operator
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault-secrets-operator 0.1.0 0.1.0 Official HashiCorp Vault Secrets Operator Chart
hashicorp/vault-secrets-operator 0.3.0 0.3.0 Official HashiCorp Vault Secrets Operator Chart
```
Then install the Operator:
```shell-session
$ helm install --create-namespace --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator --version 0.1.0
$ helm install --create-namespace --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator --version 0.3.0
```

76
website/content/docs/platform/k8s/vso/sources/hvs.mdx Normal file
View File

@ -0,0 +1,76 @@
---
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.
---
# HCP Vault Secrets source
## Overview
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).
### 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
```
@include 'vso/blurb-api-reference.mdx'

15
website/content/docs/platform/k8s/vso/sources/index.mdx Normal file
View File

@ -0,0 +1,15 @@
---
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)](/vault/docs/platform/k8s/vso) supports syncing secrets from multiple sources.
## Secret sources
- [Vault](/vault/docs/platform/k8s/vso/sources/vault)
- [HCP Vault Secrets](/vault/docs/platform/k8s/vso/sources/hvs)

303
website/content/docs/platform/k8s/vso/sources/vault.mdx Normal file
View File

@ -0,0 +1,303 @@
---
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.

2
website/content/partials/vso/blurb-api-reference.mdx Normal file
View File

@ -0,0 +1,2 @@
For more details on any of the custom resources mentioned here, please see the
[api-reference](/vault/docs/platform/k8s/vso/api-reference).

17
website/data/docs-nav-data.json
View File

@ -1864,6 +1864,23 @@
"title": "Installation",
"path": "platform/k8s/vso/installation"
},
{
"title": "Secret Sources",
"routes": [
{
"title": "Overview",
"path": "platform/k8s/vso/sources"
},
{
"title": "Vault",
"path": "platform/k8s/vso/sources/vault"
},
{
"title": "HCP Vault Secrets",
"path": "platform/k8s/vso/sources/hvs"
}
]
},
{
"title": "Examples",
"path": "platform/k8s/vso/examples"