From 6a92a8bd78a14671afb0835954e06144d1eafb69 Mon Sep 17 00:00:00 2001 From: Jason O'Donnell <2160810+jasonodonnell@users.noreply.github.com> Date: Fri, 26 Mar 2021 11:08:55 -0400 Subject: [PATCH] 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 * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/configurations.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/configurations.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor * review feedback * Fix typo * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor Co-authored-by: Tom Proctor --- .../docs/platform/k8s/csi/configurations.mdx | 46 +++++ .../docs/platform/k8s/csi/examples.mdx | 170 ++++++++++++++++++ .../content/docs/platform/k8s/csi/index.mdx | 129 +++++++++++++ .../docs/platform/k8s/csi/installation.mdx | 44 +++++ website/data/docs-navigation.js | 4 + 5 files changed, 393 insertions(+) create mode 100644 website/content/docs/platform/k8s/csi/configurations.mdx create mode 100644 website/content/docs/platform/k8s/csi/examples.mdx create mode 100644 website/content/docs/platform/k8s/csi/index.mdx create mode 100644 website/content/docs/platform/k8s/csi/installation.mdx diff --git a/website/content/docs/platform/k8s/csi/configurations.mdx b/website/content/docs/platform/k8s/csi/configurations.mdx new file mode 100644 index 000000000..164a54dee --- /dev/null +++ b/website/content/docs/platform/k8s/csi/configurations.mdx @@ -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" + ``` diff --git a/website/content/docs/platform/k8s/csi/examples.mdx b/website/content/docs/platform/k8s/csi/examples.mdx new file mode 100644 index 000000000..c9741f970 --- /dev/null +++ b/website/content/docs/platform/k8s/csi/examples.mdx @@ -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. diff --git a/website/content/docs/platform/k8s/csi/index.mdx b/website/content/docs/platform/k8s/csi/index.mdx new file mode 100644 index 000000000..7e54b6a0e --- /dev/null +++ b/website/content/docs/platform/k8s/csi/index.mdx @@ -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 mount them into the pod's CSI 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. diff --git a/website/content/docs/platform/k8s/csi/installation.mdx b/website/content/docs/platform/k8s/csi/installation.mdx new file mode 100644 index 000000000..e5c5a21e6 --- /dev/null +++ b/website/content/docs/platform/k8s/csi/installation.mdx @@ -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. diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 2f8399832..f4c93ade7 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -347,6 +347,10 @@ export default [ category: 'injector', content: ['annotations', 'installation', 'examples'], }, + { + category: 'csi', + content: ['configurations', 'examples', 'installation'], + }, ], }, {