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 new file mode 100644 index 00000000..bb01ae80 --- /dev/null +++ b/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 ; 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. + +## 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](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`? 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 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; }