From 12002fb3e7caf3831ff40d46311da92c95845a3c Mon Sep 17 00:00:00 2001 From: Theron Voran Date: Wed, 29 Mar 2023 16:49:11 -0700 Subject: [PATCH] backport of commit 25934124a046199f7434f9c61e1454bcbef08cdf (#19836) * backport of commit 25934124a046199f7434f9c61e1454bcbef08cdf --------- Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> --- .../content/docs/platform/k8s/csi/index.mdx | 2 +- .../docs/platform/k8s/csi/installation.mdx | 6 +- website/content/docs/platform/k8s/index.mdx | 22 + .../docs/platform/k8s/vso/api-reference.mdx | 408 ++++++++++++++++++ .../docs/platform/k8s/vso/examples.mdx | 14 + .../content/docs/platform/k8s/vso/helm.mdx | 252 +++++++++++ .../content/docs/platform/k8s/vso/index.mdx | 182 ++++++++ .../docs/platform/k8s/vso/installation.mdx | 49 +++ .../docs/platform/k8s/vso/telemetry.mdx | 14 + website/content/partials/vso-beta-note.mdx | 2 + website/data/docs-nav-data.json | 29 ++ 11 files changed, 976 insertions(+), 4 deletions(-) create mode 100644 website/content/docs/platform/k8s/vso/api-reference.mdx create mode 100644 website/content/docs/platform/k8s/vso/examples.mdx create mode 100644 website/content/docs/platform/k8s/vso/helm.mdx create mode 100644 website/content/docs/platform/k8s/vso/index.mdx create mode 100644 website/content/docs/platform/k8s/vso/installation.mdx create mode 100644 website/content/docs/platform/k8s/vso/telemetry.mdx create mode 100644 website/content/partials/vso-beta-note.mdx diff --git a/website/content/docs/platform/k8s/csi/index.mdx b/website/content/docs/platform/k8s/csi/index.mdx index 3e83d4631bdf..8bc00e8bf987 100644 --- a/website/content/docs/platform/k8s/csi/index.mdx +++ b/website/content/docs/platform/k8s/csi/index.mdx @@ -148,4 +148,4 @@ the Secret Provider Class named `vault-db-creds`. ## Tutorial Refer to the [Vault CSI Provider](/vault/tutorials/kubernetes/kubernetes-secret-store-driver) -tutorial to learn how to set up Vault and its depedencies with a Helm chart. +tutorial to learn how to set up Vault and its dependencies with a Helm chart. diff --git a/website/content/docs/platform/k8s/csi/installation.mdx b/website/content/docs/platform/k8s/csi/installation.mdx index ccce5365640e..9fa130bc541f 100644 --- a/website/content/docs/platform/k8s/csi/installation.mdx +++ b/website/content/docs/platform/k8s/csi/installation.mdx @@ -35,7 +35,7 @@ Then install the chart and enable the CSI feature by setting the $ helm install vault hashicorp/vault --set="csi.enabled=true" ``` -Upgrades may be performed with `helm upgrade` on an existing install. Please +Upgrades may be performed with `helm upgrade` on an existing installation. Please always run Helm with `--dry-run` before any install or upgrade to verify changes. @@ -116,8 +116,8 @@ users: EOF ``` -Add the security context constraint for the applicaiton. +Add the security context constraint for the application. ```shell-session $ kubectl apply -f application-scc.yaml -``` \ No newline at end of file +``` diff --git a/website/content/docs/platform/k8s/index.mdx b/website/content/docs/platform/k8s/index.mdx index dcf59066179b..7ffbb36a1c77 100644 --- a/website/content/docs/platform/k8s/index.mdx +++ b/website/content/docs/platform/k8s/index.mdx @@ -54,6 +54,28 @@ There are several ways to try Vault with Kubernetes in different environments. - [Vault on Kubernetes Deployment Guide](/vault/tutorials/kubernetes/kubernetes-raft-deployment-guide) covers the steps required to install and configure a single HashiCorp Vault cluster as defined in the [Vault on Kubernetes Reference Architecture](/vault/tutorials/kubernetes/kubernetes-reference-architecture). +### High Level Comparison of Integrations + +There are currently 3 different integrations to help Kubernetes workloads seamlessly consume secrets from Vault, without the need to modify the application to interact directly with Vault. Each integration addresses slightly different use-cases. The following is a brief overview of the strengths of each integration. + +#### Agent Injector + +- No durable secret storage outside Vault. All secrets written to disk are in ephemeral in-memory volumes. +- No highly privileged service accounts required. All secrets are fetched with the pod's own service account without the need for any other service accounts to impersonate it. +- More mature solution, with proven production record and advanced features like templating, + wider array of auth methods, etc. + +#### Vault Secrets Operator (public beta) + +- 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. +- Better Vault secret availability. Kubernetes secrets act as a durable cluster-local cache of Vault secrets. + +#### Vault CSI Provider + +- The CSI driver that the provider is based on is vendor neutral. +- No durable secret storage outside Vault if the secret sync feature isn't used. All secrets written to disk are in ephemeral in-memory volumes. + ### Documentation - [Vault on Kubernetes Reference Architecture](/vault/tutorials/kubernetes/kubernetes-reference-architecture) provides recommended practices for running Vault on Kubernetes in production. diff --git a/website/content/docs/platform/k8s/vso/api-reference.mdx b/website/content/docs/platform/k8s/vso/api-reference.mdx new file mode 100644 index 000000000000..32c0fb5d0342 --- /dev/null +++ b/website/content/docs/platform/k8s/vso/api-reference.mdx @@ -0,0 +1,408 @@ +--- +layout: docs +page_title: Vault Secrets Operator API Reference +description: >- + The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets. +--- + +@include 'vso-beta-note.mdx' + + +# API Reference + +## Packages +- [secrets.hashicorp.com/v1alpha1](#secretshashicorpcomv1alpha1) + + +## secrets.hashicorp.com/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the secrets v1alpha1 API group + +### Resource Types +- [VaultAuth](#vaultauth) +- [VaultAuthList](#vaultauthlist) +- [VaultConnection](#vaultconnection) +- [VaultConnectionList](#vaultconnectionlist) +- [VaultDynamicSecret](#vaultdynamicsecret) +- [VaultDynamicSecretList](#vaultdynamicsecretlist) +- [VaultPKISecret](#vaultpkisecret) +- [VaultPKISecretList](#vaultpkisecretlist) +- [VaultStaticSecret](#vaultstaticsecret) +- [VaultStaticSecretList](#vaultstaticsecretlist) + + + +#### Destination + + + +Destination provides the configuration that will be applied to the destination Kubernetes Secret during a Vault Secret -> K8s Secret sync. + +_Appears in:_ +- [VaultDynamicSecretSpec](#vaultdynamicsecretspec) +- [VaultPKISecretSpec](#vaultpkisecretspec) +- [VaultStaticSecretSpec](#vaultstaticsecretspec) + +| Field | Description | +| --- | --- | +| `name` _string_ | Name of the Secret | +| `create` _boolean_ | Create the destination Secret. If the Secret already exists this should be set to false. | +| `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.22/#secrettype-v1-core)_ | Type of Kubernetes Secret. Requires Create to be set to true. Defaults to Opaque. | + + +#### RolloutRestartTarget + + + +RolloutRestartTarget provides the configuration required to perform a rollout-restart of the supported resources upon Vault Secret rotation. The rollout-restart is triggered by patching the target resource's 'spec.template.metadata.annotations' to include 'vso.secrets.hashicorp.com/restartedAt' with a timestamp value of when the trigger was executed. E.g. vso.secrets.hashicorp.com/restartedAt: "2023-03-23T13:39:31Z" +Supported resources: Deployment, DaemonSet, StatefulSet + +_Appears in:_ +- [VaultDynamicSecretSpec](#vaultdynamicsecretspec) +- [VaultPKISecretSpec](#vaultpkisecretspec) +- [VaultStaticSecretSpec](#vaultstaticsecretspec) + +| Field | Description | +| --- | --- | +| `kind` _string_ | | +| `name` _string_ | | + + +#### StorageEncryption + + + +StorageEncryption provides the necessary configuration needed to encrypt the storage cache entries using Vault's Transit engine. It only supports Kubernetes Auth for now. + +_Appears in:_ +- [VaultAuthSpec](#vaultauthspec) + +| Field | Description | +| --- | --- | +| `mount` _string_ | Mount path of the Transit engine in Vault. | +| `keyName` _string_ | KeyName to use for encrypt/decrypt operations via Vault Transit. | + + +#### VaultAuth + + + +VaultAuth is the Schema for the vaultauths API + +_Appears in:_ +- [VaultAuthList](#vaultauthlist) + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultAuth` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[VaultAuthSpec](#vaultauthspec)_ | | + + +#### VaultAuthConfigKubernetes + + + +VaultAuthConfigKubernetes provides VaultAuth configuration options needed for authenticating to Vault. + +_Appears in:_ +- [VaultAuthSpec](#vaultauthspec) + +| Field | Description | +| --- | --- | +| `role` _string_ | Role to use for authenticating to Vault. | +| `serviceAccount` _string_ | ServiceAccount to use when authenticating to Vault's kubernetes authentication backend. | +| `audiences` _string array_ | TokenAudiences to include in the ServiceAccount token. | +| `tokenExpirationSeconds` _integer_ | TokenExpirationSeconds to set the ServiceAccount token. | + + +#### VaultAuthList + + + +VaultAuthList contains a list of VaultAuth + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultAuthList` +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` _[VaultAuth](#vaultauth) array_ | | + + +#### VaultAuthSpec + + + +VaultAuthSpec defines the desired state of VaultAuth + +_Appears in:_ +- [VaultAuth](#vaultauth) + +| Field | Description | +| --- | --- | +| `vaultConnectionRef` _string_ | 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. | +| `namespace` _string_ | Namespace to auth to in Vault | +| `method` _string_ | Method to use when authenticating to Vault. | +| `mount` _string_ | Mount to use when authenticating to auth method. | +| `params` _object (keys:string, values:string)_ | Params to use when authenticating to Vault | +| `headers` _object (keys:string, values:string)_ | Headers to be included in all Vault requests. | +| `kubernetes` _[VaultAuthConfigKubernetes](#vaultauthconfigkubernetes)_ | Kubernetes specific auth configuration, requires that the Method be set to kubernetes. | +| `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 the label: cacheStorageEncryption=true | + + + + +#### VaultConnection + + + +VaultConnection is the Schema for the vaultconnections API + +_Appears in:_ +- [VaultConnectionList](#vaultconnectionlist) + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultConnection` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[VaultConnectionSpec](#vaultconnectionspec)_ | | + + +#### VaultConnectionList + + + +VaultConnectionList contains a list of VaultConnection + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultConnectionList` +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` _[VaultConnection](#vaultconnection) array_ | | + + +#### VaultConnectionSpec + + + +VaultConnectionSpec defines the desired state of VaultConnection + +_Appears in:_ +- [VaultConnection](#vaultconnection) + +| Field | Description | +| --- | --- | +| `address` _string_ | Address of the Vault server | +| `headers` _object (keys:string, values:string)_ | Headers to be included in all Vault requests. | +| `tlsServerName` _string_ | TLSServerName to use as the SNI host for TLS connections. | +| `caCertSecretRef` _string_ | CACertSecretRef containing the trusted PEM encoded CA certificate chain. | +| `skipTLSVerify` _boolean_ | SkipTLSVerify for TLS connections. | + + + + +#### VaultDynamicSecret + + + +VaultDynamicSecret is the Schema for the vaultdynamicsecrets API + +_Appears in:_ +- [VaultDynamicSecretList](#vaultdynamicsecretlist) + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultDynamicSecret` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[VaultDynamicSecretSpec](#vaultdynamicsecretspec)_ | | + + +#### VaultDynamicSecretList + + + +VaultDynamicSecretList contains a list of VaultDynamicSecret + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultDynamicSecretList` +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` _[VaultDynamicSecret](#vaultdynamicsecret) array_ | | + + +#### VaultDynamicSecretSpec + + + +VaultDynamicSecretSpec defines the desired state of VaultDynamicSecret + +_Appears in:_ +- [VaultDynamicSecret](#vaultdynamicsecret) + +| Field | Description | +| --- | --- | +| `vaultAuthRef` _string_ | VaultAuthRef to the VaultAuth resource If no value is specified the Operator will default to the `default` VaultAuth, configured in its own Kubernetes namespace. | +| `namespace` _string_ | Namespace where the secrets engine is mounted in Vault. | +| `mount` _string_ | Mount path of the secret's engine in Vault. | +| `role` _string_ | Role in Vault to get the credentials for. | +| `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. | + + + + +#### VaultPKISecret + + + +VaultPKISecret is the Schema for the vaultpkisecrets API + +_Appears in:_ +- [VaultPKISecretList](#vaultpkisecretlist) + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultPKISecret` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[VaultPKISecretSpec](#vaultpkisecretspec)_ | | + + +#### VaultPKISecretList + + + +VaultPKISecretList contains a list of VaultPKISecret + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultPKISecretList` +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` _[VaultPKISecret](#vaultpkisecret) array_ | | + + +#### VaultPKISecretSpec + + + +VaultPKISecretSpec defines the desired state of VaultPKISecret + +_Appears in:_ +- [VaultPKISecret](#vaultpkisecret) + +| Field | Description | +| --- | --- | +| `vaultAuthRef` _string_ | VaultAuthRef of the VaultAuth resource If no value is specified the Operator will default to the `default` VaultAuth, configured in its own Kubernetes namespace. | +| `namespace` _string_ | Namespace to get the secret from in Vault | +| `mount` _string_ | Mount for the secret in Vault | +| `name` _string_ | Name of the secret in Vault | +| `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. | +| `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", the Vault response fields "certificate" and "private_key" will be copied to fields "tls.crt" and "tls.key", respectively, in the Kubernetes secret. | +| `commonName` _string_ | CommonName to include in the request. | +| `altNames` _string array_ | AltNames to include in the request May contain both DNS names and email addresses. | +| `ipSans` _string array_ | IPSans to include in the request. | +| `uriSans` _string array_ | The requested URI SANs. | +| `otherSans` _string_ | Requested other SANs, in an array with the format oid;type:value for each entry. | +| `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 | +| `notAfter` _string_ | NotAfter field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ | +| `excludeCNFromSans` _boolean_ | ExcludeCNFromSans from DNS or Email Subject Alternate Names. Default: false | + + + + +#### VaultSecretLease + + + + + +_Appears in:_ +- [VaultDynamicSecretStatus](#vaultdynamicsecretstatus) + +| Field | Description | +| --- | --- | +| `id` _string_ | ID of the Vault secret. | +| `duration` _integer_ | LeaseDuration of the Vault secret. | +| `renewable` _boolean_ | Renewable Vault secret lease | +| `requestID` _string_ | RequestID of the Vault secret request. | + + +#### VaultStaticSecret + + + +VaultStaticSecret is the Schema for the vaultstaticsecrets API + +_Appears in:_ +- [VaultStaticSecretList](#vaultstaticsecretlist) + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultStaticSecret` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[VaultStaticSecretSpec](#vaultstaticsecretspec)_ | | + + +#### VaultStaticSecretList + + + +VaultStaticSecretList contains a list of VaultStaticSecret + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `kind` _string_ | `VaultStaticSecretList` +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` _[VaultStaticSecret](#vaultstaticsecret) array_ | | + + +#### VaultStaticSecretSpec + + + +VaultStaticSecretSpec defines the desired state of VaultStaticSecret + +_Appears in:_ +- [VaultStaticSecret](#vaultstaticsecret) + +| Field | Description | +| --- | --- | +| `vaultAuthRef` _string_ | VaultAuthRef of the VaultAuth resource If no value is specified the Operator will default to the `default` VaultAuth, configured in its own Kubernetes namespace. | +| `namespace` _string_ | Namespace to get the secret from in Vault | +| `mount` _string_ | Mount for the secret in Vault | +| `name` _string_ | Name of the secret in Vault | +| `type` _string_ | Type of the Vault static secret | +| `refreshAfter` _string_ | RefreshAfter a period of time, in duration notation | +| `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. | diff --git a/website/content/docs/platform/k8s/vso/examples.mdx b/website/content/docs/platform/k8s/vso/examples.mdx new file mode 100644 index 000000000000..2289dedb6d96 --- /dev/null +++ b/website/content/docs/platform/k8s/vso/examples.mdx @@ -0,0 +1,14 @@ +--- +layout: docs +page_title: Vault Secrets Operator Examples +description: >- + The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets. +--- + +@include 'vso-beta-note.mdx' + +# 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) +- A Terraform based demo can be found [here](https://github.com/hashicorp/vault-secrets-operator/tree/main/demo) diff --git a/website/content/docs/platform/k8s/vso/helm.mdx b/website/content/docs/platform/k8s/vso/helm.mdx new file mode 100644 index 000000000000..45bcc76e5eb1 --- /dev/null +++ b/website/content/docs/platform/k8s/vso/helm.mdx @@ -0,0 +1,252 @@ +--- +layout: docs +page_title: Vault Secrets Operator Helm Chart Configuration +description: >- + Configuration for the Vault Secrets Operator Helm chart. +--- + +@include 'vso-beta-note.mdx' + +# 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). + + + + +## Top-Level Stanzas + +Use these links to navigate to a particular top-level stanza. + +- [`controller`](#h-controller) +- [`metricsService`](#h-metricsservice) +- [`defaultVaultConnection`](#h-defaultvaultconnection) +- [`defaultAuthMethod`](#h-defaultauthmethod) +- [`tests`](#h-tests) + +## All Values + +### controller ((#h-controller)) + +- `controller` ((#v-controller)) - Top level configuration for the vault secrets operator deployment. + This is comprised of a controller and a kube rbac proxy container. + + - `replicas` ((#v-controller-replicas)) (`integer: 1`) - Set the number of replicas for the operator. + + - `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. + + - `image` ((#v-controller-kuberbacproxy-image)) - Image sets the repo and tag of the kube-rbac-proxy image to use for the controller. + + - `repository` ((#v-controller-kuberbacproxy-image-repository)) (`string: gcr.io/kubebuilder/kube-rbac-proxy`) + + - `tag` ((#v-controller-kuberbacproxy-image-tag)) (`string: v0.11.0`) + + - `resources` ((#v-controller-kuberbacproxy-resources)) (`map`) - Configures the default resources for the kube rbac proxy container. + For more information on configuring resources, see the K8s documentation: + https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + + - `limits` ((#v-controller-kuberbacproxy-resources-limits)) + + - `cpu` ((#v-controller-kuberbacproxy-resources-limits-cpu)) (`string: 500m`) + + - `memory` ((#v-controller-kuberbacproxy-resources-limits-memory)) (`string: 128Mi`) + + - `requests` ((#v-controller-kuberbacproxy-resources-requests)) + + - `cpu` ((#v-controller-kuberbacproxy-resources-requests-cpu)) (`string: 5m`) + + - `memory` ((#v-controller-kuberbacproxy-resources-requests-memory)) (`string: 64Mi`) + + - `manager` ((#v-controller-manager)) - Settings related to the vault-secrets-operator container. + + - `image` ((#v-controller-manager-image)) - Image sets the repo and tag of the vault-secrets-operator image to use for the controller. + + - `repository` ((#v-controller-manager-image-repository)) (`string: hashicorp/vault-secrets-operator`) + + - `tag` ((#v-controller-manager-image-tag)) (`string: 0.1.0-beta`) + + - `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 around their TTLs as well as the + ability to renew. + + - `persistenceModel` ((#v-controller-manager-clientcache-persistencemodel)) (`string: ""`) - Defines the `-client-cache-persistence-model` which caches+persists vault tokens. + 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. + "direct-encrypted" - in-memory client cache is persisted encrypted using the Vault Transit engine. + + 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. + 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. + + default: 10000 + + - `maxConcurrentReconciles` ((#v-controller-manager-maxconcurrentreconciles)) (`integer: ""`) - Defines the maximum number of concurrent reconciles by the controller. + NOTE: Currently this is only used by the reconciliation logic of dynamic secrets. + + default: 100 + + - `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/ + + - `limits` ((#v-controller-manager-resources-limits)) + + - `cpu` ((#v-controller-manager-resources-limits-cpu)) (`string: 500m`) + + - `memory` ((#v-controller-manager-resources-limits-memory)) (`string: 128Mi`) + + - `requests` ((#v-controller-manager-resources-requests)) + + - `cpu` ((#v-controller-manager-resources-requests-cpu)) (`string: 10m`) + + - `memory` ((#v-controller-manager-resources-requests-memory)) (`string: 64Mi`) + + - `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: + https://kubernetes.io/docs/concepts/configuration/configmap/ + + - `health` ((#v-controller-controllerconfigmapyaml-health)) + + - `healthProbeBindAddress` ((#v-controller-controllerconfigmapyaml-health-healthprobebindaddress)) (`string: :8081`) + + - `leaderElection` ((#v-controller-controllerconfigmapyaml-leaderelection)) + + - `leaderElect` ((#v-controller-controllerconfigmapyaml-leaderelection-leaderelect)) (`boolean: true`) + + - `resourceName` ((#v-controller-controllerconfigmapyaml-leaderelection-resourcename)) (`string: b0d477c0.hashicorp.com`) + + - `metrics` ((#v-controller-controllerconfigmapyaml-metrics)) + + - `bindAddress` ((#v-controller-controllerconfigmapyaml-metrics-bindaddress)) (`string: 127.0.0.1:8080`) + + - `webhook` ((#v-controller-controllerconfigmapyaml-webhook)) + + - `port` ((#v-controller-controllerconfigmapyaml-webhook-port)) (`integer: 9443`) + + - `kubernetesClusterDomain` ((#v-controller-kubernetesclusterdomain)) (`string: cluster.local`) - Configures the environment variable KUBERNETES_CLUSTER_DOMAIN used by KubeDNS. + +### metricsService ((#h-metricsservice)) + +- `metricsService` ((#v-metricsservice)) (`map`) - Configure the metrics service ports used by the metrics service. + Set the configuration fo the metricsService port. + + - `ports` ((#v-metricsservice-ports)) (`map`) - Set the port settings for the metrics service. + For more information on configuring resources, see the K8s documentation: + https://kubernetes.io/docs/concepts/services-networking/service/ + + - `name` ((#v-metricsservice-ports-name)) (`string: https`) + + - `port` ((#v-metricsservice-ports-port)) (`integer: 8443`) + + - `protocol` ((#v-metricsservice-ports-protocol)) (`string: TCP`) + + - `targetPort` ((#v-metricsservice-ports-targetport)) (`string: https`) + + - `type` ((#v-metricsservice-type)) (`string: ClusterIP`) + +### defaultVaultConnection ((#h-defaultvaultconnection)) + +- `defaultVaultConnection` ((#v-defaultvaultconnection)) - Configures the default VaultConnection CR which will be used by resources + if they do not specify a VaultConnection reference. The name is 'default' and will + always be installed in the same namespace as the operator. + NOTE: + * It is strongly recommended to deploy the vault secrets operator in a secure Vault environment + which includes a configuration utilizing TLS and installing Vault into its own restricted namespace. + + - `enabled` ((#v-defaultvaultconnection-enabled)) (`boolean: false`) - toggles the deployment of the VaultAuthMethod CR + + - `address` ((#v-defaultvaultconnection-address)) (`string: ""`) - Address of the Vault Server + Example: http://vault.default.svc.cluster.local:8200 + + - `caCertSecret` ((#v-defaultvaultconnection-cacertsecret)) (`string: ""`) - CACertSecret containing the trusted PEM encoded CA certificate chain. + Note: This secret must exist prior to deploying the CR. + + - `tlsServerName` ((#v-defaultvaultconnection-tlsservername)) (`string: ""`) - TLSServerName to use as the SNI host for TLS connections. + + - `skipTLSVerify` ((#v-defaultvaultconnection-skiptlsverify)) (`boolean: false`) - SkipTLSVerify for TLS connections. + + - `headers` ((#v-defaultvaultconnection-headers)) (`string: ""`) - Headers to be included in all Vault requests. + headers: | + "vault-something1": "foo" + "vault-something2": "bar" + "vault-something3": "baz" + +### defaultAuthMethod ((#h-defaultauthmethod)) + +- `defaultAuthMethod` ((#v-defaultauthmethod)) - Configures and deploys the default VaultAuthMethod CR which will be used by resources + if they do not specify a VaultAuthMethod reference. The name is 'default' and will + always be installed in the same namespace as the operator. + NOTE: + * It is strongly recommended to deploy the vault secrets operator in a secure Vault environment + which includes a configuration utilizing TLS and installing Vault into its own restricted namespace. + + - `enabled` ((#v-defaultauthmethod-enabled)) (`boolean: false`) - toggles the deployment of the VaultAuthMethod CR + + - `namespace` ((#v-defaultauthmethod-namespace)) (`string: ""`) - Vault namespace for the VaultAuthMethod CR + + - `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. + + - `kubernetes` ((#v-defaultauthmethod-kubernetes)) - Vault Kubernetes auth method specific configuration + + - `role` ((#v-defaultauthmethod-kubernetes-role)) (`string: ""`) - Vault Auth Role to use + This is a required field and must be setup in Vault prior to deploying the helm chart + if `defaultAuthMethod.enabled=true` + + - `serviceAccount` ((#v-defaultauthmethod-kubernetes-serviceaccount)) (`string: default`) - Kubernetes ServiceAccount associated with the default Vault Auth Role + + - `tokenAudiences` ((#v-defaultauthmethod-kubernetes-tokenaudiences)) (`array: []`) - Token Audience is required and should match whatever the audience + of the vault kubernetes auth role has set. + + - `params` ((#v-defaultauthmethod-params)) (`string: ""`) - Params to use when authenticating to Vault + params: | + "vault-something1": "foo" + "vault-something2": "bar" + "vault-something3": "baz" + + - `headers` ((#v-defaultauthmethod-headers)) (`string: ""`) - Headers to be included in all Vault requests. + headers: | + "vault-something1": "foo" + "vault-something2": "bar" + "vault-something3": "baz" + +### tests ((#h-tests)) + +- `tests` ((#v-tests)) - # Used by unit tests, and will not be rendered except when using `helm template`, this can be safely ignored. + + - `enabled` ((#v-tests-enabled)) (`boolean: true`) + + + +## Helm Chart Examples + +The below `config.yaml` results in a single replica installation of the Vault Secrets Operator +with a default vault connection and auth method custom resource deployed. +It expects a local Vault installation within the kubernetes cluster +accessible via `http://vault.default.svc.cluster.local:8200` with TLS disabled, +and a [Vault Auth Method](/vault/docs/auth/kubernetes) to be setup against the `default` ServiceAccount. + + +```yaml +# config.yaml + +defaultVaultConnection: + enabled: true +defaultVaultAuthMethod: + enabled: true + +``` + +## Customizing the Helm Chart + +If you need to extend the Helm chart with additional options, we recommend using a third-party tool, +such as [kustomize](https://github.com/kubernetes-sigs/kustomize) using the project repo `config/` path +in the [vault-secrets-operator](https://github.com/hashicorp/vault-secrets-operator) project. diff --git a/website/content/docs/platform/k8s/vso/index.mdx b/website/content/docs/platform/k8s/vso/index.mdx new file mode 100644 index 000000000000..2797cc684711 --- /dev/null +++ b/website/content/docs/platform/k8s/vso/index.mdx @@ -0,0 +1,182 @@ +--- +layout: docs +page_title: Vault Secrets Operator +description: >- + The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets. +--- + +@include 'vso-beta-note.mdx' + +# Vault Secrets Operator + +The Vault Secrets Operator (VSO) allows Pods to consume Vault secrets 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 +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. + +### Features + +The following features are supported by the Vault Secrets Operator: + +- All Vault secret engines supported. +- TLS/mTLS communications with Vault. +- Authentication using the requesting `Pod`'s `ServiceAccount` via the [Kubernetes Auth Method](/vault/docs/auth/kubernetes). +- Syncing Vault Secrets to Kubernetes Secrets. +- Secret rotation for `Deployment`, `ReplicaSet`, `StatefulSet` Kubernetes resource types. +- Prometheus instrumentation for monitoring the Operator +- Supported installation methods: `Helm`, `Kustomize`
+*see the [installation](/vault/docs/platform/k8s/vso/installation.mdx) docs for more details* + +## Vault Access and Custom Resource Definitions + +~> **Note:** Currently, the Operator only supports the [Kubernetes Auth Method](/vault/docs/auth/kubernetes). +Over time, we will be adding support for more Vault Auth methods. + +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/v1alpha1 +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/v1alpha1 +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.
+Supported secrets engines: [kv-v2](/vault/docs/secrets/kv/kv-v2), [kv-v1](/vault/docs/secrets/kv/kv-v1) + +```yaml +--- +apiVersion: secrets.hashicorp.com/v1alpha1 +kind: VaultStaticSecret +metadata: + namespace: vso-example + name: example +spec: + vaultAuthRef: example + mount: kvv2 + type: kv-v2 + name: secret + refreshAfter: 60s + destination: + create: true + name: static-secret1 +``` + +### VaultPKISecret Custom Resource +Provides the configuration necessary for the Operator to synchronize a single Vault *PKI* Secret to a single Kubernetes Secret.
+Supported secrets engines: [pki](/vault/docs/secrets/pki) + +```yaml +--- +apiVersion: secrets.hashicorp.com/v1alpha1 +kind: VaultPKISecret +metadata: + namespace: vso-example + name: example +spec: + vaultAuthRef: example + mount: pki + name: 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.
+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), ... + +```yaml +--- +apiVersion: secrets.hashicorp.com/v1alpha1 +kind: VaultDynamicSecret +metadata: + namespace: vso-example + name: example +spec: + vaultAuthRef: example + mount: db + role: postgres + destination: + create: true + name: dynamic1 +``` diff --git a/website/content/docs/platform/k8s/vso/installation.mdx b/website/content/docs/platform/k8s/vso/installation.mdx new file mode 100644 index 000000000000..448a96af057d --- /dev/null +++ b/website/content/docs/platform/k8s/vso/installation.mdx @@ -0,0 +1,49 @@ +--- +layout: docs +page_title: Vault Secrets Operator Installation +description: >- + The Vault Secrets Operator can be installed using Helm. +--- + +@include 'vso-beta-note.mdx' + +# Installing the Vault Secrets Operator + +## Prerequisites + +- Kubernetes 1.22+ +- Vault OSS/Enterprise 1.11+ + +## Installation using helm + +The [Vault Secrets Operator Helm chart](/vault/docs/platform/k8s/vso/helm) is the recommended way of +installing and configuring the Vault Secrets Operator. + +To install a new instance of the Vault Secrets Operator, first add the +HashiCorp helm repository and ensure you have access to the chart: + +```shell-session +$ helm repo add hashicorp https://helm.releases.hashicorp.com +"hashicorp" has been added to your repositories + +$ helm search repo hashicorp/vault-secrets-operator +NAME CHART VERSION APP VERSION DESCRIPTION +hashicorp/vault-secrets-operator 0.1.0-beta 0.1.0-beta 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 +``` + + +## Upgrading using helm + +Upgrades may be performed with `helm upgrade` on an existing install. Please +always run Helm with `--dry-run` before any install or upgrade to verify +changes. + + +### Helm Chart Values +All supported Helm chart values can be found [here](/vault/docs/platform/k8s/vso/helm) diff --git a/website/content/docs/platform/k8s/vso/telemetry.mdx b/website/content/docs/platform/k8s/vso/telemetry.mdx new file mode 100644 index 000000000000..6f5203879718 --- /dev/null +++ b/website/content/docs/platform/k8s/vso/telemetry.mdx @@ -0,0 +1,14 @@ +--- +layout: docs +page_title: Vault Secrets Operator Telemetry +description: >- + The Vault Secrets Operator allows Pods to consume Vault secrets natively from Kubernetes Secrets. +--- + +@include 'vso-beta-note.mdx' + +# Telemetry + +The Vault Secrets Operator is instrumented with Prometheus metrics. + +*More to come* diff --git a/website/content/partials/vso-beta-note.mdx b/website/content/partials/vso-beta-note.mdx new file mode 100644 index 000000000000..8be5326a5383 --- /dev/null +++ b/website/content/partials/vso-beta-note.mdx @@ -0,0 +1,2 @@ +~> The Vault Secrets Operator is in public beta.
+ *Please provide your feedback by opening a GitHub issue [here](https://github.com/hashicorp/vault-secrets-operator/issues)* diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 8b8d9be0f705..6157dd2a8c87 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1692,6 +1692,35 @@ "path": "platform/k8s/csi/examples" } ] + }, + { + "title": "Vault Secrets Operator", + "routes": [ + { + "title": "Overview", + "path": "platform/k8s/vso" + }, + { + "title": "Installation", + "path": "platform/k8s/vso/installation" + }, + { + "title": "Examples", + "path": "platform/k8s/vso/examples" + }, + { + "title": "Helm Chart", + "path": "platform/k8s/vso/helm" + }, + { + "title": "Telemetry", + "path": "platform/k8s/vso/telemetry" + }, + { + "title": "API Reference", + "path": "platform/k8s/vso/api-reference" + } + ] } ] },