Skip to content

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.

  1. Configure access to the Venafi OCI registry. Follow the instructions in Configuring access to the Venafi OCI Registry to enable access to the artifacts required for this component (cert-manager Components is the default scope for cert-manager). Use venafi as the namespace.

    The sample file below, for example, assumes you created the following Kubernetes Secret:

    • namespace: venafi
    • name: venafi-image-pull-secret
  2. 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.

    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
    

    Use the helm upgrade command to install cert-manager:

    helm upgrade -i -n venafi cert-manager oci://registry.venafi.cloud/charts/cert-manager \
      --set extraArgs={--controllers='*\,-certificaterequests-approver'} \
      --set crds.enabled=true \
      --values cert-manager.values.yaml \
      --create-namespace \
      --version v1.15.0
    

    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-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
    

    Use the helm upgrade command to install cert-manager:

    helm upgrade -i -n venafi cert-manager oci://registry.venafi.cloud/charts/cert-manager \
      --set extraArgs={--controllers='*\,-certificaterequests-approver'} \
      --set crds.enabled=true \
      --values cert-manager.values.yaml \
      --create-namespace \
      --version v1.15.0
    

    A sample cert-manager.values.yaml for users with their own organizatonal OCI registry. Be sure to update this command with the URI of your own company's 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-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
    

    Use the helm upgrade command to install cert-manager:

    helm upgrade -i -n venafi cert-manager oci://myregistry.example.com/charts/cert-manager \
      --set extraArgs={--controllers='*\,-certificaterequests-approver'} \
      --set crds.enabled=true \
      --values cert-manager.values.yaml \
      --create-namespace \
      --version v1.15.0
    

    Note

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

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.

  1. 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.

  2. 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:

  1. 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
    
  2. Install CSI driver for SPIFFE from the Venafi OCI 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.6.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.6.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.6.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

  1. 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:

    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.6.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.6.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.6.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.