helm-charts-hardened/charts/spire/README.md

spire

A Helm chart for deploying the complete Spire stack including: spire-server, spire-agent, spiffe-csi-driver, spiffe-oidc-discovery-provider and spire-controller-manager.

Homepage: https://github.com/spiffe/helm-charts-hardened/tree/main/charts/spire

Install Instructions

Non Production

To do a quick install suitable for testing in something like minikube:

helm upgrade --install -n spire-server spire-crds spire-crds --repo https://spiffe.github.io/helm-charts-hardened/ --create-namespace
helm upgrade --install -n spire-server spire spire --repo https://spiffe.github.io/helm-charts-hardened/

Production

Preparing a production deployment requires a few steps.

1. Save the following to your-values.yaml, ideally in your git repo.

global:
  openshift: false # If running on openshift, set to true
  spire:
    recommendations:
      enabled: true
    namespaces:
      create: true
    ingressControllerType: "" # If not openshift, and want to expose services, set to a supported option [ingress-nginx]
    # Update these
    clusterName: example-cluster
    trustDomain: example.org
spire-server:
  ca_subject:
    # Update these
    country: ARPA
    organization: Example
    common_name: example.org

2. If you need a non default storageClass, append the following to the spire-server section and update:

  persistence:
    storageClass: your-storage-class

3. If your Kubernetes cluster is OpenShift based, use the output of the following command to update the trustDomain setting:

oc get cm -n openshift-config-managed  console-public -o go-template="{{ .data.consoleURL }}" | sed 's@https://@@; s/^[^.]*\.//'

4. Find any additional values you might want to set based on the documentation below or using the examples

In particular, consider using an external database.

5. Deploy

helm upgrade --install -n spire-mgmt spire-crds spire-crds --repo https://spiffe.github.io/helm-charts-hardened/ --create-namespace
helm upgrade --install -n spire-mgmt spire spire --repo https://spiffe.github.io/helm-charts-hardened/ -f your-values.yaml

Upgrade notes

We only support upgrading one major version at a time. Version skipping isn't supported.

0.17.X

• The SPIFFE OIDC Discovery Provider now has many new TLS options and defaults to using SPIRE to issue its certificate.

• The spiffe-oidc-discovery-provider.insecureScheme.enabled flag was removed. If you previously set that flag, remove the setting from your values.yaml and see if the new default of using a SPIRE issued certificate is suitable for your deployment. If it isn't, please consider one of the other options under spiffe-oidc-discovery-provider.tls. If all other options are still unsuitable, you can still enable the previous mode by disabling TLS. (spiffe-oidc-discovery-provider.spire.enabled=false)

• The SPIFFE OIDC Discovery Provider is now enabled by default. If you previously chose to have it off, you can disable it explicitly with spiffe-oidc-discovery-provider.enabled=false.

0.16.X

The settings under "spire-server.controllerManager.identities" have all been moved under "spire-server.controllerManager.identities.clusterSPIFFEIDs.default". If you have changed any from the defaults, please update them to the new location during upgrade.

0.15.X

The spire-crds chart has been updated. Please ensure you have upgraded spire-crds before upgrading the spire chart.

The chart now supports multiple parallel installs of spire-controller-manager. Each install will handle all custom resources with a matching className field. By default this is set to Release.Namespace-Release.Name and the controller manager will only pick up custom resources with this className.

If you have not loaded any SPIRE custom resources yourself, the upgrade process will be transparent. If you have loaded your own SPIRE custom resources, set spire-server.controllerManager.watchClassless=true until you can update your SPIRE custom resources to have the className for the instance specified.

0.14.X

If coming from a chart version before 0.14.0, you must relabel your crds to switch to using the new spire-crds chart. To migrate to the spire-crds chart run the following:

Replace the spire-server namespace in the commands below with the namespace you want to install the spire-crds chart in.

kubectl label crd "clusterfederatedtrustdomains.spire.spiffe.io" "app.kubernetes.io/managed-by=Helm"
kubectl annotate crd "clusterfederatedtrustdomains.spire.spiffe.io" "meta.helm.sh/release-name=spire-crds"
kubectl annotate crd "clusterfederatedtrustdomains.spire.spiffe.io" "meta.helm.sh/release-namespace=spire-server"
kubectl label crd "clusterspiffeids.spire.spiffe.io" "app.kubernetes.io/managed-by=Helm"
kubectl annotate crd "clusterspiffeids.spire.spiffe.io" "meta.helm.sh/release-name=spire-crds"
kubectl annotate crd "clusterspiffeids.spire.spiffe.io" "meta.helm.sh/release-namespace=spire-server"
kubectl label crd "controllermanagerconfigs.spire.spiffe.io" "app.kubernetes.io/managed-by=Helm"
kubectl annotate crd "controllermanagerconfigs.spire.spiffe.io" "meta.helm.sh/release-name=spire-crds"
kubectl annotate crd "controllermanagerconfigs.spire.spiffe.io" "meta.helm.sh/release-namespace=spire-server"
helm install -n spire-server spire-crds charts/spire-crds

Version support

Warning

This Chart is still in development and still subject to change the API (values.yaml). Until we reach a 1.0.0 version of the chart we can't guarantee backwards compatibility although we do aim for as much stability as possible.

Dependency	Supported Versions
Helm	3.x
Kubernetes	1.22+

Note

For Kubernetes, we will officially support the last 3 versions as described in k8s versioning. Any version before the last 3 we will try to support as long it doesn't bring security issues or any big maintenance burden.

FAQ

For any issues see our FAQ…

Usage

To utilize Spire in your own workloads you should add the following to your workload:

 apiVersion: v1
 kind: Pod
 metadata:
   name: my-app
 spec:
   containers:
     - name: my-app
       image: "my-app:latest"
       imagePullPolicy: Always
+      volumeMounts:
+        - name: spiffe-workload-api
+          mountPath: /spiffe-workload-api
+          readOnly: true
       resources:
         requests:
           cpu: 200m
           memory: 32Mi
         limits:
           cpu: 500m
           memory: 64Mi
+  volumes:
+    - name: spiffe-workload-api
+      csi:
+        driver: "csi.spiffe.io"
+        readOnly: true

Now you can interact with the Spire agent socket from your own application. The socket is mounted on /spiffe-workload-api/spire-agent.sock.

Maintainers

Name	Email	Url
marcofranssen	[email protected]	https://marcofranssen.nl
kfox1111	[email protected]
faisal-memon	[email protected]
edwbuck	[email protected]

Source Code

• https://github.com/spiffe/helm-charts-hardened/tree/main/charts/spire

Requirements

Repository	Name	Version
file://./charts/spiffe-csi-driver	spiffe-csi-driver	0.1.0
file://./charts/spiffe-csi-driver	upstream-spiffe-csi-driver(spiffe-csi-driver)	0.1.0
file://./charts/spiffe-oidc-discovery-provider	spiffe-oidc-discovery-provider	0.1.0
file://./charts/spire-agent	spire-agent	0.1.0
file://./charts/spire-agent	upstream-spire-agent(spire-agent)	0.1.0
file://./charts/spire-server	spire-server	0.1.0
file://./charts/tornjak-frontend	tornjak-frontend	0.1.0

Parameters

Global parameters

Name	Description	Value
global.k8s.clusterDomain	Cluster domain name configured for Spire install	cluster.local
global.spire.bundleConfigMap	A configmap containing the Spire bundle	""
global.spire.clusterName	The name of the k8s cluster for Spire install	example-cluster
global.spire.jwtIssuer	The issuer for Spire JWT tokens. Defaults to oidc-discovery.$trustDomain if unset	""
global.spire.trustDomain	The trust domain for Spire install	example.org
global.spire.upstreamServerAddress	Set what address to use for the upstream server when using nested spire	""
global.spire.recommendations.enabled	Use recommended settings for production deployments. Default is off.	false
global.spire.recommendations.namespaceLayout	Set to true to use recommended values for installing across namespaces	true
global.spire.recommendations.namespacePSS	When chart namespace creation is enabled, label them with preffered Pod Security Standard labels	true
global.spire.recommendations.priorityClassName	Set to true to use recommended values for Pod Priority Class Names	true
global.spire.recommendations.strictMode	Check values, such as trustDomain, are overridden with a suitable value for production.	true
global.spire.recommendations.securityContexts	Set to true to use recommended values for Pod and Container Security Contexts	true
global.spire.recommendations.prometheus	Enable prometheus exporters for monitoring	true
global.spire.image.registry	Override all Spire image registries at once	""
global.spire.namespaces.create	Set to true to Create all namespaces. If this or either of the namespace specific create flags is set, the namespace will be created.	false
global.spire.namespaces.system.name	Name of the Spire system Namespace.	spire-system
global.spire.namespaces.system.create	Create a Namespace for Spire system resources.	false
global.spire.namespaces.system.annotations	Annotations to apply to the Spire system Namespace.	{}
global.spire.namespaces.system.labels	Labels to apply to the Spire system Namespace.	{}
global.spire.namespaces.server.name	Name of the Spire server Namespace.	spire-server
global.spire.namespaces.server.create	Create a Namespace for Spire server resources.	false
global.spire.namespaces.server.annotations	Annotations to apply to the Spire server Namespace.	{}
global.spire.namespaces.server.labels	Labels to apply to the Spire server Namespace.	{}
global.spire.strictMode	Check values, such as trustDomain, are overridden with a suitable value for production.	false
global.spire.ingressControllerType	Specify what type of ingress controller you're using to add the necessary annotations accordingly. If blank, autodetection is attempted. If other, no annotations will be added. Must be one of [ingress-nginx, openshift, other, ""].	""
global.installAndUpgradeHooks.enabled	Enable Helm hooks to autofix common install/upgrade issues (should be disabled when using helm template)	true
global.deleteHooks.enabled	Enable Helm hooks to autofix common delete issues (should be disabled when using helm template)	true

Spire server parameters

Name	Description	Value
spire-server.enabled	Flag to enable Spire server	true
spire-server.nameOverride	Overrides the name of Spire server pods	server
spire-server.controllerManager.enabled	Enable controller manager and provision CRD's	true

Spire agent parameters

Name	Description	Value
spire-agent.enabled	Flag to enable Spire agent	true
spire-agent.nameOverride	Overrides the name of Spire agent pods	agent

Upstream Spire agent and CSI driver configuration

Name	Description	Value
upstream.enabled	Enable upstream agent and driver for use with nested spire	false

Upstream Spire agent parameters

Name	Description	Value
upstream-spire-agent.upstream	Flag for enabling upstream Spire agent	true
upstream-spire-agent.nameOverride	Name override for upstream Spire agent	agent-upstream
upstream-spire-agent.bundleConfigMap	The configmap name for upstream Spire agent bundle	spire-bundle-upstream
upstream-spire-agent.socketPath	Socket path where Spire agent socket is mounted	/run/spire/agent-sockets-upstream/spire-agent.sock
upstream-spire-agent.serviceAccount.name	Service account name for upstream Spire agent	spire-agent-upstream
upstream-spire-agent.healthChecks.port	Health check port number for upstream Spire agent	9981
upstream-spire-agent.telemetry.prometheus.port	The port where prometheus metrics are available	9989

SPIFFE CSI Driver parameters

Name	Description	Value
spiffe-csi-driver.enabled	Flag to enable spiffe-csi-driver for the cluster	true

Upstream SPIFFE CSI Driver parameters

Name	Description	Value
upstream-spiffe-csi-driver.pluginName	The plugin name for configuring upstream Spiffe CSI driver	upstream.csi.spiffe.io
upstream-spiffe-csi-driver.agentSocketPath	The socket path where Spiffe CSI driver mounts agent socket	/run/spire/agent-sockets-upstream/spire-agent.sock
upstream-spiffe-csi-driver.healthChecks.port	The port where Spiffe CSI driver health checks are exposed	9810

SPIFFE oidc discovery provider parameters

Name	Description	Value
spiffe-oidc-discovery-provider.enabled	Flag to enable spiffe-oidc-discovery-provider for the cluster	true

Tornjak frontend parameters

Name	Description	Value
tornjak-frontend.enabled	Enables deployment of Tornjak frontend/UI (Not for production)	false