Installing CSI driver for SPIFFE using Helm¶

Learn how to install CSI driver for SPIFFE using Helm.

Prequisites¶

To install CSI driver for SPIFFE you'll need the following:

You must have permission to install Helm charts and CRDs on your Kubernetes cluster.
You must have kubectl, Helm 3.8.0 or later, and cmctl on your local computer.

Step 1: Install cert-manager¶

CSI driver for SPIFFE requires cert-manager to be installed but a default installation of cert-manager will not work. If the default approver is not disabled, the CSI driver for SPIFFE approver will race with cert-manager and policy enforcement will become useless.

Policy enforcement is absolutely critical for using CSI driver for SPIFFE safely.

To install cert-manager in the venafi namespace, and configure it to use the pull-secret, create a file cert-manager.values.yaml containing the following content.

US RegionEU RegionOwn Registry

A sample cert-manager.values.yaml for users of the US region OCI registry:

cert-manager.values.yaml

global:
  imagePullSecrets:
    - name: venafi-image-pull-secret

crds:
  enabled: true

image:
  repository: private-registry.venafi.cloud/cert-manager/cert-manager-controller

acmesolver:
  image:
    repository: private-registry.venafi.cloud/cert-manager/cert-manager-acmesolver

webhook:
  image:
    repository: private-registry.venafi.cloud/cert-manager/cert-manager-webhook

cainjector:
  image:
    repository: private-registry.venafi.cloud/cert-manager/cert-manager-cainjector

startupapicheck:
  image:
    repository: private-registry.venafi.cloud/cert-manager/cert-manager-startupapicheck

A sample cert-manager.values.yaml for users of the EU region OCI registry:

cert-manager.values.yaml

global:
  imagePullSecrets:
    - name: venafi-image-pull-secret

crds:
  enabled: true

image:
  repository: private-registry.venafi.eu/cert-manager/cert-manager-controller

acmesolver:
  image:
    repository: private-registry.venafi.eu/cert-manager/cert-manager-acmesolver

webhook:
  image:
    repository: private-registry.venafi.eu/cert-manager/cert-manager-webhook

cainjector:
  image:
    repository: private-registry.venafi.eu/cert-manager/cert-manager-cainjector

startupapicheck:
  image:
    repository: private-registry.venafi.eu/cert-manager/cert-manager-startupapicheck

A sample cert-manager.values.yaml for users with their own OCI registry:

cert-manager.values.yaml

global:
  imagePullSecrets:
    - name: venafi-image-pull-secret

crds:
  enabled: true

image:
  repository: myregistry.example.com/cert-manager/cert-manager-controller

acmesolver:
  image:
    repository: myregistry.example.com/cert-manager/cert-manager-acmesolver

webhook:
  image:
    repository: myregistry.example.com/cert-manager/cert-manager-webhook

cainjector:
  image:
    repository: myregistry.example.com/cert-manager/cert-manager-cainjector

startupapicheck:
  image:
    repository: myregistry.example.com/cert-manager/cert-manager-startupapicheck

Note

As of cert-manager v1.15.0, the installCRDs value is deprecated in favor of crds.enabled.

Use Helm to install the software and wait for it to be ready:

helm upgrade cert-manager oci://registry.venafi.cloud/charts/cert-manager \
--install \
--wait \
--create-namespace \
--namespace venafi \
--values cert-manager.values.yaml \
--version v1.15.1

Note

For more information about Helm support for OCI package distribution, see the Helm documentation.

Step 2: Configure an Issuer or ClusterIssuer¶

Note

This step can be deferred if you use runtime configuration, but a valid issuer must be configured before a pod can successfully use CSI driver for SPIFFE to obtain an SVID.

If you wish to use a namespace-scoped issuer it must be created in every namespace that Pods will mount volumes from.

You must use an Issuer type which is compatible with signing certificates with a custom URI SAN. ACME issuers won't generally work, and the SelfSigned issuer is not appropriate.

Note

This step requires you to use the cert-manager command-line tool cmctl. For more information on how to install and use this tool see the cmctl install page.

Install or configure an issuer to use for signing CertificateRequest resources in your Trust Domain. See the following example:

clusterissuer.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: csi-driver-spiffe-ca
  namespace: venafi
spec:
  commonName: csi-driver-spiffe-ca
  secretName: csi-driver-spiffe-ca
  duration: 2160h
  isCA: true
  issuerRef:
    name: selfsigned
    kind: ClusterIssuer
    group: cert-manager.io
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: my-issuer-name
spec:
  ca:
    secretName: csi-driver-spiffe-ca

Use kubectl to apply the clusterissuer.yaml file:

kubectl apply -f clusterissuer.yaml

Note

If you are using a configmap to configure an issuer at runtime, be sure to take note of the name, kind and group values you use in your issuer as they will be need to be passed to the configmap.

You must also approve the CertificateRequest since the default approver is disabled. The following example uses cmctl to approve the CertificateRequest, since the default approver was disabled above:
```
cmctl approve -n venafi \
  $(kubectl get cr -n venafi -ojsonpath='{.items[0].metadata.name}')
```
Important

This example demonstrates the use of a CA issuer with the private key stored on the cluster for simplicity. Venafi strongly advises against using this approach in production environments. For a more secure and manageable solution, organizations should use a Venafi Firefly issuer.

Step 3: Install CSI driver for SPIFFE¶

You can install CSI driver for SPIFFE with or without runtime configuration.

To install CSI driver for SPIFFE with runtime configuration¶

As of release v0.6.0, you can specify an issuer at runtime using a ConfigMap:

Configure a ConfigMap in CSI driver for SPIFFE's installation namespace that specifies which issuer to use.

kubectl create configmap spiffe-issuer -n venafi \
    --from-literal=issuer-name=my-issuer-name \
    --from-literal=issuer-kind=ClusterIssuer \
    --from-literal=issuer-group=cert-manager.io

Install CSI driver for SPIFFE from the Venafi OCI registry:

US RegionEU RegionOwn Registry

A sample command for users of the US region Venafi OCI registry

helm upgrade -i -n venafi cert-manager-csi-driver-spiffe oci://registry.venafi.cloud/charts/cert-manager-csi-driver-spiffe --wait \
    --version "v0.8.0" \
    --set "app.logLevel=1" \
    --set "app.trustDomain=my.trust.domain" \
    --set "app.driver.livenessProbeImage.repository=private-registry.venafi.cloud/csi-driver/livenessprobe" \
    --set "app.driver.nodeDriverRegistrarImage.repository=private-registry.venafi.cloud/csi-driver/csi-node-driver-registrar" \
    --set "image.repository.approver=private-registry.venafi.cloud/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
    --set "image.repository.driver=private-registry.venafi.cloud/csi-driver-spiffe/cert-manager-csi-driver-spiffe" \
    --set "app.issuer.name=" \
    --set "app.issuer.kind=" \
    --set "app.issuer.group=" \
    --set "app.runtimeIssuanceConfigMap=spiffe-issuer"

A sample command for users of the EU region Venafi OCI registry:

helm upgrade -i -n venafi cert-manager-csi-driver-spiffe oci://registry.venafi.cloud/charts/cert-manager-csi-driver-spiffe --wait \
    --version "v0.8.0" \
    --set "app.logLevel=1" \
    --set "app.trustDomain=my.trust.domain" \
    --set "app.driver.livenessProbeImage.repository=private-registry.venafi.eu/csi-driver/livenessprobe" \
    --set "app.driver.nodeDriverRegistrarImage.repository=private-registry.venafi.eu/csi-driver/csi-node-driver-registrar" \
    --set "image.repository.approver=private-registry.venafi.eu/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
    --set "image.repository.driver=private-registry.venafi.eu/csi-driver-spiffe/cert-manager-csi-driver-spiffe" \
    --set "app.issuer.name=" \
    --set "app.issuer.kind=" \
    --set "app.issuer.group=" \
    --set "app.runtimeIssuanceConfigMap=spiffe-issuer"

A sample command for users with their own organizatonal OCI registry. Be sure to update this command with the URI of your own company's registry:

helm upgrade -i -n venafi cert-manager-csi-driver-spiffe oci://myregistry.example.com/charts/cert-manager-csi-driver-spiffe --wait \
    --version "v0.8.0" \
    --set "app.logLevel=1" \
    --set "app.trustDomain=my.trust.domain" \
    --set "app.driver.livenessProbeImage.repository=myregistry.example.com/csi-driver/livenessprobe" \
    --set "app.driver.nodeDriverRegistrarImage.repository=myregistry.example.com/csi-driver/csi-node-driver-registrar" \
    --set "image.repository.approver=myregistry.example.com/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
    --set "image.repository.driver=myregistry.example.com/csi-driver-spiffe/cert-manager-csi-driver-spiffe" \
    --set "app.issuer.name=" \
    --set "app.issuer.kind=" \
    --set "app.issuer.group=" \
    --set "app.runtimeIssuanceConfigMap=spiffe-issuer"

Note

app.trustDomain - CSI driver for SPIFFE requires the name of a SPIFFE trust domain to embed into the machine identities it creates. Usually this takes the form of a subdomain of a company domain name, for example kubernetes-1.example.com.

The logs for the CSI driver for SPIFFE DaemonSet pods should produce output like the following to show that the ConfigMap was picked up:

I0516 11:57:44.655854       1 driver.go:410] "Changed active issuerRef in response to runtime configuration ConfigMap" logger="csi.runtime-config-watcher" config-map-name="spiffe-issuer" config-map-namespace="venafi" issuer-name="my-issuer-name" issuer-kind="ClusterIssuer" issuer-group="cert-manager.io"

In the example above the default issuer values (app.issuer.name, app.issuer.kind, and app.issuer.group) are explicitly set to be empty, meaning that only runtime configuration will be used.

You can set the default issuer values if you want to fall back to that issuer in the event that the runtime configuration ConfigMap is invalid or deleted.

Installing CSI driver for SPIFFE without runtime configuration¶

Use the helm upgrade command to install CSI driver for SPIFFE from the Venafi OCI registry. Note that the issuer.name, issuer.kind and issuer.group will need to be changed to match the issuer you're using:

US RegionEU RegionOwn registry

A sample command for users of the US region Venafi OCI registry

helm upgrade -i -n venafi cert-manager-csi-driver-spiffe oci://registry.venafi.cloud/charts/cert-manager-csi-driver-spiffe --wait \
  --version "v0.8.0" \
  --set "app.logLevel=1" \
  --set "app.trustDomain=my.trust.domain" \
  --set "app.driver.livenessProbeImage.repository=private-registry.venafi.cloud/csi-driver/livenessprobe" \
  --set "app.driver.nodeDriverRegistrarImage.repository=private-registry.venafi.cloud/csi-driver/csi-node-driver-registrar" \
  --set "image.repository.approver=private-registry.venafi.cloud/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
  --set "image.repository.driver=private-registry.venafi.cloud/csi-driver-spiffe/cert-manager-csi-driver-spiffe" \
  --set "app.issuer.name=my-issuer-name" \
  --set "app.issuer.kind=ClusterIssuer" \
  --set "app.issuer.group=cert-manager.io"

A sample command for users of the EU region Venafi OCI registry:

helm upgrade -i -n venafi cert-manager-csi-driver-spiffe oci://registry.venafi.cloud/charts/cert-manager-csi-driver-spiffe --wait \
  --version "v0.8.0" \
  --set "app.logLevel=1" \
  --set "app.trustDomain=my.trust.domain" \
  --set "app.driver.livenessProbeImage.repository=private-registry.venafi.eu/csi-driver/livenessprobe" \
  --set "app.driver.nodeDriverRegistrarImage.repository=private-registry.venafi.eu/csi-driver/csi-node-driver-registrar" \
  --set "image.repository.approver=private-registry.venafi.eu/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
  --set "image.repository.driver=private-registry.venafi.eu/csi-driver-spiffe/cert-manager-csi-driver-spiffe" \
  --set "app.issuer.name=my-issuer-name" \
  --set "app.issuer.kind=ClusterIssuer" \
  --set "app.issuer.group=cert-manager.io"

A sample command for users with their own organizatonal OCI registry. Be sure to update this command with the URI of your own company's registry:

helm upgrade -i -n venafi cert-manager-csi-driver-spiffe oci://myregistry.example.com/charts/cert-manager-csi-driver-spiffe --wait \
    --version "v0.8.0" \
    --set "app.logLevel=1" \
    --set "app.trustDomain=my.trust.domain" \
    --set "app.driver.livenessProbeImage.repository=myregistry.example.com/csi-driver/livenessprobe" \
    --set "app.driver.nodeDriverRegistrarImage.repository=myregistry.example.com/csi-driver/csi-node-driver-registrar" \
    --set "image.repository.approver=myregistry.example.com/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
    --set "image.repository.driver=myregistry.example.com/csi-driver-spiffe/cert-manager-csi-driver-spiffe" \
    --set "app.issuer.name=my-issuer-name" \
    --set "app.issuer.kind=ClusterIssuer" \
    --set "app.issuer.group=cert-manager.io"

Note

app.trustDomain - CSI driver for SPIFFE requires the name of a SPIFFE trust domain to embed into the machine identities it creates. Usually this takes the form of a subdomain of a company domain name, for example kubernetes-1.example.com.

Reference: CSI driver for SPIFFE Helm values

Installing CSI driver for SPIFFE using Helm¶

Prequisites¶

Step 1: Install cert-manager¶

Step 2: Configure an Issuer or ClusterIssuer¶

Step 3: Install CSI driver for SPIFFE¶

To install CSI driver for SPIFFE with runtime configuration¶

Installing CSI driver for SPIFFE without runtime configuration¶

Related links¶