Improve examples

README.md

@@ -4,7 +4,7 @@
 
 Hello, and welcome to SPIRE examples!
 
-This repository houses various SPIFFE/SPIRE deployment and integration examples. All examples are self contained, and come with instructions on how to use them.
+This repository houses various SPIFFE/SPIRE deployment and integration examples. All examples are self-contained, and come with instructions on how to use them.
 
 The SPIRE project is growing rapidly, and new features are released often. In order to ensure the accuracy of accompanying documentation, each example is written against a specific version of SPIRE. All examples are regularly tested against the stated SPIRE version, but are likely to work with newer versions as well.
 

examples/envoy/README.md

@@ -43,7 +43,7 @@ Open up a browser to http://localhost:8080 to test out:
 - mTLS connection between Web and Echo servers via Envoy
 - TLS connection between Web and Echo servers via Envoy
 
-**NOTE** It may take a 30 seconds or so for Envoy to reconnect to upstream
+**NOTE** It may take 30 seconds or so for Envoy to reconnect to upstream
 after the registration entries are created.
 
 ## Clean up

examples/k8s/advanced/README.md

@@ -9,4 +9,9 @@ The Kubernetes cluster is running SPIRE and spiffe-helper, and spiffe-helper is
 to push certificates into a Postgres database for authentication. 
 
 Because spiffe-helper has to be inside the same image as the Postgres server, these scripts
-create a new image containg Postgres and spiffe-helper.
+create a new image containing Postgres and spiffe-helper.
+
+
+> **Deprecation Note**
+> k8s-workload-registrar is deprecated, we recommend using the [spire-controller-manager](https://github.com/spiffe/spire-controller-manager),
+> which is a Kubernetes controller used to manage registration entries and federation. A demo can be found [here](https://github.com/spiffe/spire-controller-manager/tree/main/demo)

examples/k8s/postgres/README.md

@@ -27,7 +27,7 @@ failures and scalability.
 + **stateless** - To run the SPIRE server stateless (as in this example), the
   `UpstreamAuthority` plugin needs to be used.
 + **stateful** - To run the SPIRE server stateful, the directory specified in
-  `data_dir` must be persistent (such as in the [simple sat example](../simple_sat)
+  `data_dir` must be persistent (such as in the [simple sat example](../simple_sat))
   where a StatefulSet and PersistentVolumeClaim are used.
 
 In this example deployment, the SPIRE server is stateless, using the example
@@ -69,3 +69,8 @@ Start the agent DaemonSet:
 ```
 $ kubectl apply -f spire-agent.yaml
 ```
+
+## Test
+
+Simply run `./test.sh`, this script will start a cluster using [kind](https://kind.sigs.k8s.io/), deploy the postgres database,
+spire server and agent, and run a simple test to verify the node attestation process.

examples/k8s/postgres/spire-agent.yaml

@@ -1,3 +1,4 @@
+# Service account for the spire-agent
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -6,6 +7,7 @@ metadata:
 
 ---
 
+# Config map for the spire-agent, which contains the agent configuration file and the trust bundle certificate
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -73,6 +75,7 @@ data:
 
 ---
 
+# Daemonset for spire-agent
 apiVersion: apps/v1
 kind: DaemonSet
 metadata:

examples/k8s/postgres/spire-database.yaml

@@ -1,10 +1,12 @@
+# Create a namespace for the SPIRE Server and Agent
 apiVersion: v1
 kind: Namespace
 metadata:
   name: spire
 
 ---
 
+# Service account for the spire-database
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -13,6 +15,7 @@ metadata:
 
 ---
 
+# StatefulSet for the spire-database
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
@@ -71,6 +74,7 @@ spec:
 
 ---
 
+# Service for the spire-database, so that the spire-server can connect to it
 kind: Service
 apiVersion: v1
 metadata:

examples/k8s/postgres/spire-server.yaml

@@ -1,3 +1,4 @@
+# Service account for the spire-server
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -6,6 +7,36 @@ metadata:
 
 ---
 
+# Create cluster role allowed to create resource "tokenreviews" in API group "authentication.k8s.io".
+# This is required by the server to authenticate agents using [Token Review API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/)
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: spire-server
+rules:
+  - apiGroups: [ "authentication.k8s.io" ]
+    resources: [ "tokenreviews" ]
+    verbs: [ "create" ]
+
+---
+
+# Bind the spire-server service account to the role
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: spire-server
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: spire-server
+subjects:
+  - kind: ServiceAccount
+    name: spire-server
+    namespace: spire
+
+---
+
+# Create the upstream authority private key
 apiVersion: v1
 kind: Secret
 metadata:
@@ -17,6 +48,7 @@ data:
 
 ---
 
+# Config map for the spire-server, which contains the server configuration file
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -50,7 +82,7 @@ data:
         plugin_data {
           clusters = {
             "demo-cluster" = {
-              service_account_key_file = "/run/k8s-certs/sa.pub"
+              use_token_review_api_validation = true
               service_account_allow_list = ["spire:spire-agent"]
             }
           }
@@ -94,6 +126,7 @@ data:
 
 ---
 
+# Deployment for the spire-server
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -133,9 +166,6 @@ spec:
             - name: spire-secrets
               mountPath: /run/spire/secrets
               readOnly: true
-            - name: k8s-sa-cert
-              mountPath: /run/k8s-certs/sa.pub
-              readOnly: true
           livenessProbe:
             httpGet:
               path: /live
@@ -157,13 +187,10 @@ spec:
         - name: spire-secrets
           secret:
             secretName: spire-server
-        - name: k8s-sa-cert
-          hostPath:
-            path: /var/lib/minikube/certs/sa.pub
-            type: File
 
 ---
 
+# Create the spire-server service binding to the spire-server deployment
 apiVersion: v1
 kind: Service
 metadata:

examples/k8s/postgres/test.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 bold=$(tput bold) || true
 norm=$(tput sgr0) || true
@@ -9,58 +9,72 @@ green=$(tput setaf 2) || true
 yellow=$(tput setaf 3) || true
 
 fail() {
-	echo "${red}$*${norm}."
-	exit 1
+  echo "${red}$*${norm}."
+  exit 1
+}
+
+create-cluster() {
+  if ! kind get clusters | grep demo-cluster; then
+    kind create cluster -n demo-cluster || fail "Failed to create cluster"
+  fi
+}
+
+delete-cluster() {
+  if [ "${KEEP_CLUSTER:-0}" -eq 0 ]; then
+    kind delete cluster -n demo-cluster >/dev/null
+  fi
 }
 
 delete-ns() {
-	echo "${bold}Cleaning up...${norm}"
-    kubectl delete --ignore-not-found namespace spire > /dev/null
+  echo "${bold}Cleaning up...${norm}"
+  kubectl delete --ignore-not-found namespace spire >/dev/null
 }
 
 cleanup() {
-    if [ -z "${GOOD}" ]; then
-        echo "${yellow}Dumping statefulset/spire-database logs...${norm}"
-        kubectl -nspire logs statefulset/spire-database --all-containers
-        echo "${yellow}Dumping deployment/spire-server logs...${norm}"
-        kubectl -nspire logs deployment/spire-server --all-containers
-        echo "${yellow}Dumping daemonset/spire-agent logs...${norm}"
-        kubectl -nspire logs daemonset/spire-agent --all-containers
-    fi
-    delete-ns
-    if [ -n "${GOOD}" ]; then
-        echo "${green}Success.${norm}"
-    else
-        echo "${red}Failed.${norm}"
-    fi
+  delete-cluster
+  if [ -z "${GOOD}" ]; then
+    echo "${yellow}Dumping statefulset/spire-database logs...${norm}"
+    kubectl -nspire logs statefulset/spire-database --all-containers
+    echo "${yellow}Dumping deployment/spire-server logs...${norm}"
+    kubectl -nspire logs deployment/spire-server --all-containers
+    echo "${yellow}Dumping daemonset/spire-agent logs...${norm}"
+    kubectl -nspire logs daemonset/spire-agent --all-containers
+  fi
+  delete-ns
+  if [ -n "${GOOD}" ]; then
+    echo "${green}Success.${norm}"
+  else
+    echo "${red}Failed.${norm}"
+  fi
 }
 
 trap cleanup EXIT
 
 echo "${bold}Preparing environment...${norm}"
+create-cluster
 delete-ns
 kubectl create namespace spire
 
 echo "${bold}Applying configuration...${norm}"
 kubectl apply -k "${DIR}"
 
 LOGLINE="Agent attestation request completed"
-for ((i=0;i<120;i++)); do
-    if ! kubectl -nspire rollout status deployment/spire-server; then
-        sleep 1
-        continue
-    fi
-    if ! kubectl -nspire rollout status daemonset/spire-agent; then
-        sleep 1
-        continue
-    fi
-    if ! kubectl -nspire logs deployment/spire-server -c spire-server | grep -e "$LOGLINE" ; then
-        sleep 1
-        continue
-    fi
-    echo "${bold}Node attested.${norm}"
-    GOOD=1
-    exit 0
+for ((i = 0; i < 120; i++)); do
+  if ! kubectl -nspire rollout status deployment/spire-server; then
+    sleep 1
+    continue
+  fi
+  if ! kubectl -nspire rollout status daemonset/spire-agent; then
+    sleep 1
+    continue
+  fi
+  if ! kubectl -nspire logs deployment/spire-server -c spire-server | grep -e "$LOGLINE"; then
+    sleep 1
+    continue
+  fi
+  echo "${bold}Node attested.${norm}"
+  GOOD=1
+  exit 0
 done
 
 echo "${red}Timed out waiting for node to attest.${norm}"

examples/k8s/simple_psat/README.md

@@ -8,27 +8,10 @@ This configuration is an example of a simple SPIRE 1.5.1 deployment for Kubernet
 
 Both SPIRE agent and server run in the **spire** namespace, using service
 accounts of **spire-server** and **spire-agent**.
-Also RBAC authorization policies are set in order to guarantee access to certain API server resources.
+Also, RBAC authorization policies are set in order to guarantee access to certain API server resources.
 
 ## Usage
 
-### Configuration
-
-The following flags must be passed to the Kubernetes API server to properly run this PSAT attestor example:
-+ `service-account-signing-key-file`
-+ `service-account-key-file`
-+ `service-account-issuer`
-+ `service-account-api-audiences`
-
-If you are using minikube, make sure it is started as follows:
-```
-minikube start  --driver=virtualbox \
-                --extra-config=apiserver.authorization-mode=Node,RBAC \
-                --extra-config=apiserver.service-account-signing-key-file=/var/lib/minikube/certs/sa.key \
-                --extra-config=apiserver.service-account-key-file=/var/lib/minikube/certs/sa.pub \
-                --extra-config=apiserver.service-account-issuer=api \
-                --extra-config=apiserver.service-account-api-audiences=api,spire-server
-```
 
 ### Deployment
 
@@ -45,3 +28,8 @@ $ kubectl apply -f spire-agent.yaml
 ```
 
 The agent should automatically attest to SPIRE server.
+
+## Test
+
+Simply run `./test.sh`, this script will start a cluster using [kind](https://kind.sigs.k8s.io/), deploy spire server and
+agent, and run a simple test to verify the node attestation process using PSAT NodeAttestor.

examples/k8s/simple_psat/spire-agent.yaml

@@ -1,3 +1,4 @@
+# Service Account for spire-agent
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -34,6 +35,7 @@ roleRef:
 
 ---
 
+# Config map for the spire-agent, which contains the agent configuration file and the trust bundle certificate
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -101,6 +103,7 @@ data:
 
 ---
 
+# DaemonSet for the spire-agent
 apiVersion: apps/v1
 kind: DaemonSet
 metadata:

examples/k8s/simple_psat/spire-server.yaml

@@ -1,10 +1,12 @@
+# Create a namespace for spire-server
 apiVersion: v1
 kind: Namespace
 metadata:
   name: spire
 
 ---
 
+# Service account for the spire-server
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -44,6 +46,7 @@ roleRef:
 
 ---
 
+# Create the upstream authority private key
 apiVersion: v1
 kind: Secret
 metadata:
@@ -55,6 +58,7 @@ data:
 
 ---
 
+# Config map for the spire-server, which contains the server configuration file
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -130,6 +134,7 @@ data:
 
 ---
 
+# Stateful set for the spire-server
 apiVersion: apps/v1
 kind: StatefulSet
 metadata: