⚠️ Additional Instructions

Since SPIFFE Helm Charts do not have SPIKE Bootstrap yet, the instructions on this page have additional guidance to deploy SPIKE using a local SPIFFE Helm Charts repo.

We will update this page once SPIKE Bootstrap is available in the upstream SPIFFE Helm Charts.

SPIKE Quickstart Guide

The fastest way to get started with SPIRE and SPIKE is to deploy them using the official SPIFFE Helm chart.

You can deploy SPIKE to any Kubernetes cluster, including a local one like KinD or Minikube. We will use Minikube in this guide. Your installation may vary slightly depending on the Kubernetes cluster you are using, but the general steps will be the same.

We will also use a Debian Linux machine throughout this guide, but you can use any OS that supports SPIFFE, SPIRE, Docker, and Kubernetes. Depending on your OS, your installation steps may vary slightly, but the general steps will not change much.

Prerequisites

Here is a list of things you need to have installed on your machine before starting with this guide:

Have Docker installed and running on your machine.
Have a kubectl client installed.
Have make installed on your machine.
Have a minikube binary installed.
Have helm binary installed.
(Optional) install zola if you want to build the documentation locally.

For Windows Users

The best way to get started on Windows is to use Windows Subsystem for Linux. After installing WSL, make sure to install the prerequisites (docker, kubectl, make, minikube, helm) to your WSL distribution and not to your Windows machine.

Hosts File Setup

SPIKE bare-metal installation requires that spike.spike.ist is configured in your /etc/hosts file. However, WSL will automatically override your Linux hosts wile every time you restart your WSL distribution.

To fix this, edit /etc/wsl.conf and add the following lines:

# sudo vim /etc/wsl.conf

[network]
generateHosts=false

Then update your hosts file:

# sudo vim /etc/hosts

# Add the following line:
127.0.0.1  spire.spike.ist

Then restart your WSL distribution, and the hosts file is yours to modify and maintain.

Note that editing C:\Windows\System32\drivers\etc\hosts will NOT work.

WSL Memory Lock Limit

WSL sets a default RLIMIT_MEMLOCK of 64MB for all shell sessions. This limit is imposed by WSL’s Relay process before any Linux configuration is read, which means standard Linux approaches (/etc/security/limits.conf, systemd configs, PAM) cannot override it.

SPIKE uses memory locking (mlock) to prevent sensitive secrets from being swapped to disk. Failing to lock memory will not stop SPIKE from running, but you will see warnings in the logs.

WSL spawns your shell via a Windows-side Relay process:

Windows WSL (sets 64MB limit) → Relay → your shell

By the time Linux session management runs, the limit is already inherited. The following have no effect on interactive WSL shells:

/etc/security/limits.conf
/etc/systemd/user.conf
/etc/systemd/system.conf
PAM configuration

These configs do apply to processes spawned through systemd (e.g., systemd-run --user), but not to your default terminal session.

To fix this, you can use the following script:

!#/usr/bin/env bash
# > ulimit -l
# 65536
# --

# Raise memlock limit for SPIKE development
sudo prlimit --memlock=unlimited:unlimited \
  --pid $$ 2>/dev/null && exec bash

# --
# > ulimit -l
# unlimited

You can even add this script to your ~/.bashrc or ~/.zshrc to make it automatically run on every shell session.

Environment Variables

It may be useful to set the following environment variables before you start.

This is a sample configuration; please adjust as needed:

# User Configuration
#
# Add this to your ~/.bashrc or ~/.zshrc, ~/.profile,
# or ~/.zprofile, or wherever you keep your shell config.

export PATH=$PATH:/usr/local/go/bin

# If you are using GPG for signing commits:
export GPG_TTY=$(tty)

# This where you clone SPIKE, SPIRE, and SPIFFE Helm Charts:
export WORKSPACE="$HOME/WORKSPACE" 

# These are needed for Bare-Metal Installation:
export PATH="$PATH:$WORKSPACE/spire/bin"
export PATH="$PATH:$WORKSPACE/spike"

# Optional, but recommended.
source "$WORKSPACE/spike/hack/lib/env.sh"
# ^ Note that the `make start` Make target will
# automatically source this file for you.

Starting Minikube

To start a local Minikube cluster, clone the project repository and run the following command in the root directory of the project:

cd $WORKSPACE # Replace with your workspace directory
git clone https://github.com/spiffe/spike.git
cd spike
make docker-cleanup # (Optional) Purge docker registry.
make k8s-delete     # Delete any former Minikube installation.
make k8s-start      # This will start a Minikube cluster.

If successful, you will have a local Minikube cluster running with the necessary plugins enabled. You can verify that Minikube is running by executing:

minikube status
# or...
kubectl get node

# Sample Outputs:
#
# $ minikube status
# minikube
# type: Control Plane
# host: Running
# kubelet: Running
# apiserver: Running
# kubeconfig: Configured
#
# $ kubectl get node
# NAME       STATUS   ROLES           AGE   VERSION
# minikube   Ready    control-plane   67s   v1.33.1

Deploying SPIKE to Minikube

⚠️ Changes Due to Current Upstream Helm Charts Work

There are some changes to the upstream SPIFFE Helm Charts that are currently in progress. Until they are merged, you will need to use a feature branch of the upstream repo.

For this, first clone the upstream repo:
git clone https://github.com/spiffe/helm-charts-hardened.git
Then, switch to the spike-next branch:
cd helm-charts-hardened
git checkout spike-next
You can now use the spike-next branch of the upstream repo to deploy SPIKE to Minikube.
# $WORKSPACE is your local workspace directory where you cloned the 
# helm-charts-hardened repo and the spike repo.

# Create a new namespace for SPIRE components.
kubectl create ns spire-mgmt

# Deploy the CRDs.
helm upgrade --install -n spire-mgmt "spire-crds" "spire-crds" \
"WORKSPACE/helm-charts-hardened/charts/spire-crds" \
--create-namespace

# Deploy SPIRE and SPIKE components.
helm upgrade --install -n spire-mgmt "spiffe" "spire" \
"WORKSPACE/helm-charts-hardened/charts/spire" \
-f /path/to/your/values.yaml

spife-helm-charts-hardened: https://spiffe.github.io/helm-charts-hardened/

Once you have Minikube running, you can deploy SPIKE to it from SPIFFE helm charts.

First create a values.yaml file to enable SPIKE components:

# file: values.yaml
spike-nexus:
  enabled: true
spike-keeper:
  enabled: true
spike-pilot:
  enabled: true
spire-server:
  enabled: true
spire-agent:
  enabled: true
spiffe-csi-driver:
  enabled: true
spiffe-oidc-discovery-provider:
  enabled: true

Then deploy SPIKE using the following command:

helm upgrade --install spire-crds spire-crds \
  --repo https://spiffe.github.io/helm-charts-hardened/
  
helm upgrade --install spiffe spire \
  --repo https://spiffe.github.io/helm-charts-hardened \
  -f ./values.yaml # The values.yaml file we created earlier

Verifying SPIKE Deployment

First, make sure that your components are up and running.

kubectl get po -A
# Sample Output:
#
# NAME                                              READY  STATUS 
# spike          spiffe-spike-keeper-0              1/1    Running
# spike          spiffe-spike-keeper-1              1/1    Running
# spike          spiffe-spike-keeper-2              1/1    Running
# spike          spiffe-spike-nexus-0               1/1    Running
# spike          spiffe-spike-pilot-5ddb88f-jsv9q   1/1    Running
# spire-server   spiffe-server-0                    2/2    Running
# spire-server   spiffe-oidc-provider-b4b9d-vn2zj   2/2    Running
# spire-system   spiffe-agent-lllsv                 1/1    Running
# spire-system   spiffe-spiffe-csi-driver-dkbwf     2/2    Running

Once the deployment is complete, you can verify SPIKE is running by creating a sample secret and reading its value back.

kubectl exec -it deploy/spiffe-spike-pilot -- sh
# Shell into the container and run the following commands:
spike secret list
# Output:
# No Secrets found.
spike secret put test/creds username=spike password=SPIKERocks
# Output:
# OK
spike secret list
# Output:
# - test/creds
spike secret get test/creds
# Output:
# password: SPIKERocks
# username: spike

Next Up

You are all set. You have successfully deployed SPIKE to your local Minikube cluster. Explore other parts of the documentation to learn more about using SPIKE.

Here are a few links to get you started:

Open Source Is Better Together

Join the SPIKE community to ask your questions and learn from the subject-matter experts.