scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-01 19:17:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docs for VSO v0.5.0 (#25394)

Browse Source 
---------

Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>
This commit is contained in:
Ben Ash
2024-02-15 16:03:41 -05:00
committed by GitHub
parent 83986f342b
commit f939c86156
7 changed files with 435 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
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=52673cce7858d2c074ca6375f90561fd9f011646
commit SHA=513441e0a912dbae2ddd7dc6bcee6a562f8d52e1
-->
# API Reference
@@ -24,6 +24,8 @@ Package v1beta1 contains API Schema definitions for the secrets v1beta1 API grou
- [HCPAuthList](#hcpauthlist)
- [HCPVaultSecretsApp](#hcpvaultsecretsapp)
- [HCPVaultSecretsAppList](#hcpvaultsecretsapplist)
- [SecretTransformation](#secrettransformation)
- [SecretTransformationList](#secrettransformationlist)
- [VaultAuth](#vaultauth)
- [VaultAuthList](#vaultauthlist)
- [VaultConnection](#vaultconnection)
@@ -53,9 +55,11 @@ _Appears in:_
| --- | --- |
| `name` _string_ | Name of the Secret |
| `create` _boolean_ | Create the destination Secret. If the Secret already exists this should be set to false. |
| `overwrite` _boolean_ | Overwrite the destination Secret if it exists and Create is true. This is useful when migrating to VSO from a previous secret deployment strategy. |
| `labels` _object (keys:string, values:string)_ | Labels to apply to the Secret. Requires Create to be set to true. |
| `annotations` _object (keys:string, values:string)_ | Annotations to apply to the Secret. Requires Create to be set to true. |
| `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. |
| `transformation` _[Transformation](#transformation)_ | Transformation provides configuration for transforming the secret data before it is stored in the Destination. |
#### HCPAuth
@@ -197,11 +201,78 @@ _Appears in:_
| `name` _string_ | |
#### SecretTransformation
SecretTransformation is the Schema for the secrettransformations API
_Appears in:_
- [SecretTransformationList](#secrettransformationlist)
| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1`
| `kind` _string_ | `SecretTransformation`
| `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` _[SecretTransformationSpec](#secrettransformationspec)_ | |
#### SecretTransformationList
SecretTransformationList contains a list of SecretTransformation
| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1`
| `kind` _string_ | `SecretTransformationList`
| `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` _[SecretTransformation](#secrettransformation) array_ | |
#### SecretTransformationSpec
SecretTransformationSpec defines the desired state of SecretTransformation
_Appears in:_
- [SecretTransformation](#secrettransformation)
| Field | Description |
| --- | --- |
| `templates` _object (keys:string, values:[Template](#template))_ | Templates maps a template name to its Template. Templates are always included in the rendered K8s Secret with the specified key. |
| `sourceTemplates` _[SourceTemplate](#sourcetemplate) array_ | SourceTemplates are never included in the rendered K8s Secret, they can be used to provide common template definitions, etc. |
| `includes` _string array_ | Includes contains regex patterns used to filter top-level source secret data fields for inclusion in the final K8s Secret data. These pattern filters are never applied to templated fields as defined in Templates. They are always applied last. |
| `excludes` _string array_ | Excludes contains regex patterns used to filter top-level source secret data fields for exclusion from the final K8s Secret data. These pattern filters are never applied to templated fields as defined in Templates. They are always applied before any inclusion patterns. To exclude all source secret data fields, you can configure the single pattern ".*". |
#### SourceTemplate
SourceTemplate provides source templating configuration.
_Appears in:_
- [SecretTransformationSpec](#secrettransformationspec)
| Field | Description |
| --- | --- |
| `name` _string_ | |
| `text` _string_ | Text contains the Go text template format. The template references attributes from the data structure of the source secret. Refer to https://pkg.go.dev/text/template for more information. |
#### StorageEncryption
StorageEncryption provides the necessary configuration need to encrypt the storage cache entries using Vault's Transit engine. It only supports Kubernetes Auth for now.
StorageEncryption provides the necessary configuration need to encrypt the storage cache entries using Vault's Transit engine.
_Appears in:_
- [VaultAuthSpec](#vaultauthspec)
@@ -212,6 +283,73 @@ _Appears in:_
| `keyName` _string_ | KeyName to use for encrypt/decrypt operations via Vault Transit. |
#### Template
Template provides templating configuration.
_Appears in:_
- [SecretTransformationSpec](#secrettransformationspec)
- [Transformation](#transformation)
| Field | Description |
| --- | --- |
| `name` _string_ | Name of the Template |
| `text` _string_ | Text contains the Go text template format. The template references attributes from the data structure of the source secret. Refer to https://pkg.go.dev/text/template for more information. |
#### TemplateRef
TemplateRef points to templating text that is stored in a SecretTransformation custom resource.
_Appears in:_
- [TransformationRef](#transformationref)
| Field | Description |
| --- | --- |
| `name` _string_ | Name of the Template in SecretTransformationSpec.Templates. the rendered secret data. |
| `keyOverride` _string_ | KeyOverride to the rendered template in the Destination secret. If Key is empty, then the Key from reference spec will be used. Set this to override the Key set from the reference spec. |
#### Transformation
_Appears in:_
- [Destination](#destination)
| Field | Description |
| --- | --- |
| `templates` _object (keys:string, values:[Template](#template))_ | Templates maps a template name to its Template. Templates are always included in the rendered K8s Secret, and take precedence over templates defined in a SecretTransformation. |
| `transformationRefs` _[TransformationRef](#transformationref) array_ | TransformationRefs contain references to template configuration from SecretTransformation. |
| `includes` _string array_ | Includes contains regex patterns used to filter top-level source secret data fields for inclusion in the final K8s Secret data. These pattern filters are never applied to templated fields as defined in Templates. They are always applied last. |
| `excludes` _string array_ | Excludes contains regex patterns used to filter top-level source secret data fields for exclusion from the final K8s Secret data. These pattern filters are never applied to templated fields as defined in Templates. They are always applied before any inclusion patterns. To exclude all source secret data fields, you can configure the single pattern ".*". |
| `excludeRaw` _boolean_ | ExcludeRaw data from the destination Secret. Exclusion policy can be set globally by including 'exclude-raw` in the '--global-transformation-options' command line flag. If set, the command line flag always takes precedence over this configuration. |
#### TransformationRef
TransformationRef contains the configuration for accessing templates from an SecretTransformation resource. TransformationRefs can be shared across all syncable secret custom resources.
_Appears in:_
- [Transformation](#transformation)
| Field | Description |
| --- | --- |
| `namespace` _string_ | Namespace of the SecretTransformation resource. |
| `name` _string_ | Name of the SecretTransformation resource. |
| `templateRefs` _[TemplateRef](#templateref) array_ | TemplateRefs map to a Template found in this TransformationRef. If empty, then all templates from the SecretTransformation will be rendered to the K8s Secret. |
| `ignoreIncludes` _boolean_ | IgnoreIncludes controls whether to use the SecretTransformation's Includes data key filters. |
| `ignoreExcludes` _boolean_ | IgnoreExcludes controls whether to use the SecretTransformation's Excludes data key filters. |
#### VaultAuth
@@ -524,7 +662,7 @@ _Appears in:_
| `role` _string_ | Role in Vault to use when issuing TLS certificates. |
| `revoke` _boolean_ | Revoke the certificate when the resource is deleted. |
| `clear` _boolean_ | Clear the Kubernetes secret when the resource is deleted. |
| `expiryOffset` _string_ | ExpiryOffset to use for computing when the certificate should be renewed. The rotation time will be difference between the expiration and the offset. Should be in duration notation e.g. 30s, 120s, etc. Set to empty string "" to prevent certificate rotation. |
| `expiryOffset` _string_ | ExpiryOffset to use for computing when the certificate should be renewed. The rotation time will be difference between the expiration and the offset. Should be in duration notation e.g. 30s, 120s, etc. |
| `issuerRef` _string_ | IssuerRef reference to an existing PKI issuer, either by Vault-generated identifier, the literal string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. |
| `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. See RolloutRestartTarget for more details. |
| `destination` _[Destination](#destination)_ | Destination provides configuration necessary for syncing the Vault secret to Kubernetes. If the type is set to "kubernetes.io/tls", "tls.key" will be set to the "private_key" response from Vault, and "tls.crt" will be set to "certificate" + "ca_chain" from the Vault response ("issuing_ca" is used when "ca_chain" is empty). The "remove_roots_from_chain=true" option is used with Vault to exclude the root CA from the Vault response. |
@@ -533,6 +671,7 @@ _Appears in:_
| `ipSans` _string array_ | IPSans to include in the request. |
| `uriSans` _string array_ | The requested URI SANs. |
| `otherSans` _string array_ | Requested other SANs, in an array with the format oid;type:value for each entry. |
| `userIDs` _string array_ | User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the signed certificate. |
| `ttl` _string_ | TTL for the certificate; sets the expiration date. If not specified the Vault role's default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount's max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA. Should be in duration notation e.g. 120s, 2h, etc. |
| `format` _string_ | Format for the certificate. Choices: "pem", "der", "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Default: pem |
| `privateKeyFormat` _string_ | PrivateKeyFormat, generally the default will be controlled by the Format parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Default: der |
@@ -630,7 +769,3 @@ _Appears in:_
| `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. |

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

@@ -11,7 +11,7 @@ The chart is customizable using
[Helm configuration values](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing).
<!-- DO NOT EDIT. The docs below are generated automatically. To change, edit
the vault-secrets-operator repo's values.yaml: file commit=dbdfa37e122bd91a4db0bb016970b717aca544f5 -->
the vault-secrets-operator repo's values.yaml: file commit=12d914f6ad83b28d56bc629cde6cbfd5ce1475f0 -->
<!-- codegen: start -->
## Top-Level Stanzas
@@ -79,6 +79,8 @@ Use these links to navigate to a particular top-level stanza.
- `image` ((#v-controller-kuberbacproxy-image)) - Image sets the repo and tag of the kube-rbac-proxy image to use for the controller.
- `pullPolicy` ((#v-controller-kuberbacproxy-image-pullpolicy)) (`string: IfNotPresent`)
- `repository` ((#v-controller-kuberbacproxy-image-repository)) (`string: gcr.io/kubebuilder/kube-rbac-proxy`)
- `tag` ((#v-controller-kuberbacproxy-image-tag)) (`string: v0.15.0`)
@@ -117,9 +119,16 @@ Use these links to navigate to a particular top-level stanza.
- `image` ((#v-controller-manager-image)) - Image sets the repo and tag of the vault-secrets-operator image to use for the controller.
- `pullPolicy` ((#v-controller-manager-image-pullpolicy)) (`string: IfNotPresent`)
- `repository` ((#v-controller-manager-image-repository)) (`string: hashicorp/vault-secrets-operator`)
- `tag` ((#v-controller-manager-image-tag)) (`string: 0.4.3`)
- `tag` ((#v-controller-manager-image-tag)) (`string: 0.5.0`)
- `globalTransformationOptions` ((#v-controller-manager-globaltransformationoptions)) (`array<string>: ""`) - Global secret transformation options.
- `excludeRaw` ((#v-controller-manager-globaltransformationoptions-excluderaw)) (`boolean: false`) - excludeRaw directs the operator to prevent _raw secret data being stored
in the destination K8s Secret.
- `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
@@ -127,6 +136,7 @@ Use these links to navigate to a particular top-level stanza.
Persistence is only useful in the context of Dynamic Secrets, so "none" is an okay default.
- `persistenceModel` ((#v-controller-manager-clientcache-persistencemodel)) (`string: ""`) - Defines the `-client-cache-persistence-model` which caches+persists vault tokens.
May also be set via the `VSO_CLIENT_CACHE_PERSISTENCE_MODEL` environment variable.
Valid values are:
"none" - in-memory client cache is used, no tokens are persisted.
"direct-unencrypted" - in-memory client cache is persisted, unencrypted. This is NOT recommended for any production workload.
@@ -138,6 +148,7 @@ Use these links to navigate to a particular top-level stanza.
default: "none"
- `cacheSize` ((#v-controller-manager-clientcache-cachesize)) (`integer: ""`) - Defines the size of the in-memory LRU cache *in entries*, that is used by the client cache controller.
May also be set via the `VSO_CLIENT_CACHE_SIZE` environment variable.
Larger numbers will increase memory usage by the controller, lower numbers will cause more frequent evictions
of the client cache which can result in additional Vault client counts.
@@ -263,14 +274,27 @@ Use these links to navigate to a particular top-level stanza.
X-vault-something1: "foo"
- `maxConcurrentReconciles` ((#v-controller-manager-maxconcurrentreconciles)) (`integer: ""`) - Defines the maximum number of concurrent reconciles for each controller.
May also be set via the `VSO_MAX_CONCURRENT_RECONCILES` environment variable.
default: 100
- `extraEnv` ((#v-controller-manager-extraenv)) (`array<map>`) - Defines additional environment variables to be added to the
vault-secrets-opearator manager container.
vault-secrets-operator manager container.
Example:
```yaml
extraEnv:
- name: HTTP_PROXY
value: http://proxy.example.com
- name: VSO_OUTPUT_FORMAT
value: json
- name: VSO_CLIENT_CACHE_SIZE
value: "20000"
- name: VSO_CLIENT_CACHE_PERSISTENCE_MODEL
value: "direct-encrypted"
- name: VSO_MAX_CONCURRENT_RECONCILES
value: "30"
```
- `extraArgs` ((#v-controller-manager-extraargs)) (`array: []`) - Defines additional commandline arguments to be passed to the
vault-secrets-operator manager container.
@@ -390,6 +414,8 @@ Use these links to navigate to a particular top-level stanza.
- `namespace` ((#v-defaultauthmethod-namespace)) (`string: ""`) - Vault namespace for the VaultAuthMethod CR
- `allowedNamespaces` ((#v-defaultauthmethod-allowednamespaces)) (`array<string>: []`) - Kubernetes namespace glob patterns which are allow-listed for use with the default AuthMethod.
- `method` ((#v-defaultauthmethod-method)) (`string: kubernetes`) - Vault Auth method to be used with the VaultAuthMethod CR
- `mount` ((#v-defaultauthmethod-mount)) (`string: kubernetes`) - Mount path for the Vault Auth Method.

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

@@ -27,6 +27,7 @@ The following features are supported by the Vault Secrets Operator:
- 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*
- Support for [secret data transformation](/vault/docs/platform/k8s/vso/secret-transformation).
## Supported secret sources

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

@@ -31,13 +31,13 @@ $ helm repo add hashicorp https://helm.releases.hashicorp.com
```shell-session
$ helm search repo hashicorp/vault-secrets-operator
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/vault-secrets-operator 0.4.3 0.4.3 Official HashiCorp Vault Secrets Operator Chart
hashicorp/vault-secrets-operator 0.5.0 0.5.0 Official HashiCorp Vault Secrets Operator Chart
```
Then install the Operator:
```shell-session
$ helm install --version 0.4.3 --create-namespace --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator
$ helm install --version 0.5.0 --create-namespace --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator
```
## Upgrading using Helm
@@ -65,10 +65,10 @@ $ helm show crds --version <TARGET_VSO_VERSION> hashicorp/vault-secrets-operator
$ helm upgrade --version <TARGET_VSO_VERSION> --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator
```
For example, if you are upgrading to VSO 0.4.3:
For example, if you are upgrading to VSO 0.5.0:
```shell-session
$ helm show crds --version 0.4.3 hashicorp/vault-secrets-operator | kubectl apply -f -
$ helm upgrade --version 0.4.3 --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator
$ helm show crds --version 0.5.0 hashicorp/vault-secrets-operator | kubectl apply -f -
$ helm upgrade --version 0.5.0 --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator
```
## Updating CRDs when using Helm
@@ -83,9 +83,9 @@ To update the VSO CRDs, replace `<TARGET_VSO_VERSION>` with the VSO version you
$ helm show crds --version <TARGET_VSO_VERSION> hashicorp/vault-secrets-operator | kubectl apply -f -
```
For example, if you are upgrading to VSO 0.4.3:
For example, if you are upgrading to VSO 0.5.0:
```shell-session
$ helm show crds --version 0.4.3 hashicorp/vault-secrets-operator | kubectl apply -f -
$ helm show crds --version 0.5.0 hashicorp/vault-secrets-operator | kubectl apply -f -
customresourcedefinition.apiextensions.k8s.io/hcpauths.secrets.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/hcpvaultsecretsapps.secrets.hashicorp.com created
@@ -112,9 +112,9 @@ You can install and update your installation using `kustomize` which allows you
To install using Kustomize, download and untar/unzip the latest release from the [Releases Page](https://github.com/hashicorp/vault-secrets-operator/releases).
```shell-session
$ wget -q https://github.com/hashicorp/vault-secrets-operator/archive/refs/tags/v0.4.3.tar.gz
$ tar -zxf v0.4.3.tar.gz
$ cd vault-secrets-operator-0.4.3/
$ wget -q https://github.com/hashicorp/vault-secrets-operator/archive/refs/tags/v0.5.0.tar.gz
$ tar -zxf v0.5.0.tar.gz
$ cd vault-secrets-operator-0.5.0/
```
Next install using `kustomize build`:

4
website/content/docs/platform/k8s/vso/openshift.mdx
View File

@@ -23,7 +23,7 @@ The Vault Secrets Operator may also be installed in OpenShift using the Helm cha
$ helm install vault-secrets-operator hashicorp/vault-secrets-operator \
--create-namespace \
--namespace vault-secrets-operator \
--version 0.4.3 \
--version 0.5.0 \
--values values.yaml
```
@@ -56,7 +56,7 @@ controller:
manager:
image:
repository: registry.connect.redhat.com/hashicorp/vault-secrets-operator
tag: 0.4.3-ubi
tag: 0.5.0-ubi
resources:
limits:
memory: 256Mi

245
website/content/docs/platform/k8s/vso/secret-transformation.mdx Normal file
View File

@@ -0,0 +1,245 @@
---
layout: docs
page_title: Vault Secrets Operator Secret Transformation
description: >-
Learn how to transform Secret data with the Vault Secrets Operator.
---
# Secret data transformation
Utilizing advanced templating and data filters, the Vault Secrets Operator for Kubernetes (VSO) can
transform source secret data, secret metadata, resource labels and annotations into a format that is
compatible with your application. All secret data sources are supported. Secret transformations can
be specified directly within a secret custom resource (CR), or by references to one or more
[SecretTransformation](/vault/docs/platform/k8s/vso/api-reference#secrettransformation) custom resource
instances, or both.
## Templating
VSO utilizes the data-driven [templates for Golang](https://pkg.go.dev/text/template) to generate
secret data output. The template data input holds the secret data, secret metadata, resource labels
and annotations.
Templates are configured in a secret custom resource's
[spec.Destination.Transformation.Templates](/vault/docs/platform/k8s/vso/api-reference#transformation),
or in a SecretTransformation resource's [spec.templates](/vault/docs/platform/k8s/vso/api-reference#secrettransformationspec).
VSO provides access to a large library of template functions, some of which are documented
[below](#template-functions).
### Secret data input
Secret data is accessed through the `.Secrets` input member. It contains a map of secret
key-value pairs, which are assumed to be sensitive information fetched from a
[secret source](/vault/docs/platform/k8s/vso/sources).
For example, to include a password in your application's secret, you might specify
a template like:
```go
{{- printf "password=%s" (get .Secrets "password") -}}
```
### Secret metadata input
Secret metadata is accessed through the `.Metadata` input member. It contains a map of metadata key to
its value. The data should not contain any confidential information.
For example, to include a secret metadata value in your application's secret, you might specify
a template like:
```go
{{- printf "secretGroup=%s" (get .Metadata "secretGroup") -}}
```
### Resource annotations input
Resource annotations are accessed through the `.Annotations` input member. The annotations consist
of all `metadata.annotations` configured on the secret custom resource.
For example, to include a value from the resource's annotations in your application's secret, you
might specify a template like:
```go
{{- printf "host=%s" (get .Annotations "myapp.config/host") -}}
```
### Resource labels input
Resource labels are accessed through the `.Labels` input member. The labels consist
of all `metadata.labels` configured on the secret custom resource.
For example, to include a value from the resource's labels in your application's secret, you
might specify a template like:
```go
{{- printf "appType=%s" (get .Labels "appType") -}}
```
## Filters
Filters are used to control which source secret data fields are included in the destination secret's
data. They are specified as a set of exclude/include RE2 accepted [regular expressions](https://golang.org/s/re2syntax).
Filters are configured in the `excludes` and `includes` fields of a secret custom resource's
[spec.Destination.Transformation](/vault/docs/platform/k8s/vso/api-reference#transformation),
or in a SecretTransformation resource's [spec](/vault/docs/platform/k8s/vso/api-reference#secrettransformationspec).
All exclude patterns take precedence over any include patterns, and are never applied to templated keys.
## Examples
### Local transformation
A VaultDynamicSecret configured to sync Postgres database credentials from Vault to the Kubernetes
secret named `example-vds`.
```yaml
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
namespace: example-ns
name: example-vds
annotations:
myapp.config/postgres-host: postgres-postgresql.postgres.svc.cluster.local:5432
spec:
destination:
create: true
name: app-secret
transformation:
excludes:
- .*
templates:
url:
text: |
{{- $host := get .Annotations "myapp.config/postgres-host" -}}
{{- printf "postgresql://%s:%s@%s/postgres?sslmode=disable" (get .Secrets "username") (get .Secrets "password") $host -}}
path: creds/dev-postgres
```
The resulting Kubernetes secret includes a single key named `url`, with a valid Postgres connection
URL as its value.
```yaml
url: postgresql://v-postgres-user:XUpah-password@postgres-postgresql.postgres.svc.cluster.local:5432/postgres?sslmode=disable
```
### Shared transformation
The following manifest contains shared transformation templates and filters. All `templates` it provides
will be included in the destination k8s secret. It also provides `sourceTemplates` that can be included
in any template text configured in a secret CR or within the same resource instance.
```yaml
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: SecretTransformation
metadata:
name: vso-templates
namespace: example-vds
spec:
excludes:
- password|username
templates:
url:
text: '{{- template "dbUrl" . -}}'
sourceTemplates:
- name: helpers
text: |
{{/*
create a Java props from SecretInput for this app
*/}}
{{- define "appProps" -}}
{{- $host := get .Annotations "myapp.config/postgres-host" -}}
{{- printf "db.host=%s\n" $host -}}
{{- range $k, $v := .Secrets -}}
{{- printf "db.%s=%s\n" $k $v -}}
{{- end -}}
{{- end -}}
{{/*
create a JSON config from SecretInput for this app
*/}}
{{- define "appJson" -}}
{{- $host := get .Annotations "myapp.config/postgres-host" -}}
{{- $copy := .Secrets | mustDeepCopy -}}
{{- $_ := set $copy "host" $host -}}
{{- mustToPrettyJson $copy -}}
{{- end -}}
{{/*
compose a Postgres URL from SecretInput for this app
*/}}
{{- define "dbUrl" -}}
{{- $host := get .Annotations "myapp.config/postgres-host" -}}
{{- printf "postgresql://%s:%s@%s/postgres?sslmode=disable" (get .Secrets "username") (get .Secrets "password") $host -}}
{{- end -}}
{{/*
get the app name from the VSO resource's label
*/}}
{{- define "appName" -}}
{{- get .Labels "myapp/name" -}}
{{- end -}}
```
The following `VaultDynamicSecret` manifest references the `SecretTransformation` above.
All templates and filters from the reference object will be applied to the destination secret data.
```yaml
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
namespace: example-ns
name: example-vds
annotations:
myapp.config/postgres-host: postgres-postgresql.postgres.svc.cluster.local:5432
spec:
destination:
create: true
name: app-secret
transformation:
transformationRefs:
- name: vso-templates
path: creds/dev-postgres
```
The resulting Kubernetes secret includes a single key named `url`, with a valid Postgres connection
URL as its value
```yaml
url: postgresql://v-postgres-user:XUpah-password@postgres-postgresql.postgres.svc.cluster.local:5432/postgres?sslmode=disable
```
### Template functions
All template functions are provided by the [sprig](http://masterminds.github.io/sprig) library. Some common functions are mentioned below.
For the complete list of functions see [allowedSprigFuncs](https://github.com/hashicorp/vault-secrets-operator/blob/main/internal/template/funcs.go#L26)
### String functions
`trim` removes any leading or trailing whitespaces from the input:
```
trim " host " -> `host`
```
### Encoding functions
`b64enc` base64 encodes an input value
```
b64enc "host" -> `aG9zdAo=`
```
`b64dec` base64 decodes an input value
```
b64dec "aG9zdAo=" -> `host`
```
### Map functions
`get` retrieves a value from a `map` input:
```
get .Secrets "baz" -> `qux`
```
## Related API references
- [Transformation](/vault/docs/platform/k8s/vso/api-reference#transformation)
- [HCPVaultSecretsApp](/vault/docs/platform/k8s/vso/api-reference#hcpvaultsecretsapp)
- [VaultDynamicSecret](/vault/docs/platform/k8s/vso/api-reference#vaultdynamicsecret)
- [VaultPKISecret](/vault/docs/platform/k8s/vso/api-reference#vaultpkisecret)
- [VaultStaticSecret](/vault/docs/platform/k8s/vso/api-reference#vaultstaticsecret)
- [SecretTransformation](/vault/docs/platform/k8s/vso/api-reference#secrettransformation)

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

@@ -2054,13 +2054,17 @@
]
},
{
"title": "Examples",
"path": "platform/k8s/vso/examples"
"title": "Secret Data Transformation",
"path": "platform/k8s/vso/secret-transformation"
},
{
"title": "Helm Chart",
"path": "platform/k8s/vso/helm"
},
{
"title": "Examples",
"path": "platform/k8s/vso/examples"
},
{
"title": "Telemetry",
"path": "platform/k8s/vso/telemetry"