About this Tutorial

This tutorial walks you through getting a SPIRE Server and SPIRE Agent running in a Kubernetes cluster, and configuring a workload container to access SPIRE.

This tutorial is not designed for a production Kubernetes environment.
A production environment requires adjustments to certain steps; the section
Changes for a Production Environment walks you through the necessary changes.

Before You Begin

Before you begin, read through this section for information about the environment and deployment it sets up. Also, if you’re not familiar with basic SPIFFE and SPIRE concepts, be sure to review the SPIFFE and SPIRE overviews.

Tested Kubernetes Versions

This tutorial has been tested on these Kubernetes versions: 1.13.1, 1.12.4, and 1.10.12.

Assumptions

The sample .yaml files for this walkthrough assume you are running Kubernetes in a minikube cluster. If you’re not running a minikube cluster, you will need to adjust certain configuration settings; these adjustments are called out in the relevant step in the tutorial.

Deployment and Configuration Details

The server deployment uses a nodeSelector to ensure that it runs on a “master” node. When running in an environment without an accessible “master,” you must select a node for the SPIRE Server and provision it, and change the nodeSelector entry in the server-deployment.yaml file accordingly.

The server deployment runs on the master Kubernetes node

The agent daemonset runs on each Kubernetes worker node

All SPIRE components are created in a Kubernetes namespace called spire.

The server runs in a service account named spire-server

The agent runs in a service account named spire-agent

The server uses a hostPath bind mount for persisting its keys and SQLite database.
.

Section 2: Configure Kubernetes Namespace for SPIRE Components

Follow these steps to configure the spire namespace in which this tutorial deploys the SPIRE Server and SPIRE Agent.

Create the namespace:

$ kubectl apply -f spire-namespace.yaml

Run the following command and verify that spire is listed in the output:

$ kubectl get namespaces

Section 3: Configure SPIRE Server

To configure the SPIRE server, you:

Create server service account

Create server secrets

Create server configmap

Create server deployment

Create Server Service Account

Configure a service account named spire-server, by applying the server-account.yaml configuration file:

$ kubectl apply -f server-account.yaml

To confirm successful creation, verify that “spire-server” appears in the output of the following command:

$ kubectl get sa -n spire

Create Server Secrets

This example of creating secrets uses a bootstrap cert and key, as configured in the server-secrets.yaml configuration file.
The value for bootstrap.key is a base64 encoding of dummy_upstream_ca.key. For reference, this value was generated by running the following base64 command:

$ base64 -w0 spire/conf/server/dummy_upstream_ca.key

Create a set of secrets named spire-server in the spire namespace by issuing the following command:

$ kubectl apply -f server-secrets.yaml

To confirm this command succeeded, look for the string “spire-server Opaque” in the output of the following command:

$ kubectl get secrets -n spire

Create Server Configmap

The server is configured in the Kubernetes configmap specified in server-configmap.yaml, which specifies a number of important directories, notably /run/spire/data, /run/spire/config, /run/spire/secrets, and /run/k8s-certs. These volumes are bound in when the server container is deployed.

The configmap also contains the bootstrap certificate dummy_upstream_ca.crt. As explained in the section Changes for a Production Environment, this is not appropriate for a production environment.

To create the server configmap, issue the following command:

$ kubectl apply -f server-configmap.yaml

Create Server Deployment

Before you deploy the server: If you are not running Kubernetes in a minikube cluster, you must introspect the running pod for kube-apiserver to determine which certificate Kubernetes uses to validate service accounts. This will either be the value of –service-account-key-file OR – if that is not provided to kube-apiserver – the value of –tls-private-key-file. Depending on which applies to you, set the k8s-sa-cert value to the certificate in use.

Deploy the server by applying the configuration server-deployment.yaml file:

$ kubectl apply -f server-deployment.yaml

This creates a deployment called spire-server in the spire namespace and starts up a spire-server pod, as demonstrated in the output of the following two commands:

The public key used to validate service accounts. As noted under Create Server Deployment you must take special steps to correctly set this value if you’re not running Kubernetes in a minikube cluster.

/run/k8s-certs/sa.pub

Create Server Service

Create the server service by applying the server-service.yaml configuration file:

$ kubectl apply -f server-service.yaml

Verify that the spire namespace now has a spire-server service in the spire namespace:

Section 5: Configure a Workload Container to Access SPIRE

In this step, you configure a workload container to access SPIRE. Specifically, you are configuring the workload container to access the Workload API UNIX domain socket.

The client-deployment.yaml file configures a no-op container using the spire-k8s docker image used for the server and agent. Examine the volumeMounts and volumes configuration stanzas to see how the UNIX domain socketagent.sock is bound in.

You can test that the agent socket is accessible from an application container by issuing the following sequence of commands:

Changes For A Production Environment

This tutorial is not designed for a production Kubernetes environment. A production environment requires adjustments to certain steps; these changes are summarized in this section.

The server uses a hostPath bind mount for persisting its keys and SQLite database. In a production deployment, a more robust and secure persistence mechanism is required.

This tutorial uses a bootstrap cert – dummy_upstream_ca.crt – and key from the SPIRE source tree. In a production deployment, you would generate a new key/certificate pair and implement certificate rotation.

In the Create Server Configmap step: set the the cluster name in the k8s_sat NodeAttestor entry to the name you provide in the agent-configmap.yaml configuration file.