Installing CSI Driver for SPIFFE using Helm¶

In this tutorial, you'll use Helm to install CSI Driver for SPIFFE, which issues SPIFFE Verifiable Identity Documents (SVIDs) to pods as secretless X.509 certificates.

Prerequisites¶

To complete these steps, you must have:

On your local machine, kubectl, Helm 3.8.0+, and cmctl.
Permission to install Helm charts and CRDs in your Kubernetes cluster.
As described in Configuring Next-Gen Trust Security registry access, private registry access through a Built-in Account with the OCI Registry Use Case and cert-manager Components Scope, using kubectl to create a pull secret.

Step 1: Install cert-manager¶

Install cert-manager with the default approver disabled. CSI Driver for SPIFFE includes its own approver, which replaces the built-in one.

Disable the default cert-manager approver

If you do not disable the default cert-manager approver before installing, the approvers will race and policy enforcement will not work.

To disable the cert-manager approver, see the steps in Reconfigure cert-manager from the Approver Policy tutorial, which apply here as well.

v1.20+Pre-v1.20

To install cert-manager and configure it to use a pull secret, create cert-manager.values.yaml.

cert-manager.values.yaml

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

crds:
  enabled: true

# Add if using your own registry
# imageRegistry: myregistry.example.com
# imageNamespace: cert-manager

Install cert-manager and wait for it to be ready:

helm upgrade cert-manager oci://registry.ngts.paloaltonetworks.com/charts/cert-manager \
  --install \
  --wait \
  --create-namespace \
  --namespace venafi \
  --values cert-manager.values.yaml \
  --version v1.20.0

Prior to cert-manager v1.20, you specify the full image path for each component in the values file.

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

If using your own registry, replace registry.ngts.paloaltonetworks.com with your registry URL.

cert-manager.values.yaml

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

crds:
  enabled: true

image:
  repository: registry.ngts.paloaltonetworks.com/cert-manager/cert-manager-controller

acmesolver:
  image:
    repository: registry.ngts.paloaltonetworks.com/cert-manager/cert-manager-acmesolver

webhook:
  image:
    repository: registry.ngts.paloaltonetworks.com/cert-manager/cert-manager-webhook

cainjector:
  image:
    repository: registry.ngts.paloaltonetworks.com/cert-manager/cert-manager-cainjector

startupapicheck:
  image:
    repository: registry.ngts.paloaltonetworks.com/cert-manager/cert-manager-startupapicheck

Install cert-manager and wait for it to be ready:

helm upgrade cert-manager oci://registry.ngts.paloaltonetworks.com/charts/cert-manager \
  --install \
  --wait \
  --create-namespace \
  --namespace venafi \
  --values cert-manager.values.yaml \
  --version vX.X.X

Step 2: Configure an Issuer or ClusterIssuer¶

CSI Driver for SPIFFE requires an issuer to sign SVIDs. You can defer this step if you plan to use runtime configuration, but you must configure a valid issuer before any pod can obtain an SVID.

Your issuer must support signing certificates with a custom URI Subject Alternative Name (SAN). ACME issuers and the SelfSigned issuer are not compatible. If you use a namespace-scoped issuer, create it in every namespace where pods will mount volumes.

Create a clusterissuer.yaml file with your issuer definition.

Warning

The following example stores the CA private key on the cluster for simplicity. In production, use an issuer that stores private keys externally, such as Distributed Issuer.

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

Save runtime configuration values

If you are using a ConfigMap to configure an issuer at runtime, note the name, kind, and group values. You will need them when creating the ConfigMap.

Apply the issuer configuration:
```
kubectl apply -f clusterissuer.yaml
```

Approve the CertificateRequest manually with cmctl. The default approver is disabled.

cmctl approve -n venafi \
  $(kubectl get cr -n venafi -ojsonpath='{.items[0].metadata.name}')

Step 3: Install CSI Driver for SPIFFE¶

If you mirror images to your own registry, replace registry.ngts.paloaltonetworks.com with your registry URL.
For FIPS-compliant images, append -fips to the chart name and each image path in the command, for example registry.ngts.paloaltonetworks.com/csi-driver-spiffe/csi-driver-fips.

With runtime configurationWithout runtime configuration

In CSI Driver for SPIFFE v0.6.0+, you can specify an issuer at runtime with 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 and wait for it to be ready.

Default issuer fallback

In the following example, the default issuer values app.issuer.name, app.issuer.kind, and app.issuer.group are empty so that only a runtime configuration is used. If you prefer, set values to fall back to when the runtime configuration ConfigMap is invalid or deleted.

helm upgrade cert-manager-csi-driver-spiffe oci://registry.ngts.paloaltonetworks.com/charts/cert-manager-csi-driver-spiffe \
    --install \
    --namespace venafi \
    --version v0.12.0 \
    --set "app.logLevel=1" \
    --set "app.trustDomain=my.trust.domain" \ # (1)!
    --set "app.driver.livenessProbeImage.repository=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/livenessprobe" \
    --set "app.driver.nodeDriverRegistrarImage.repository=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/csi-node-driver-registrar" \
    --set "image.repository.approver=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
    --set "image.repository.driver=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/cert-manager-csi-driver" \
    --set "app.issuer.name=" \
    --set "app.issuer.kind=" \
    --set "app.issuer.group=" \
    --set "app.runtimeIssuanceConfigMap=spiffe-issuer" \
    --wait

Your SPIFFE trust domain, usually a subdomain of your company domain, for example kubernetes-1.example.com.

Verify that the ConfigMap was picked up by checking the CSI Driver for SPIFFE DaemonSet logs:

kubectl logs -n venafi -l app=cert-manager-csi-driver-spiffe --tail=20

Successful output is similar to the following:

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"

Change app.issuer.name, app.issuer.kind, and app.issuer.group to match the issuer you configured in Step 2.

Install CSI Driver for SPIFFE and wait for it to be ready:

helm upgrade cert-manager-csi-driver-spiffe oci://registry.ngts.paloaltonetworks.com/charts/cert-manager-csi-driver-spiffe \
    --install \
    --namespace venafi \
    --version v0.12.0 \
    --set "app.logLevel=1" \
    --set "app.trustDomain=my.trust.domain" \ # (1)!
    --set "app.driver.livenessProbeImage.repository=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/livenessprobe" \
    --set "app.driver.nodeDriverRegistrarImage.repository=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/csi-node-driver-registrar" \
    --set "image.repository.approver=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/cert-manager-csi-driver-spiffe-approver" \
    --set "image.repository.driver=registry.ngts.paloaltonetworks.com/csi-driver-spiffe/cert-manager-csi-driver" \
    --set "app.issuer.name=my-issuer-name" \
    --set "app.issuer.kind=ClusterIssuer" \
    --set "app.issuer.group=cert-manager.io" \
    --wait

Your SPIFFE trust domain, usually a subdomain of your company domain, for example kubernetes-1.example.com.