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 <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/configurations.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/configurations.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/examples.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * review feedback * Fix typo * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> * Update website/content/docs/platform/k8s/csi/index.mdx Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com>
This commit is contained in:
Jason O'Donnell
GitHub
parent
1a3556b2c8
commit
6a92a8bd78
|
|
@ -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"
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -347,6 +347,10 @@ export default [
|
|||
category: 'injector',
|
||||
content: ['annotations', 'installation', 'examples'],
|
||||
},
|
||||
{
|
||||
category: 'csi',
|
||||
content: ['configurations', 'examples', 'installation'],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in New Issue