diff --git a/website/content/docs/platform/k8s/vso/api-reference.mdx b/website/content/docs/platform/k8s/vso/api-reference.mdx index 02e9696c36a9..0a6bf1d46f7c 100644 --- a/website/content/docs/platform/k8s/vso/api-reference.mdx +++ b/website/content/docs/platform/k8s/vso/api-reference.mdx @@ -8,18 +8,18 @@ description: >- @include 'vso-beta-note.mdx' # API Reference ## Packages -- [secrets.hashicorp.com/v1alpha1](#secretshashicorpcomv1alpha1) +- [secrets.hashicorp.com/v1beta1](#secretshashicorpcomv1beta1) -## secrets.hashicorp.com/v1alpha1 +## secrets.hashicorp.com/v1beta1 -Package v1alpha1 contains API Schema definitions for the secrets v1alpha1 API group +Package v1beta1 contains API Schema definitions for the secrets v1beta1 API group ### Resource Types - [VaultAuth](#vaultauth) @@ -77,7 +77,7 @@ _Appears in:_ -StorageEncryption provides the necessary configuration needed 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. It only supports Kubernetes Auth for now. _Appears in:_ - [VaultAuthSpec](#vaultauthspec) @@ -99,12 +99,33 @@ _Appears in:_ | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultAuth` | `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` _[VaultAuthSpec](#vaultauthspec)_ | | +#### VaultAuthConfigAWS + + + +VaultAuthConfigAWS provides VaultAuth configuration options needed for authenticating to Vault via an AWS AuthMethod. Will use creds from `SecretRef` or `IRSAServiceAccount` if provided, in that order. If neither are provided, the underlying node role or instance profile will be used to authenticate to Vault. + +_Appears in:_ +- [VaultAuthSpec](#vaultauthspec) + +| Field | Description | +| --- | --- | +| `role` _string_ | Vault role to use for authenticating | +| `region` _string_ | AWS Region to use for signing the authentication request | +| `headerValue` _string_ | The Vault header value to include in the STS signing request | +| `sessionName` _string_ | The role session name to use when creating a webidentity provider | +| `stsEndpoint` _string_ | The STS endpoint to use; if not set will use the default | +| `iamEndpoint` _string_ | The IAM endpoint to use; if not set will use the default | +| `secretRef` _string_ | SecretRef is the name of a Kubernetes Secret which holds credentials for AWS. Expected keys include `access_key_id`, `secret_access_key`, `session_token` | +| `irsaServiceAccount` _string_ | IRSAServiceAccount name to use with IAM Roles for Service Accounts (IRSA), and should be annotated with "eks.amazonaws.com/role-arn". This ServiceAccount will be checked for other EKS annotations: eks.amazonaws.com/audience and eks.amazonaws.com/token-expiration | + + #### VaultAuthConfigAppRole @@ -165,7 +186,7 @@ VaultAuthList contains a list of VaultAuth | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultAuthList` | `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` _[VaultAuth](#vaultauth) array_ | | @@ -191,6 +212,7 @@ _Appears in:_ | `kubernetes` _[VaultAuthConfigKubernetes](#vaultauthconfigkubernetes)_ | Kubernetes specific auth configuration, requires that the Method be set to `kubernetes`. | | `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 | @@ -207,7 +229,7 @@ _Appears in:_ | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultConnection` | `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` _[VaultConnectionSpec](#vaultconnectionspec)_ | | @@ -223,7 +245,7 @@ VaultConnectionList contains a list of VaultConnection | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultConnectionList` | `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` _[VaultConnection](#vaultconnection) array_ | | @@ -243,7 +265,7 @@ _Appears in:_ | `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. | +| `caCertSecretRef` _string_ | CACertSecretRef is the name of a Kubernetes secret containing the trusted PEM encoded CA certificate chain as `ca.crt`. | | `skipTLSVerify` _boolean_ | SkipTLSVerify for TLS connections. | @@ -260,7 +282,7 @@ _Appears in:_ | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultDynamicSecret` | `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` _[VaultDynamicSecretSpec](#vaultdynamicsecretspec)_ | | @@ -276,7 +298,7 @@ VaultDynamicSecretList contains a list of VaultDynamicSecret | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultDynamicSecretList` | `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` _[VaultDynamicSecret](#vaultdynamicsecret) array_ | | @@ -301,6 +323,7 @@ _Appears in:_ | `params` _object (keys:string, values:string)_ | Params that can be passed when requesting credentials/secrets. When Params is set the configured RequestHTTPMethod will be ignored. See RequestHTTPMethod for more details. Please consult [secrets](/vault/docs/secrets) if you are uncertain about what 'params' should/can be set to. | | `renewalPercent` _integer_ | RenewalPercent is the percent out of 100 of the lease duration when the lease is renewed. Defaults to 67 percent plus jitter. | | `revoke` _boolean_ | Revoke the existing lease on VDS resource deletion. | +| `allowStaticCreds` _boolean_ | AllowStaticCreds should be set when syncing credentials that are periodically rotated by the Vault server, rather than created upon request. These secrets are sometimes referred to as "static roles", or "static credentials", with a request path that contains "static-creds". | | `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. | @@ -318,7 +341,7 @@ _Appears in:_ | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultPKISecret` | `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` _[VaultPKISecretSpec](#vaultpkisecretspec)_ | | @@ -334,7 +357,7 @@ VaultPKISecretList contains a list of VaultPKISecret | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultPKISecretList` | `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` _[VaultPKISecret](#vaultpkisecret) array_ | | @@ -354,7 +377,7 @@ _Appears in:_ | `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 | +| `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. | @@ -392,6 +415,22 @@ _Appears in:_ | `requestID` _string_ | RequestID of the Vault secret request. | +#### VaultStaticCredsMetaData + + + + + +_Appears in:_ +- [VaultDynamicSecretStatus](#vaultdynamicsecretstatus) + +| Field | Description | +| --- | --- | +| `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 | +| `ttl` _integer_ | TTL is the seconds remaining before the next rotation. | + + #### VaultStaticSecret @@ -403,7 +442,7 @@ _Appears in:_ | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultStaticSecret` | `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` _[VaultStaticSecretSpec](#vaultstaticsecretspec)_ | | @@ -419,7 +458,7 @@ VaultStaticSecretList contains a list of VaultStaticSecret | Field | Description | | --- | --- | -| `apiVersion` _string_ | `secrets.hashicorp.com/v1alpha1` +| `apiVersion` _string_ | `secrets.hashicorp.com/v1beta1` | `kind` _string_ | `VaultStaticSecretList` | `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` _[VaultStaticSecret](#vaultstaticsecret) array_ | | @@ -439,10 +478,14 @@ _Appears in:_ | `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 | +| `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: [kv-v2](/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 | | `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/helm.mdx b/website/content/docs/platform/k8s/vso/helm.mdx index 85b54f82b4f6..80c3aa6064d7 100644 --- a/website/content/docs/platform/k8s/vso/helm.mdx +++ b/website/content/docs/platform/k8s/vso/helm.mdx @@ -24,6 +24,7 @@ Use these links to navigate to a particular top-level stanza. - [`metricsService`](#h-metricsservice) - [`defaultVaultConnection`](#h-defaultvaultconnection) - [`defaultAuthMethod`](#h-defaultauthmethod) +- [`telemetry`](#h-telemetry) - [`tests`](#h-tests) ## All Values @@ -31,7 +32,7 @@ Use these links to navigate to a particular top-level stanza. ### 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. + This consists of a controller and a kube rbac proxy container. - `replicas` ((#v-controller-replicas)) (`integer: 1`) - Set the number of replicas for the operator. @@ -68,7 +69,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.1.0-beta`) + - `tag` ((#v-controller-manager-image-tag)) (`string: 0.1.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 @@ -94,30 +95,107 @@ Use these links to navigate to a particular top-level stanza. - `storageEncryption` ((#v-controller-manager-clientcache-storageencryption)) - StorageEncryption provides the necessary configuration to encrypt the client storage cache within Kubernetes objects using (required) Vault Transit Engine. - This should only be configured when client cache persistence with encryption is enabled. - E.g. `controller.manager.clientCache.persistenceMode=direct-encrypted` - Typically there should only ever be one VaultAuth configured with + This should only be configured when client cache persistence with encryption is enabled and + will deploy an additional VaultAuthMethod to be used by the Vault Transit Engine. + E.g. when `controller.manager.clientCache.persistenceModel=direct-encrypted` + Supported Vault authentication methods for the Transit Auth method are: jwt, approle, + and kubernetes. + Typically, there should only ever be one VaultAuth configured with StorageEncryption in the Cluster. - - `vaultConnectionRef` ((#v-controller-manager-clientcache-storageencryption-vaultconnectionref)) (`string: default`) - Vault Connection Ref to be used by the VaultAuthMethod. - Default setting will use the default VaultConnectionRef, which must also be configured. + - `enabled` ((#v-controller-manager-clientcache-storageencryption-enabled)) (`boolean: false`) - toggles the deployment of the Transit VaultAuthMethod CR. - - `namespace` ((#v-controller-manager-clientcache-storageencryption-namespace)) (`string: ""`) - Vault namespace for the VaultAuthMethod + - `vaultConnectionRef` ((#v-controller-manager-clientcache-storageencryption-vaultconnectionref)) (`string: default`) - Vault Connection Ref to be used by the Transit VaultAuthMethod. + Default setting will use the default VaultConnectionRef, which must also be configured. - `keyName` ((#v-controller-manager-clientcache-storageencryption-keyname)) (`string: ""`) - KeyName to use for encrypt/decrypt operations via Vault Transit. - - `mount` ((#v-controller-manager-clientcache-storageencryption-mount)) (`string: kubernetes`) - Mount path for the Vault Auth Method. + - `transitMount` ((#v-controller-manager-clientcache-storageencryption-transitmount)) (`string: ""`) - Mount path for the Transit VaultAuthMethod. + + - `namespace` ((#v-controller-manager-clientcache-storageencryption-namespace)) (`string: ""`) - Vault namespace for the Transit VaultAuthMethod CR. + + - `method` ((#v-controller-manager-clientcache-storageencryption-method)) (`string: kubernetes`) - Vault Auth method to be used with the Transit VaultAuthMethod CR. + + - `mount` ((#v-controller-manager-clientcache-storageencryption-mount)) (`string: kubernetes`) - Mount path for the Transit VaultAuthMethod. + + - `kubernetes` ((#v-controller-manager-clientcache-storageencryption-kubernetes)) - Vault Kubernetes auth method specific configuration + + - `role` ((#v-controller-manager-clientcache-storageencryption-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-controller-manager-clientcache-storageencryption-kubernetes-serviceaccount)) (`string: ""`) - Kubernetes ServiceAccount associated with the Transit Vault Auth Role + Defaults to using the Operator's service-account. + + - `tokenAudiences` ((#v-controller-manager-clientcache-storageencryption-kubernetes-tokenaudiences)) (`array: []`) - Token Audience should match the audience of the vault kubernetes auth role. + + - `jwt` ((#v-controller-manager-clientcache-storageencryption-jwt)) - Vault JWT auth method specific configuration + + - `role` ((#v-controller-manager-clientcache-storageencryption-jwt-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 using JWT for the Transit VaultAuthMethod. + + - `secretName` ((#v-controller-manager-clientcache-storageencryption-jwt-secretname)) (`string: ""`) - One of the following is required prior to deploying the helm chart + - K8s secret that contains the JWT + - K8s service account if a service account JWT is used as a Vault JWT auth token and + needs generating by VSO. + + Name of Kubernetes Secret that has the Vault JWT auth token. + The Kubernetes Secret must contain a key named `jwt` which references the JWT token, and + must exist in the namespace of any consuming VaultSecret CR. This is a required field if + a JWT token is provided. + + - `serviceAccount` ((#v-controller-manager-clientcache-storageencryption-jwt-serviceaccount)) (`string: default`) - Kubernetes ServiceAccount to generate a service account JWT - - `role` ((#v-controller-manager-clientcache-storageencryption-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` + - `tokenAudiences` ((#v-controller-manager-clientcache-storageencryption-jwt-tokenaudiences)) (`array: []`) - Token Audience should match the bound_audiences or the `aud` list in bound_claims if + applicable of the Vault JWT auth role. - - `serviceAccount` ((#v-controller-manager-clientcache-storageencryption-serviceaccount)) (`string: ""`) - Kubernetes ServiceAccount associated with the default Vault Auth Role - default: Operator's ServiceAccount + - `appRole` ((#v-controller-manager-clientcache-storageencryption-approle)) - AppRole auth method specific configuration - - `tokenAudiences` ((#v-controller-manager-clientcache-storageencryption-tokenaudiences)) (`array: []`) - Token Audience should match the audience of the vault kubernetes auth role. + - `roleId` ((#v-controller-manager-clientcache-storageencryption-approle-roleid)) (`string: ""`) - AppRole Role's RoleID to use for authenticating to Vault. + This is a required field when using appRole and must be setup in Vault prior to deploying + the helm chart. - - `transitMount` ((#v-controller-manager-clientcache-storageencryption-transitmount)) (`string: ""`) - Mount path for the Transit Method. + - `secretName` ((#v-controller-manager-clientcache-storageencryption-approle-secretname)) (`string: ""`) - Name of Kubernetes Secret that has the AppRole Role's SecretID used to authenticate with + Vault. The Kubernetes Secret must contain a key named `id` which references the AppRole + Role's SecretID, and must exist in the namespace of any consuming VaultSecret CR. + This is a required field when using appRole and must be setup in Vault prior to + deploying the helm chart. + + - `aws` ((#v-controller-manager-clientcache-storageencryption-aws)) - AWS auth method specific configuration + + - `role` ((#v-controller-manager-clientcache-storageencryption-aws-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 using the AWS for the Transit auth method. + + - `region` ((#v-controller-manager-clientcache-storageencryption-aws-region)) (`string: ""`) - AWS region to use for signing the authentication request + Optional, but most commonly will be the EKS cluster region. + + - `headerValue` ((#v-controller-manager-clientcache-storageencryption-aws-headervalue)) (`string: ""`) - Vault header value to include in the STS signing request + + - `sessionName` ((#v-controller-manager-clientcache-storageencryption-aws-sessionname)) (`string: ""`) - The role session name to use when creating a WebIdentity provider + + - `stsEndpoint` ((#v-controller-manager-clientcache-storageencryption-aws-stsendpoint)) (`string: ""`) - The STS endpoint to use; if not set will use the default + + - `iamEndpoint` ((#v-controller-manager-clientcache-storageencryption-aws-iamendpoint)) (`string: ""`) - The IAM endpoint to use; if not set will use the default + + - `secretRef` ((#v-controller-manager-clientcache-storageencryption-aws-secretref)) (`string: ""`) - The name of a Kubernetes Secret which holds credentials for AWS. Supported keys + include `access_key_id`, `secret_access_key`, `session_token` + + - `irsaServiceAccount` ((#v-controller-manager-clientcache-storageencryption-aws-irsaserviceaccount)) (`string: ""`) - Name of a Kubernetes service account that is configured with IAM Roles + for Service Accounts (IRSA). Should be annotated with "eks.amazonaws.com/role-arn". + + - `params` ((#v-controller-manager-clientcache-storageencryption-params)) (`map`) - Params to use when authenticating to Vault using this auth method. + params: + vault-something1: "foo" + vault-something2: "bar" + vault-something3: "baz" + + - `headers` ((#v-controller-manager-clientcache-storageencryption-headers)) (` map: ""`) - Headers to be included in all Vault requests. + headers: + vault-something1: "foo" + vault-something2: "bar" + vault-something3: "baz" - `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. @@ -198,7 +276,7 @@ Use these links to navigate to a particular top-level stanza. - `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. + - `caCertSecret` ((#v-defaultvaultconnection-cacertsecret)) (`string: ""`) - CACertSecret is the name of a Kubernetes secret containing the trusted PEM encoded CA certificate chain as `ca.crt`. 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. @@ -242,7 +320,7 @@ Use these links to navigate to a particular top-level stanza. - `role` ((#v-defaultauthmethod-jwt-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 `jwtAuthMethod.enabled=true` + if using the JWT for the default auth method. - `secretName` ((#v-defaultauthmethod-jwt-secretname)) (`string: ""`) - One of the following is required prior to deploying the helm chart - K8s secret that contains the JWT @@ -269,17 +347,74 @@ Use these links to navigate to a particular top-level stanza. This is a required field when using appRole and must be setup in Vault prior to deploying the helm chart. - - `params` ((#v-defaultauthmethod-params)) (`string: ""`) - Params to use when authenticating to Vault - params: | - "vault-something1": "foo" - "vault-something2": "bar" - "vault-something3": "baz" + - `aws` ((#v-defaultauthmethod-aws)) - AWS auth method specific configuration - - `headers` ((#v-defaultauthmethod-headers)) (`string: ""`) - Headers to be included in all Vault requests. - headers: | - "vault-something1": "foo" - "vault-something2": "bar" - "vault-something3": "baz" + - `role` ((#v-defaultauthmethod-aws-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 using the AWS for the default auth method. + + - `region` ((#v-defaultauthmethod-aws-region)) (`string: ""`) - AWS region to use for signing the authentication request + Optional, but most commonly will be the region where the EKS cluster is running + + - `headerValue` ((#v-defaultauthmethod-aws-headervalue)) (`string: ""`) - Vault header value to include in the STS signing request + + - `sessionName` ((#v-defaultauthmethod-aws-sessionname)) (`string: ""`) - The role session name to use when creating a WebIdentity provider + + - `stsEndpoint` ((#v-defaultauthmethod-aws-stsendpoint)) (`string: ""`) - The STS endpoint to use; if not set will use the default + + - `iamEndpoint` ((#v-defaultauthmethod-aws-iamendpoint)) (`string: ""`) - The IAM endpoint to use; if not set will use the default + + - `secretRef` ((#v-defaultauthmethod-aws-secretref)) (`string: ""`) - The name of a Kubernetes Secret which holds credentials for AWS. Supported keys include + `access_key_id`, `secret_access_key`, `session_token` + + - `irsaServiceAccount` ((#v-defaultauthmethod-aws-irsaserviceaccount)) (`string: ""`) - Name of a Kubernetes service account that is configured with IAM Roles + for Service Accounts (IRSA). Should be annotated with "eks.amazonaws.com/role-arn". + + - `params` ((#v-defaultauthmethod-params)) (`map`) - Params to use when authenticating to Vault + params: + vault-something1: "foo" + vault-something2: "bar" + vault-something3: "baz" + + - `headers` ((#v-defaultauthmethod-headers)) (`map`) - Headers to be included in all Vault requests. + headers: + vault-something1: "foo" + vault-something2: "bar" + vault-something3: "baz" + +### telemetry ((#h-telemetry)) + +- `telemetry` ((#v-telemetry)) - Configures a Prometheus ServiceMonitor + + - `serviceMonitor` ((#v-telemetry-servicemonitor)) + + - `enabled` ((#v-telemetry-servicemonitor-enabled)) (`boolean: false`) - The Prometheus operator *must* be installed before enabling this feature, + if not the chart will fail to install due to missing CustomResourceDefinitions + provided by the operator. + + Instructions on how to install the Helm chart can be found here: + https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack + More information can be found here: + https://github.com/prometheus-operator/prometheus-operator + https://github.com/prometheus-operator/kube-prometheus + + Enable deployment of the Vault Secrets Operator ServiceMonitor CustomResource. + + - `selectors` ((#v-telemetry-servicemonitor-selectors)) (`string: ""`) - Selector labels to add to the ServiceMonitor. + When empty, defaults to: + release: prometheus + + - `scheme` ((#v-telemetry-servicemonitor-scheme)) (`string: https`) - Scheme of the service Prometheus scrapes metrics from. This must match the scheme of the metrics service of VSO + + - `port` ((#v-telemetry-servicemonitor-port)) (`string: https`) - Port at which Prometheus scrapes metrics. This must match the port of the metrics service of VSO + + - `path` ((#v-telemetry-servicemonitor-path)) (`string: /metrics`) - Path at which Prometheus scrapes metrics + + - `bearerTokenFile` ((#v-telemetry-servicemonitor-bearertokenfile)) (`string: /var/run/secrets/kubernetes.io/serviceaccount/token`) - File Prometheus reads bearer token from for scraping metrics + + - `interval` ((#v-telemetry-servicemonitor-interval)) (`string: 30s`) - Interval at which Prometheus scrapes metrics + + - `scrapeTimeout` ((#v-telemetry-servicemonitor-scrapetimeout)) (`string: 10s`) - Timeout for Prometheus scrapes ### tests ((#h-tests)) diff --git a/website/content/docs/platform/k8s/vso/index.mdx b/website/content/docs/platform/k8s/vso/index.mdx index 672adf614278..6b0e84192e6f 100644 --- a/website/content/docs/platform/k8s/vso/index.mdx +++ b/website/content/docs/platform/k8s/vso/index.mdx @@ -49,7 +49,7 @@ Provides the configuration necessary for the Operator to connect to a single Vau ```yaml --- -apiVersion: secrets.hashicorp.com/v1alpha1 +apiVersion: secrets.hashicorp.com/v1beta1 kind: VaultConnection metadata: namespace: vso-example @@ -77,7 +77,7 @@ specified in a `VaultConnection` Custom Resource. ```yaml --- -apiVersion: secrets.hashicorp.com/v1alpha1 +apiVersion: secrets.hashicorp.com/v1beta1 kind: VaultAuth metadata: namespace: vso-example @@ -119,9 +119,35 @@ Each supported CRD is specialized to a *class* of Vault secret, documented below 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) +##### 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/v1alpha1 +apiVersion: secrets.hashicorp.com/v1beta1 kind: VaultStaticSecret metadata: namespace: vso-example @@ -130,20 +156,23 @@ spec: vaultAuthRef: example mount: kvv2 type: kv-v2 - name: secret + path: eng/apikey/google + version: 2 refreshAfter: 60s destination: create: true - name: static-secret1 + 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.
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/v1alpha1 +apiVersion: secrets.hashicorp.com/v1beta1 kind: VaultPKISecret metadata: namespace: vso-example @@ -151,7 +180,7 @@ metadata: spec: vaultAuthRef: example mount: pki - name: default + role: default commonName: example.com format: pem expiryOffset: 1s @@ -168,9 +197,13 @@ Provides the configuration necessary for the Operator to synchronize a single Va 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/v1alpha1 +apiVersion: secrets.hashicorp.com/v1beta1 kind: VaultDynamicSecret metadata: namespace: vso-example @@ -178,8 +211,48 @@ metadata: spec: vaultAuthRef: example mount: db - role: postgres + 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 +``` diff --git a/website/content/docs/platform/k8s/vso/installation.mdx b/website/content/docs/platform/k8s/vso/installation.mdx index 546e3847b7ab..8d44a9f98c2d 100644 --- a/website/content/docs/platform/k8s/vso/installation.mdx +++ b/website/content/docs/platform/k8s/vso/installation.mdx @@ -28,13 +28,13 @@ $ helm repo add hashicorp https://helm.releases.hashicorp.com $ helm search repo hashicorp/vault-secrets-operator --devel NAME CHART VERSION APP VERSION DESCRIPTION -hashicorp/vault-secrets-operator 0.1.0-beta 0.1.0-beta Official HashiCorp Vault Secrets Operator Chart +hashicorp/vault-secrets-operator 0.1.0-rc.1 0.1.0-rc.1 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-beta +$ helm install --create-namespace --namespace vault-secrets-operator vault-secrets-operator hashicorp/vault-secrets-operator --version 0.1.0-rc.1 ```