Skip to content

Commit

Permalink
Merge pull request #1301 from SgtCoDFish/csidriver
Browse files Browse the repository at this point in the history 
Update csi-driver project page
  • Loading branch information
@jetstack-bot
jetstack-bot authored Sep 20, 2023
2 parents a1acac7 + 421f5f5 commit 4f73bfe
Showing 1 changed file with 57 additions and 69 deletions.
126 changes: 57 additions & 69 deletions content/docs/projects/csi-driver.md
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,36 @@
---
title: csi-driver
description: ''
description: 'Mounting cert-manager certificates without secrets'
---

csi-driver is a Container Storage Interface (CSI) driver plugin for Kubernetes
to work along cert-manager. The goal for this plugin is to seamlessly request
and mount certificate key pairs to pods. This is useful for facilitating mTLS,
or otherwise securing connections of pods with guaranteed present certificates
whilst having all of the features that cert-manager provides.

## Why a CSI Driver?

- Ensure private keys never leave the node and are never sent over the network.
All private keys are stored locally on the node.
- Unique key and certificate per application replica with a grantee to be
present on application run time.
- Reduce resource management overhead by defining certificate request spec
in-line of the Kubernetes Pod template.
- Automatic renewal of certificates based on expiry of each individual
certificate.
- Keys and certificates are destroyed during application termination.
- Scope for extending plugin behavior with visibility on each replica's
certificate request and termination.

## Requirements and Installation

This CSI driver plugin makes use of the 'CSI inline volume' feature - Alpha as
of `v1.15` and beta in `v1.16`. Kubernetes versions `v1.16` and higher require
no extra configuration however `v1.15` requires the following feature gate set:
```
--feature-gates=CSIInlineVolume=true
```
csi-driver is a [Container Storage Interface (CSI)](https://kubernetes-csi.github.io/docs/) driver plugin for Kubernetes
which works alongside cert-manager.

Pods which mount the cert-manager csi-driver will request certificates from cert-manager
without needing a `Certificate` resource to be created. These certificates will be mounted
directly into the pod, with no intermediate Secret being created.

## Why use csi-driver?

- Ensure private keys never leave the node and are never sent over the network. Private keys are stored in memory, and shouldn't be written to disk.
- Unique key and certificate per application replica
- Fewer `Certificate` resources means writing less YAML
- Keys and certificates are destroyed when an application terminates
- No `Secret` resources needed for storing the certificate means less RBAC
- Great for ephemeral, short-lived certificates which don't need to survive a restart (e.g. certificates for mTLS)

You must have a working installation of cert-manager present on the cluster.
Instructions on how to install cert-manager can be found
[on cert-manager.io](../installation/README.md).
## Why _not_ use csi-driver?

To install the csi-driver, use helm install:
- If you need certificates to be persisted through a node restart
- If you need the same certificate to be shared by multiple components

## Installation

You must have a working installation of cert-manager present on your cluster and be running at least Kubernetes `v1.16`.

Instructions on how to install cert-manager can be found [on this website](../installation/README.md).

To install csi-driver, use helm:

```terminal
helm repo add jetstack https://charts.jetstack.io --force-update
Expand All @@ -55,7 +49,7 @@ You can verify the installation has completed correctly by checking the presence
of the CSIDriver resource as well as a CSINode resource present for each node,
referencing `csi.cert-manager.io`.

```
```terminal
$ kubectl get csidrivers
NAME CREATED AT
csi.cert-manager.io 2019-09-06T16:55:19Z
Expand All @@ -80,17 +74,15 @@ items:
...
```

The CSI driver is now installed and is ready to be used for pods in the cluster.

## Requesting and Mounting Certificates

To request certificates from cert-manager, simply define a volume mount where
the key and certificate will be written to, along with a volume with attributes
that define the cert-manager request. The following is a dummy app that mounts a
key certificate pair to `/tls` and has been signed by the `ca-issuer` with a DNS
name valid for `my-service.sandbox.svc.cluster.local`.
Requesting a certificate using csi-driver means mounting a volume, with some attributes
set to define exactly what you need to request.

```
The following example is a dummy app that mounts a key certificate pair to `/tls`, signed using
a cert-manager issuer called `ca-issuer` with a DNS name valid for `my-service.sandbox.svc.cluster.local`.

```yaml
apiVersion: v1
kind: Pod
metadata:
Expand All @@ -115,25 +107,21 @@ spec:
csi.cert-manager.io/dns-names: ${POD_NAME}.${POD_NAMESPACE}.svc.cluster.local
```
Once created, the CSI driver will generate a private key locally, request a
certificate from cert-manager based on the given attributes, then store both
locally to be mounted to the pod. The pod will remain in a pending state until
this process has been completed.
Once created, the CSI driver will generate a private key locally (for the pod), request a
certificate from cert-manager based on the given attributes, and store the certificate ready for the pod to use.
For more information on how to set up issuers for your cluster, refer to the
cert-manager documentation
[here](../configuration/README.md). **Note** it is not
possible to use `SelfSigned` Issuers with the CSI Driver. In order for
cert-manager to self sign a certificate, it needs access to the secret
containing the private key that signed the certificate request to sign the end
certificate. This secret is not used and so not available in the CSI driver use
case.
The pod will remain in a pending state until issuance has been completed.
For more information on how to set up issuers for your cluster, refer to the cert-manager documentation
[here](../configuration/README.md).
**Note** it is not possible to use `SelfSigned` Issuers with csi-driver because `SelfSigned` issuers are a
special case.

## Supported Volume Attributes

The csi-driver driver aims to have complete feature parity with all possible
values available through the cert-manager API however currently supports the
following values;
values available through the cert-manager API. It currently supports the following values:

| Attribute | Description | Default | Example |
|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|----------------------------------|
Expand Down Expand Up @@ -164,17 +152,17 @@ The following attributes support variables that are evaluated when a request is
made for the mounting Pod. These variables are useful for constructing requests
with SANs that contain values from the mounting Pod.

```
`csi.cert-manager.io/common-name`
`csi.cert-manager.io/dns-names`
`csi.cert-manager.io/uri-sans`
```text
csi.cert-manager.io/common-name
csi.cert-manager.io/dns-names
csi.cert-manager.io/uri-sans
```

Variables follow the [go `os.Expand`](https://pkg.go.dev/os#Expand) structure,
which is generally what you would expect on a UNIX shell. The CSI driver has
access to the following variables:

```
```text
${POD_NAME}
${POD_NAMESPACE}
${POD_UID}
Expand All @@ -195,18 +183,18 @@ volumeAttributes:

If the flag `--use-token-request` is enabled on the csi-driver DaemonSet, the
[CertificateRequest](../concepts/certificaterequest.md) resource will be created
by the mounting Pod's ServiceAccount. This can be pared with
[approver-policy](./approver-policy/README.md) to enable advanced policy on a per
ServiceAccount basis.
by the mounting Pod's ServiceAccount. This can be paired with
[approver-policy](./approver-policy/README.md) to enable advanced policy control
on a per-ServiceAccount basis.

Ensure to give permissions to Pod ServiceAccounts to create CertificateRequests
Ensure that you give permissions to Pod ServiceAccounts to create CertificateRequests
with this flag enabled, i.e:

```yaml
# WARNING: This RBAC will enable any identiy in the cluster to create
# CertificateRequests. This may or may not be problimatic based on your security
# model. It is likely worth scoping the set of identities in the
# `ClusterRoleBinding` `subjects` stanza.
# WARNING: This RBAC will enable any identity in the cluster to create
# CertificateRequests and is dangerous to use in production. Instead, you should
# give permissions only to identities which need to be able to create certificates.
# This would be done via scoping the set of identities in the `ClusterRoleBinding` `subjects` stanza.
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
Expand Down

0 comments on commit 4f73bfe

Please sign in to comment.