From 7d1b026653e93f633ab52136d9393c0140d9534a Mon Sep 17 00:00:00 2001 From: Austin Norquist Date: Wed, 5 Nov 2025 14:57:12 -0800 Subject: [PATCH 1/2] Updated the StatefulSet second exercise --- .../9.2.1-stateful-sets.md | 68 +++++++++++++++++++ docs/_sidebar.md | 1 + .../ch9/statefulsets/counterapp/Dockerfile | 18 +++++ .../ch9/statefulsets/counterapp/package.json | 13 ++++ .../ch9/statefulsets/counterapp/server.js | 64 +++++++++++++++++ .../ch9/statefulsets/counterapp/src/app.js | 19 ++++++ .../statefulsets/counterapp/src/index.html | 26 +++++++ .../ch9/statefulsets/counterapp/src/style.css | 35 ++++++++++ 8 files changed, 244 insertions(+) create mode 100644 docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md create mode 100644 examples/ch9/statefulsets/counterapp/Dockerfile create mode 100644 examples/ch9/statefulsets/counterapp/package.json create mode 100644 examples/ch9/statefulsets/counterapp/server.js create mode 100644 examples/ch9/statefulsets/counterapp/src/app.js create mode 100644 examples/ch9/statefulsets/counterapp/src/index.html create mode 100644 examples/ch9/statefulsets/counterapp/src/style.css diff --git a/docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md b/docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md new file mode 100644 index 00000000..50df4f46 --- /dev/null +++ b/docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md @@ -0,0 +1,68 @@ +--- +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 ; k3d cluster create `. + +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= -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. + +?> Notice that deleting the pod may take a while to actually terminate. Take note on why you think this is the case. + +## 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 ; k3d cluster create `. + +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 + +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. + +## 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`? diff --git a/docs/_sidebar.md b/docs/_sidebar.md index dcbe9d8c..5298a03f 100644 --- a/docs/_sidebar.md +++ b/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) diff --git a/examples/ch9/statefulsets/counterapp/Dockerfile b/examples/ch9/statefulsets/counterapp/Dockerfile new file mode 100644 index 00000000..eaa21372 --- /dev/null +++ b/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"] diff --git a/examples/ch9/statefulsets/counterapp/package.json b/examples/ch9/statefulsets/counterapp/package.json new file mode 100644 index 00000000..f5472b0f --- /dev/null +++ b/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" + } +} diff --git a/examples/ch9/statefulsets/counterapp/server.js b/examples/ch9/statefulsets/counterapp/server.js new file mode 100644 index 00000000..62f02fb6 --- /dev/null +++ b/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}`); +}); diff --git a/examples/ch9/statefulsets/counterapp/src/app.js b/examples/ch9/statefulsets/counterapp/src/app.js new file mode 100644 index 00000000..02d98a84 --- /dev/null +++ b/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(); +}); diff --git a/examples/ch9/statefulsets/counterapp/src/index.html b/examples/ch9/statefulsets/counterapp/src/index.html new file mode 100644 index 00000000..1a3bd1fc --- /dev/null +++ b/examples/ch9/statefulsets/counterapp/src/index.html @@ -0,0 +1,26 @@ + + + + + + Counter + + + +
+
+
+

Counter

+
+
+
pod: …
+
+
+
0
+ +
+
+
+ + + diff --git a/examples/ch9/statefulsets/counterapp/src/style.css b/examples/ch9/statefulsets/counterapp/src/style.css new file mode 100644 index 00000000..6da935d0 --- /dev/null +++ b/examples/ch9/statefulsets/counterapp/src/style.css @@ -0,0 +1,35 @@ +* { box-sizing: border-box; } +:root { + --bg: #0f1419; + --card: #1a1f2e; + --text: #e5e7eb; + --muted: #9ca3af; + --liatrio-green: #24AE1D; + --liatrio-green-light: #2ec725; + --liatrio-green-selection: #c3e788; + --pill: #1f2937; +} +html, body { height: 100%; } +body { + margin: 0; + font-family: 'Open Sans', ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica Neue, Arial, sans-serif; + background: radial-gradient(1000px 600px at 20% 10%, rgba(36,174,29,0.12), transparent), + radial-gradient(800px 500px at 80% 30%, rgba(36,174,29,0.08), transparent), + var(--bg); + color: var(--text); +} +.container { min-height: 100%; display: grid; place-items: center; padding: 24px; } +.card { + width: 100%; max-width: 480px; background: var(--card); border: 1px solid rgba(36,174,29,0.15); + border-radius: 16px; padding: 28px; box-shadow: 0 10px 30px rgba(0,0,0,0.35); +} +.header { text-align: center; margin-bottom: 18px; } +.header h1 { margin: 0 0 4px; font-size: 26px; letter-spacing: 0.2px; color: var(--liatrio-green-light); } +.subtitle { margin: 0; color: var(--muted); font-size: 14px; } +.status { display: flex; justify-content: center; margin: 6px 0 16px; } +.pill { background: var(--pill); color: var(--liatrio-green-selection); border: 1px solid rgba(36,174,29,0.2); padding: 6px 10px; border-radius: 999px; font-size: 12px; font-weight: 500; } +.counter { display: grid; gap: 16px; justify-items: center; padding: 8px 0 6px; } +.count { font-size: 64px; font-weight: 700; letter-spacing: 1px; color: var(--liatrio-green); } +.btn { background: var(--liatrio-green); color: white; border: none; padding: 12px 16px; border-radius: 10px; font-weight: 600; cursor: pointer; font-size: 16px; transition: background 0.2s ease; } +.btn:hover { background: var(--liatrio-green-light); } +footer { margin-top: 16px; text-align: center; color: var(--muted); font-size: 12px; } From c87ea8d19da698cdd4d5b0bd32e77c4accbd7bde Mon Sep 17 00:00:00 2001 From: Joshua Burns Date: Wed, 3 Dec 2025 16:21:38 -0800 Subject: [PATCH 2/2] docs(kubernetes): enhance StatefulSets exercise to highlight Deployment limitations for stateful apps --- .../6.4-pairprogramming.md | 2 +- .../9.2.1-stateful-sets.md | 27 +++++- docs/README.md | 96 +++++++++++-------- 3 files changed, 77 insertions(+), 48 deletions(-) diff --git a/docs/6-software-development-practices/6.4-pairprogramming.md b/docs/6-software-development-practices/6.4-pairprogramming.md index 87b1b74b..e8436c7d 100644 --- a/docs/6-software-development-practices/6.4-pairprogramming.md +++ b/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: diff --git a/docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md b/docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md index 50df4f46..bb01ae80 100644 --- a/docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md +++ b/docs/9-kubernetes-container-orchestration/9.2.1-stateful-sets.md @@ -41,20 +41,18 @@ kubectl get pods -l app= -o name | xargs -I {} sh -c 'echo {} 5. Delete one of the pods from the `StatefulSet`, run the command again and observe the output. -?> Notice that deleting the pod may take a while to actually terminate. Take note on why you think this is the case. - ## 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. +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 ; k3d cluster create `. +`unset KUBECONFIG; k3d cluster delete ; k3d cluster create `. 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 +?> `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. @@ -62,6 +60,25 @@ Navigate to `examples/ch9/statefulsets/counterapp/`, there is a Dockerfile and a ?> 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? diff --git a/docs/README.md b/docs/README.md index ec7af5d5..7fc70f6f 100644 --- a/docs/README.md +++ b/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