Updated the StatefulSet second exercise (#781)

* Updated the StatefulSet second exercise

* docs(kubernetes): enhance StatefulSets exercise to highlight Deployment limitations for stateful apps

---------

Co-authored-by: Joshua Burns <joshua.burns@liatrio.com>

Author: n0rq1

docs/6-software-development-practices/6.4-pairprogramming.md

@@ -4,7 +4,7 @@ docs/6-software-development-practices/6.4-pairprogramming.md:
   estReadingMinutes: 20
   exercises:
     -
-      name: Pair Programing
+      name: Pair Programming
       description: Using 'Live Share' or some equivillant try pair programming a 'Hello World' app in the language of your choice
       estMinutes: 30
       technologies:

docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md

@@ -0,0 +1,85 @@
+---
+docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md:
+  category: Container Orchestration
+  estReadingMinutes: 10
+  exercises:
+    -
+      name: Stateful Sets
+      description: Create a simple StatefulSet in Kubernetes, understand the lifecycle of StatefulSets.
+      estMinutes: 120
+      technologies:
+      - Kubernetes
+      - StatefulSets
+---
+
+# 9.2.1 Stateful Sets
+
+StatefulSets are a type of workload controller in Kubernetes specifically designed to manage stateful applications—applications that require persistent storage and stable identities for their Pods. Unlike Deployments, where Pods are interchangeable and ephemeral, StatefulSets provide “sticky” identities and guarantees that each Pod maintains a unique, stable network identity and persistent storage across rescheduling, scaling, and updates.
+
+This stickiness is crucial for stateful workloads such as databases, message queues, and distributed systems, where each instance must maintain its state consistently and be reachable by other Pods in a predictable manner.
+
+For more information, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/).
+
+## Exercise 1 - Stateful Sets
+
+1. Destroy and recreate a new cluster.
+`unset KUBECONFIG; k3d cluster delete <cluster-name>; k3d cluster create <cluster-name>`.
+
+2. Copy the contents of `examples/ch9/volumes/random-num-pod.yaml` into a new file called `examples/ch9/statefulsets/random-num-statefulset.yaml` and modify it to use a `StatefulSet` resource instead of a `Pod` resource. Set the number of replicas to 3.
+
+> To prevent the container from dying and restarting, add a sleep command to the container:
+ `args: ["shuf -i 0-100 -n 1 >> /opt/number.out; sleep 10000"]`.
+
+?> [VolumeClaimTemplates](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#volume-claim-templates) give each statefulset replica an automatically managed, per-pod persistent volume that sticks to the Pod’s ordinal, avoids manual PVC creation, and prevents unsafe volume sharing.
+
+3. Apply the `StatefulSet` to the cluster.
+
+4. Exec into each pod and view the contents of `/opt/number.out` or use the command:
+```shell
+kubectl get pods -l app=<statefulset-label> -o name | xargs -I {} sh -c 'echo {}; kubectl exec {} -- cat /opt/number.out'
+```
+
+5. Delete one of the pods from the `StatefulSet`, run the command again and observe the output.
+
+## Exercise 2 - More Stateful Sets
+
+Navigate to `examples/ch9/statefulsets/counterapp/`, there is a Dockerfile and a directory `src` which contains a simple web application that displays a counter and the name of the pod it's running on.
+
+1. Destroy and recreate a new cluster.
+`unset KUBECONFIG; k3d cluster delete <cluster-name>; k3d cluster create <cluster-name>`.
+
+2. Create a `StatefulSet` for the counterapp.
+
+3. Create a `Service` for the `StatefulSet`.
+
+?> `StatefulSets` are a bit unique and require a `Headless Service` to function properly. This is because `StatefulSets` require stable network identities for their pods, and a `Headless Service` provides this by not load balancing traffic across pods, but instead routing traffic to specific pods based on their stable network identity. For more information: [https://kubernetes.io/docs/concepts/services-networking/service/#headless-services](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services)
+
+4. Apply both the `StatefulSet` and `Service` to the cluster.
+
+5. Port forward each pod, delete one of the pods and observe each instance of the counter app in your browser.
+
+?> Notice that deleting the pod may take a while to actually terminate. Take note on why you think this is the case.
+
+6. Clean up the cluster by deleting the `StatefulSet`, `Service`, and any dangling PV/PVCs.
+
+7. Create an analogous `Deployment` with 3 replicas and a dynamically provisioned `PersistentVolumeClaim`.
+
+   a. Apply the `Deployment` and `PVC` to the cluster.
+
+   b. Port forward to each pod and observe the counter app in your browser. What happens to the counter value across different pods?
+
+   c. Delete one of the pods and observe:
+      - How quickly does the pod terminate compared to the StatefulSet?
+      - What is the new pod's name?
+      - What happened to the counter value?
+
+   d. Scale the Deployment to 5 replicas, then back down to 2. Which pods were removed? How does this compare to StatefulSet scaling behavior?
+
+8. Based on your observations, research how you might achieve per-replica persistent storage using only Deployments. What trade-offs or additional complexity would be required?
+
+?> Consider the differences in pod naming, storage behavior, scaling order, and data continuity. Why might these differences matter for stateful applications?
+
+## Deliverables
+
+- Look into other workload controllers (Deployments, ReplicaSets, DaemonSets, etc.), what are the differences between them? Why might you use one over the other?
+- What are some downsides to using `StatefulSets`?

docs/README.md

@@ -801,7 +801,7 @@ docs/6-software-development-practices/6.4-pairprogramming.md:
   category: Agile Development
   estReadingMinutes: 20
   exercises:
-    - name: Pair Programing
+    - name: Pair Programming
       description: >-
         Using 'Live Share' or some equivillant try pair programming a 'Hello
         World' app in the language of your choice
@@ -1103,6 +1103,47 @@ docs/8-infrastructure-configuration-management/8.1.3-terraform-modules.md:
       technologies:
         - Terraform
         - AWS S3
+docs/8-infrastructure-configuration-management/8.2-ansible.md:
+  category: Infrastructure as Code
+  estReadingMinutes: 15
+  exercises:
+    - name: Vagrant and Ansible
+      description: >-
+        Provision a virtual machine and install a GitHub self-hosted runner
+        using Ansible as a provisioner in Vagrant.
+      estMinutes: 300
+      technologies:
+        - Ansible
+        - Vagrant
+        - GitHub self-hosted runner
+    - name: Idempotency
+      description: >-
+        Provision a virtual machine and install a GitHub self-hosted runner
+        using Ansible as a provisioner in Vagrant while maintaining idempotency.
+      estMinutes: 300
+      technologies:
+        - Ansible
+        - Vagrant
+        - GitHub self-hosted runner
+    - name: Ansible and AWS EC2
+      description: >-
+        Provision an AWS EC2 instance and install a GitHub self-hosted runner
+        using Ansible.
+      estMinutes: 300
+      technologies:
+        - Ansible
+        - AWS EC2
+        - GitHub self-hosted runner
+    - name: Terraform and Ansible
+      description: >-
+        Provision an EC2 instance using Terraform and install a GitHub
+        self-hosted runner with Ansible.
+      estMinutes: 360
+      technologies:
+        - Terraform
+        - Ansible
+        - AWS EC2
+        - GitHub self-hosted runner
 docs/8-infrastructure-configuration-management/8.3-terraform-providers.md:
   category: Infrastructure as Code
   estReadingMinutes: 20
@@ -1147,47 +1188,6 @@ docs/8-infrastructure-configuration-management/8.3-terraform-providers.md:
       technologies:
         - Terraform
         - Go
-docs/8-infrastructure-configuration-management/8.2-ansible.md:
-  category: Infrastructure as Code
-  estReadingMinutes: 15
-  exercises:
-    - name: Vagrant and Ansible
-      description: >-
-        Provision a virtual machine and install a GitHub self-hosted runner
-        using Ansible as a provisioner in Vagrant.
-      estMinutes: 300
-      technologies:
-        - Ansible
-        - Vagrant
-        - GitHub self-hosted runner
-    - name: Idempotency
-      description: >-
-        Provision a virtual machine and install a GitHub self-hosted runner
-        using Ansible as a provisioner in Vagrant while maintaining idempotency.
-      estMinutes: 300
-      technologies:
-        - Ansible
-        - Vagrant
-        - GitHub self-hosted runner
-    - name: Ansible and AWS EC2
-      description: >-
-        Provision an AWS EC2 instance and install a GitHub self-hosted runner
-        using Ansible.
-      estMinutes: 300
-      technologies:
-        - Ansible
-        - AWS EC2
-        - GitHub self-hosted runner
-    - name: Terraform and Ansible
-      description: >-
-        Provision an EC2 instance using Terraform and install a GitHub
-        self-hosted runner with Ansible.
-      estMinutes: 360
-      technologies:
-        - Terraform
-        - Ansible
-        - AWS EC2
-        - GitHub self-hosted runner
 docs/9-kubernetes-container-orchestration/9.1-kubectl-ref.md:
   category: Container Orchestration
   estReadingMinutes: 120
@@ -1212,6 +1212,18 @@ docs/9-kubernetes-container-orchestration/9.2-volumes.md:
       technologies:
         - Kubernetes
         - Jenkins
+docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md:
+  category: Container Orchestration
+  estReadingMinutes: 10
+  exercises:
+    - name: Stateful Sets
+      description: >-
+        Create a simple StatefulSet in Kubernetes, understand the lifecycle of
+        StatefulSets.
+      estMinutes: 120
+      technologies:
+        - Kubernetes
+        - StatefulSets
 docs/9-kubernetes-container-orchestration/9.3-probes.md:
   category: Container Orchestration
   estReadingMinutes: 10

docs/_sidebar.md

@@ -140,6 +140,7 @@
   - [9.1.4 - Cluster Management](9-kubernetes-container-orchestration/9.1.4-cluster-management.md)
   - [9.1.5 - Kubectl Settings and Usage](9-kubernetes-container-orchestration/9.1.5-kubectl-settings-and-usage.md)
 - [9.2 - Volumes](9-kubernetes-container-orchestration/9.2-volumes.md)
+  - [9.2.1 - Stateful Sets](9-kubernetes-container-orchestration/9.2.1-stateful-sets.md)
 - [9.3 - Probes](9-kubernetes-container-orchestration/9.3-probes.md)
 - [9.4 - RBAC](9-kubernetes-container-orchestration/9.4-rbac.md)
 - [9.5 - HPAs](9-kubernetes-container-orchestration/9.5-hpas.md)

examples/ch9/statefulsets/counterapp/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+
+RUN npm install --omit=dev
+
+COPY server.js ./
+COPY src/ ./src/
+
+RUN mkdir -p /data && chown -R node:node /data
+
+USER node
+
+EXPOSE 3000
+
+CMD ["npm", "start"]

examples/ch9/statefulsets/counterapp/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "counterapp",
+  "version": "1.0.0",
+  "private": true,
+  "description": "StatefulSet demo counter app with persistent per-pod state",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "express": "^4.18.2"
+  }
+}

examples/ch9/statefulsets/counterapp/server.js

@@ -0,0 +1,64 @@
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+const DATA_DIR = process.env.DATA_DIR || '/data';
+const DATA_FILE = path.join(DATA_DIR, 'counter.json');
+const POD_NAME = process.env.POD_NAME || os.hostname();
+
+app.use(express.json());
+app.use(express.static(path.join(__dirname, 'src')));
+app.get('/', (_req, res) => {
+  res.sendFile(path.join(__dirname, 'src', 'index.html'));
+});
+
+function readCounter() {
+  try {
+    if (!fs.existsSync(DATA_DIR)) {
+      fs.mkdirSync(DATA_DIR, { recursive: true });
+    }
+    if (!fs.existsSync(DATA_FILE)) {
+      fs.writeFileSync(DATA_FILE, JSON.stringify({ count: 0 }), 'utf8');
+      return 0;
+    }
+    const raw = fs.readFileSync(DATA_FILE, 'utf8');
+    const obj = JSON.parse(raw);
+    return typeof obj.count === 'number' ? obj.count : 0;
+  } catch (e) {
+    return 0;
+  }
+}
+
+function writeCounter(value) {
+  try {
+    fs.writeFileSync(DATA_FILE, JSON.stringify({ count: value }), 'utf8');
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+app.get('/healthz', (_req, res) => {
+  res.status(200).send('ok');
+});
+
+app.get('/api/state', (_req, res) => {
+  const count = readCounter();
+  res.json({ count, podName: POD_NAME });
+});
+
+app.post('/api/increment', (_req, res) => {
+  let count = readCounter();
+  count += 1;
+  if (!writeCounter(count)) {
+    return res.status(500).json({ error: 'failed_to_persist' });
+  }
+  res.json({ count, podName: POD_NAME });
+});
+
+app.listen(PORT, () => {
+  console.log(`server listening on ${PORT} as ${POD_NAME}`);
+});

examples/ch9/statefulsets/counterapp/src/app.js

@@ -0,0 +1,19 @@
+async function fetchState() {
+  const res = await fetch('/api/state');
+  if (!res.ok) return;
+  const data = await res.json();
+  document.getElementById('count').textContent = data.count;
+  document.getElementById('podName').textContent = `pod: ${data.podName}`;
+}
+
+async function increment() {
+  const res = await fetch('/api/increment', { method: 'POST' });
+  if (!res.ok) return;
+  const data = await res.json();
+  document.getElementById('count').textContent = data.count;
+}
+
+window.addEventListener('DOMContentLoaded', () => {
+  document.getElementById('incrementBtn').addEventListener('click', increment);
+  fetchState();
+});

examples/ch9/statefulsets/counterapp/src/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Counter</title>
+  <link rel="stylesheet" href="/style.css" />
+</head>
+<body>
+  <div class="container">
+    <div class="card">
+      <div class="header">
+        <h1>Counter</h1>
+      </div>
+      <div class="status">
+        <div class="pill" id="podName">pod: …</div>
+      </div>
+      <div class="counter">
+        <div class="count" id="count">0</div>
+        <button id="incrementBtn" class="btn">Increment</button>
+      </div>
+    </div>
+  </div>
+  <script src="/app.js"></script>
+</body>
+</html>