-
Notifications
You must be signed in to change notification settings - Fork 4.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add CSI documentation (#11203)
* docs: add CSI documentation * Fix typos * Improvements * Improvements * Update website/content/docs/platform/k8s/csi/installation.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/configurations.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/configurations.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <[email protected]> * review feedback * Fix typo * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <[email protected]> Co-authored-by: Tom Proctor <[email protected]>
- Loading branch information
1 parent
64ef848
commit 275bfb9
Showing
5 changed files
with
393 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: Vault CSI Provider Configurations | ||
| sidebar_title: Configurations | ||
| description: This section documents the configurables for the Vault CSI Provider. | ||
| --- | ||
|
|
||
| # Secret Class Provider Configurations | ||
|
|
||
| The following parameters are supported by the Vault provider: | ||
|
|
||
| - `roleName` `(string: "")` - Name of the role to be used during login with Vault. | ||
|
|
||
| - `vaultAddress` `(string: "")` - The address of the Vault server. | ||
|
|
||
| - `vaultSkipTLSVerify` `(string: "false")` - When set to true, skips verification of the Vault server | ||
| certificiate. Setting this to true is not recommended for production. | ||
|
|
||
| - `vaultCACertPath` `(string: "")` - The path on disk where the Vault CA certificate can be found | ||
| when verifying the Vault server certificate. | ||
|
|
||
| - `vaultTLSClientCertPath` `(string: "")` - The path on disk where the client certificate can be found | ||
| for mTLS communications with Vault. | ||
|
|
||
| - `vaultTLSClientKeyPath` `(string: "")` - The path on disk where the client key can be found | ||
| for mTLS communications with Vault. | ||
|
|
||
| - `vaultTLSServerName` `(string: "")` - The name to use as the SNI host when connecting via TLS. | ||
|
|
||
| - `objects` `(array)` - An array of secrets to retrieve from Vault. | ||
|
|
||
| - `objectName` `(string: "")` - The alias of the object which can be referenced within the secret provider class and | ||
| the name of the secret file. | ||
|
|
||
| - `method` `(string: "GET")` - The type of HTTP request. Supported values include "GET" and "PUT". | ||
|
|
||
| - `secretPath` `(string: "")` - The path in Vault where the secret is located. | ||
|
|
||
| - `secretArgs` `(map: {})` - Additional arguments to be sent to Vault for a specific secret. Arguments can vary | ||
| for different secret engines. For example: | ||
|
|
||
| ```yaml | ||
| secretArgs: | ||
| common_name: "test.example.com" | ||
| ttl: "24h" | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,170 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: Vault CSI Provider Examples | ||
| sidebar_title: Examples | ||
| description: This section documents examples of using the Vault CSI Provider. | ||
| --- | ||
|
|
||
| # Vault CSI Provider Examples | ||
|
|
||
| The following examples demonstrate how the Vault CSI Provider can be used. | ||
|
|
||
| ~> A common mistake is to not install the CSI Secret Store Driver before using the Vault CSI Provider. | ||
|
|
||
| ## File Based Dynamic Database Credentials | ||
|
|
||
| The following Secret Provider Class retrieves dynamic database credentials from Vault and | ||
| extracts the generated username and password. The secrets are then mounted as files in the | ||
| configured mount location. | ||
|
|
||
| ```yaml | ||
| --- | ||
| apiVersion: secrets-store.csi.x-k8s.io/v1alpha1 | ||
| kind: SecretProviderClass | ||
| metadata: | ||
| name: vault-db-creds | ||
| spec: | ||
| provider: vault | ||
| parameters: | ||
| roleName: "app" | ||
| vaultAddress: "https://vault.vault:8200" | ||
| vaultCACertPath: "/vault/tls/ca.crt" | ||
| objects: | | ||
| - objectName: "dbUsername" | ||
| secretPath: "database/creds/db-app" | ||
| secretKey: "username" | ||
| - objectName: "dbPassword" | ||
| secretPath: "database/creds/db-app" | ||
| secretKey: "password" | ||
| ``` | ||
| Next, a pod can be created to use this Secret Provider Class to populate the secrets in the pod: | ||
| ```yaml | ||
| apiVersion: apps/v1 | ||
| kind: Deployment | ||
| metadata: | ||
| name: app | ||
| labels: | ||
| app: demo | ||
| spec: | ||
| selector: | ||
| matchLabels: | ||
| app: demo | ||
| replicas: 1 | ||
| template: | ||
| metadata: | ||
| annotations: | ||
| labels: | ||
| app: demo | ||
| spec: | ||
| serviceAccountName: app | ||
| containers: | ||
| - name: app | ||
| image: my-app:1.0.0 | ||
| volumeMounts: | ||
| - name: "vault-db-creds" | ||
| mountPath: "/mnt/secrets-store" | ||
| readOnly: true | ||
| volumes: | ||
| - name: vault-db-creds | ||
| csi: | ||
| driver: "secrets-store.csi.k8s.io" | ||
| readOnly: true | ||
| volumeAttributes: | ||
| secretProviderClass: "vault-db-creds" | ||
| ``` | ||
| The pod mounts a CSI volume and specifies the Secret Provider Class (`vault-db-creds`) created above. | ||
| The secrets created from that provider class are mounted to `/mnt/secrets-store`. When this pod is | ||
| created the containers will find two files containing secrets: | ||
|
|
||
| * `/mnt/secrets-store/dbUsername` | ||
| * `/mnt/secrets-store/dbPassword` | ||
|
|
||
| ## Environment Variable Dynamic Database Credentials | ||
|
|
||
| The following Secret Provider Class retrieves dynamic database credentials from Vault and | ||
| extracts the generated username and password. The secrets are then synced to Kubernetes secrets | ||
| so that they can be mounted as environment variables in the containers. | ||
|
|
||
| ```yaml | ||
| --- | ||
| apiVersion: secrets-store.csi.x-k8s.io/v1alpha1 | ||
| kind: SecretProviderClass | ||
| metadata: | ||
| name: vault-db-creds | ||
| spec: | ||
| provider: vault | ||
| secretObjects: | ||
| - secretName: vault-db-creds-secret | ||
| type: Opaque | ||
| data: | ||
| - objectName: dbUsername # References dbUsername below | ||
| key: username # Key within k8s secret for this value | ||
| - objectName: dbPassword | ||
| key: password | ||
| parameters: | ||
| roleName: "app" | ||
| vaultAddress: "https://vault.vault:8200" | ||
| vaultCACertPath: "/vault/tls/ca.crt" | ||
| objects: | | ||
| - objectName: "dbUsername" | ||
| secretPath: "database/creds/db-app" | ||
| secretKey: "username" | ||
| - objectName: "dbPassword" | ||
| secretPath: "database/creds/db-app" | ||
| secretKey: "password" | ||
| ``` | ||
|
|
||
| Next, a pod can be created which uses this Secret Provider Class to populate the secrets in the pod's environment: | ||
|
|
||
| ```yaml | ||
| apiVersion: apps/v1 | ||
| kind: Deployment | ||
| metadata: | ||
| name: app | ||
| labels: | ||
| app: demo | ||
| spec: | ||
| selector: | ||
| matchLabels: | ||
| app: demo | ||
| replicas: 1 | ||
| template: | ||
| metadata: | ||
| annotations: | ||
| labels: | ||
| app: demo | ||
| spec: | ||
| serviceAccountName: app | ||
| containers: | ||
| - name: app | ||
| image: my-app:1.0.0 | ||
| envs: | ||
| - name: DB_USERNAME | ||
| valueFrom: | ||
| secretKeyRef: | ||
| name: vault-db-creds-secret | ||
| key: username | ||
| - name: DB_PASSWORD | ||
| valueFrom: | ||
| secretKeyRef: | ||
| name: vault-db-creds-secret | ||
| key: password | ||
| volumeMounts: | ||
| - name: "vault-db-creds" | ||
| mountPath: "/mnt/secrets-store" | ||
| readOnly: true | ||
| volumes: | ||
| - name: vault-db-creds | ||
| csi: | ||
| driver: "secrets-store.csi.k8s.io" | ||
| readOnly: true | ||
| volumeAttributes: | ||
| secretProviderClass: "vault-db-creds" | ||
| ``` | ||
|
|
||
| The pod mounts a CSI volume and specifies the Secret Provider Class (`vault-db-creds`) created above. | ||
| The secrets created from that provider class are mounted to `/mnt/secrets-store`, additionally a Kubernetes | ||
| secret called `vault-db-creds` is created and referenced in two environment variables. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: Vault CSI Provider | ||
| sidebar_title: Vault CSI Provider | ||
| description: >- | ||
| The Vault CSI Provider allows pods to consume Vault secrets using CSI volumes. | ||
| --- | ||
|
|
||
| # Vault CSI Provider | ||
|
|
||
| The Vault CSI Provider allows pods to consume Vault secrets using | ||
| [CSI Secrets Store](https://github.com/kubernetes-sigs/secrets-store-csi-driver) volumes. | ||
|
|
||
| ~> The Vault CSI Provider requires the [CSI Secret Store](https://github.com/kubernetes-sigs/secrets-store-csi-driver) | ||
| Driver to be installed. | ||
|
|
||
| ## Overview | ||
|
|
||
| At a high level, the CSI Secrets Store driver allows users to create `SecretProviderClass` objects. | ||
| This object defines which secret provider to use and what secrets to retrieve. When pods requesting CSI volumes | ||
| are created, the CSI Secrets Store driver will send the request to the Vault CSI Provider if the provider | ||
| is `vault`. The Vault CSI Provider will then use Secret Class Provider specified and the pod's service account to retrieve | ||
| the secrets from Vault, and <span class="x x-first x-last">mount</span> them <span class="x x-first x-last">into</span> the pod<span class="x x-first x-last">'s CSI</span> volume. | ||
|
|
||
| The secret is retrieved from Vault and populated to the CSI secrets store volume during the `ContainerCreation` phase. | ||
| This means that pods will be blocked from starting until the secrets have been read from Vault and written to the volume. | ||
|
|
||
| ### Features | ||
|
|
||
| The following features are supported by the Vault CSI Provider: | ||
|
|
||
| * All Vault secret engines supported. | ||
| * Authenticatation using the requesting pod's service account. | ||
| * TLS/mTLS communciations with Vault. | ||
| * Rendering Vault secrets to files. | ||
| * Syncing secrets to Kubernetes secrets to be used as environment variables. | ||
| * Installation via [Vault Helm](/docs/platform/k8s/helm) | ||
|
|
||
| ## Authenticating with Vault | ||
|
|
||
| The primary method of authentication with Vault when using the Vault CSI Provider | ||
| is the service account attached to the pod. At this time no other authentication methods | ||
| are supported. | ||
|
|
||
| For [Kubernetes authentication](/docs/auth/kubernetes), the service account must be bound to a Vault role and a | ||
| policy granting access to the secrets desired. | ||
|
|
||
| A service account must be present to use the Vault CSI Provider with the Kubernetes | ||
| authentication method. It is _not_ recommended to bind Vault roles to the default service | ||
| account provided to pods if no service account is defined. | ||
|
|
||
| ## Secret Provider Class Example | ||
|
|
||
| The following is an example of a Secret Provider Class using the `vault` provider: | ||
|
|
||
| ```yaml | ||
| --- | ||
| apiVersion: secrets-store.csi.x-k8s.io/v1alpha1 | ||
| kind: SecretProviderClass | ||
| metadata: | ||
| name: vault-db-creds | ||
| spec: | ||
| # Vault CSI Provider | ||
| provider: vault | ||
| parameters: | ||
| # Vault role name to use during login | ||
| roleName: "app" | ||
| # Vault's hostname | ||
| vaultAddress: "https://vault:8200" | ||
| # TLS CA certification for validation | ||
| vaultCACertPath: "/vault/tls/ca.crt" | ||
| objects: | | ||
| - objectName: "dbUsername" | ||
| secretPath: "database/creds/db-app" | ||
| secretKey: "username" | ||
| - objectName: "dbPassword" | ||
| secretPath: "database/creds/db-app" | ||
| secretKey: "password" | ||
| # "objectName" is an alias used within the SecretProviderClass to reference | ||
| # that specific secret. This will also be the filename containing the secret. | ||
| # "secretPath" is the path in Vault where the secret should be retrieved. | ||
| # "secretKey" is the key within the Vault secret response to extract a value from. | ||
| ``` | ||
|
|
||
| ~> Secret Provider Class is a namespaced object in Kubernetes. | ||
|
|
||
| ## Using Secret Provider Classes | ||
|
|
||
| An application pod uses the example Secret Provider Class above by mounting it as a CSI volume: | ||
|
|
||
| ```yaml | ||
| --- | ||
| apiVersion: apps/v1 | ||
| kind: Deployment | ||
| metadata: | ||
| name: app | ||
| labels: | ||
| app: demo | ||
| spec: | ||
| selector: | ||
| matchLabels: | ||
| app: demo | ||
| replicas: 1 | ||
| template: | ||
| spec: | ||
| serviceAccountName: app | ||
| containers: | ||
| - name: app | ||
| image: my-app:1.0.0 | ||
| volumeMounts: | ||
| - name: "vault-db-creds" | ||
| mountPath: "/mnt/secrets-store" | ||
| readOnly: true | ||
| volumes: | ||
| - name: vault-db-creds | ||
| csi: | ||
| driver: "secrets-store.csi.k8s.io" | ||
| readOnly: true | ||
| volumeAttributes: | ||
| secretProviderClass: "vault-db-creds" | ||
| ``` | ||
| In this example `volumes.csi` is created on the application deployment and references | ||
| the Secret Provider Class named `vault-db-creds`. | ||
|
|
||
| ## Learn | ||
|
|
||
| Refer to the [Vault CSI Provider](https://learn.hashicorp.com/tutorials/vault/kubernetes-secret-store-driver?in=vault/kubernetes) | ||
| guide for a step-by-step tutorial. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| --- | ||
| layout: docs | ||
| page_title: Vault CSI Provider Installation | ||
| sidebar_title: Installation | ||
| description: The Vault CSI Provider can be installed using Vault Helm. | ||
| --- | ||
|
|
||
| # Installing the Vault CSI Provider | ||
|
|
||
| ~> The Vault CSI Provider requires the [CSI Secret Store Driver](https://github.com/kubernetes-sigs/secrets-store-csi-driver). | ||
|
|
||
| The [Vault Helm chart](/docs/platform/k8s/helm) is the recommended way to | ||
| install and configure the Vault CSI Provider in Kubernetes. | ||
|
|
||
| To install a new instance of Vault and the Vault CSI Provider, first add the | ||
| HashiCorp helm repository and ensure you have access to the chart: | ||
|
|
||
| ~> Vault CSI Provider Helm installation requires Vault Helm 0.10.0+. | ||
|
|
||
| ```shell-session | ||
| $ helm repo add hashicorp https://helm.releases.hashicorp.com | ||
| "hashicorp" has been added to your repositories | ||
| $ helm search repo hashicorp/vault | ||
| NAME CHART VERSION APP VERSION DESCRIPTION | ||
| hashicorp/vault 0.10.0 1.7.0 Official HashiCorp Vault Chart | ||
| ``` | ||
|
|
||
| Then install the chart and enable the CSI feature by setting the | ||
| `csi.enabled` value to `true`: | ||
|
|
||
| ```bash | ||
| # Note: this will also install the Vault server and Agent Injector. | ||
| helm install vault hashicorp/vault --set="csi.enabled=true" | ||
| ``` | ||
|
|
||
| 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. | ||
|
|
||
| You can see all the available values settings by running `helm inspect values hashicorp/vault` or by reading the [Vault Helm Configuration | ||
| Docs](/docs/platform/k8s/helm/configuration). Commonly used values in the Helm | ||
| chart include limiting the namespaces the Vault CSI Provider runs in, TLS options and | ||
| more. |
Oops, something went wrong.