feat(root): author networking and configuration curriculum

root-07-m03-services-and-service-discovery — a new, full gold-standard- pattern module: the Service/Endpoints/DNS request path, choosing the right Service type. Lesson, demonstration (a Service with zero Endpoints — the single fastest diagnostic check for this failure class), knowledge check, guided exercise (ClusterIP vs. NodePort vs. LoadBalancer for three real components), a real Lab (expose-service-basics), and a reflection. root-07-m04-ingress-networkpolicy-foundations — a new PARTIAL module: Ingress and NetworkPolicy at the architectural level (the security- control framing of NetworkPolicy is deliberately deferred to ROOT 09). Lesson + knowledge check + real Labs (ingress-task, network-policy). Co-Authored-By: Claude Sonnet 5 <[email protected]>
2026-08-26 09:06:19 -05:00
parent 86ea035e9b
commit dbcc210889
8 changed files with 481 additions and 0 deletions
@@ -0,0 +1,87 @@
+# The Service/Endpoints/DNS Request Path
+
+## The problem: Pod IPs are not stable
+
+Every Pod gets its own IP address, but that IP is NOT durable — when a Pod is replaced (a
+rollout, a crash recovery, a reschedule), the new Pod gets a brand new IP. If another part of
+your application had that old IP hardcoded, it would silently start talking to nothing. This is
+the exact problem in `expose-service-basics`'s scenario: "other pods cannot reliably connect
+because pod IPs change when they restart."
+
+## A Service: a stable address in front of a moving set of Pods
+
+A Service is a stable virtual IP and DNS name that automatically routes to whichever Pods
+currently match its label selector — regardless of how many there are or how often they change.
+You never talk to a Pod's IP directly in normal operation; you talk to the Service, and the
+Service's Endpoints (a live, continuously-updated list of the matching Pods' IPs) determines
+where traffic actually goes.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: redis-svc
+spec:
+  selector:
+    app: redis        # <- matches Pods by label, same mechanism from ROOT 05
+  ports:
+  - port: 6379
+```
+
+This is the same label-selector mechanism you learned in ROOT 05 — a Service doesn't know or
+care about specific Pod names, only which Pods currently carry a matching label.
+
+## The three Service types you'll use most
+
+- **ClusterIP** (the default) — reachable only from inside the cluster. Use this for
+  internal-only communication, like one microservice talking to another or to a database.
+- **NodePort** — additionally exposes the Service on a static port on every node's own IP,
+  reachable from outside the cluster. Mostly used for development/testing or when there's no
+  cloud load balancer available.
+- **LoadBalancer** — asks the cloud provider to provision a real external load balancer pointed
+  at the Service. This is the standard way to expose something to the public internet on a
+  cloud-hosted cluster.
+
+Choosing wrong isn't just a style preference — a ClusterIP Service is architecturally
+unreachable from outside the cluster no matter how correctly everything else is configured.
+
+## DNS: how Pods actually find a Service by name
+
+Every Service automatically gets a DNS name inside the cluster
+(`<service-name>.<namespace>.svc.cluster.local`, or usually just `<service-name>` from within
+the same Namespace) — this is why application code can use a plain hostname like `redis-svc`
+instead of an IP address at all. Kubernetes' internal DNS resolves that name to the Service's
+stable virtual IP, which then routes to whichever Pods are currently healthy.
+
+## The full request path, end to end
+
+```
+Client  ->  DNS lookup "redis-svc"  ->  Service's stable virtual IP
+        ->  Service consults its Endpoints (live list of matching, ready Pods)
+        ->  traffic forwarded to one of those Pod IPs
+```
+
+Every one of these steps can fail independently, which is exactly why "the app can't reach
+redis" requires checking each layer rather than guessing — the next activity shows you what
+that looks like when the Endpoints layer is empty.
+
+## Instructor Notes
+
+**Approximate timing:** 15 minutes read, 10-12 minutes live with the request-path diagram.
+
+**Demo plan:** Before the next activity, it's worth live-running `kubectl get endpoints
+<service-name>` against a healthy Service so students see a populated Endpoints list before
+they see an empty one in the demonstration.
+
+**Likely misconceptions to watch for:**
+- Students often think a Service "is" a load balancer process running somewhere. It's closer to
+  a routing rule maintained by `kube-proxy` on every node — worth clarifying that there's no
+  single "Service Pod" to go find and debug.
+- ClusterIP vs. NodePort vs. LoadBalancer is sometimes memorized without the "why" — the
+  knowledge check's Service-type question is designed to test the underlying reasoning, not
+  just recall.
+
+**Discussion question:** "If a Service's selector matches zero Pods, does the Service itself
+fail to exist?" (Answer: no — the Service object exists fine; its Endpoints list is just empty,
+which looks like connection failure from the client's side without any error at the Service
+level itself. This is exactly the next activity's topic.)
@@ -0,0 +1,82 @@
+# Demonstration: A Service With Zero Endpoints
+
+This is one of the most common "it just doesn't work" incidents in real Kubernetes operation —
+and it produces no error message at all at the Service level.
+
+## The setup
+
+A Service `api-svc` selects Pods labeled `app: api`. A Deployment was recently updated and its
+Pods now carry the label `app: api-v2` instead (a rename during a refactor, deliberately or
+accidentally).
+
+## What you'd see from the client side
+
+```
+$ curl http://api-svc:8080/health
+curl: (7) Failed to connect to api-svc port 8080: Connection refused
+```
+
+Just a generic connection failure — nothing here says "your Service's selector doesn't match
+any Pods."
+
+## What the Service object itself shows
+
+```
+$ kubectl get service api-svc
+NAME      TYPE        CLUSTER-IP     PORT(S)    AGE
+api-svc   ClusterIP   10.96.34.201   8080/TCP   2h
+```
+
+Completely normal-looking. The Service exists, has a stable IP, is not in any kind of "error"
+state — because from the Service's own perspective, nothing is wrong. It's doing exactly what
+it's configured to do: route to whatever matches its selector, which currently happens to be
+nothing.
+
+## Where the real evidence is: Endpoints
+
+```
+$ kubectl get endpoints api-svc
+NAME      ENDPOINTS   AGE
+api-svc   <none>      2h
+```
+
+This is the actual signal. `<none>` means the Service's selector currently matches zero Pods —
+this is the single fastest check for "is this a Service-to-Pod mismatch" any time something
+reachable-in-principle looks like a connection failure.
+
+## Confirming the mismatch
+
+```
+$ kubectl get pods --show-labels
+NAME                     READY   STATUS    LABELS
+api-abc123                1/1    Running   app=api-v2
+```
+
+The Pod is healthy and running — `app=api-v2`, not `app=api`. The Service's selector
+(`app: api`) matches nothing, and nothing about the Pod itself is broken.
+
+## The general diagnostic shape
+
+`curl`/application-level connection failure tells you *that* something's wrong, but nothing
+about *where*. `kubectl get endpoints <service>` is the fastest way to distinguish "the Service
+has no matching Pods" from "the Pods exist and are ready but something else is wrong" —
+reach for it early whenever a Service-fronted connection fails for no obvious reason.
+
+## Instructor Notes
+
+**Demo script:** Live-create this exact mismatch (a Service with one selector, a Deployment
+with a slightly different label) and walk through `kubectl get service` -> `kubectl get
+endpoints` -> `kubectl get pods --show-labels` in front of the class, narrating what each
+command is and isn't telling you.
+
+**Approximate timing:** 8-10 minutes live; 5-7 minutes self-paced.
+
+**Common misconception to preempt:** students often check the Service object first and, seeing
+nothing obviously wrong, assume the problem must be elsewhere entirely (DNS, firewall, the
+application itself) — reinforce that `kubectl get endpoints` is the specific, fast check for
+this exact failure mode, before reaching for anything more complex.
+
+**Optional extension:** ask what `kubectl describe service api-svc` would additionally show
+compared to `kubectl get service` (answer: the same selector the Service is using, which lets
+you directly compare it against `kubectl get pods --show-labels`'s actual Pod labels side by
+side, rather than inferring the mismatch).
@@ -0,0 +1,47 @@
+# Knowledge Check: Services & Service Discovery
+
+---
+
+**1. A Deployment has three replicas but `kubectl get endpoints` shows `<none>` for its Service.
+Which part of the system should you inspect first, and why?**
+
+*Answer:* Compare the Service's selector (`kubectl describe service`) against the actual Pods'
+labels (`kubectl get pods --show-labels`) — a Service with a healthy backend Deployment but zero
+Endpoints almost always means the selector doesn't match the Pods' current labels, not that the
+Pods themselves are unhealthy.
+
+---
+
+**2. You need a microservice reachable ONLY from other services inside the same cluster, never
+from the public internet. Which Service type, and why not LoadBalancer?**
+
+*Answer:* ClusterIP — it's reachable only from inside the cluster by design, which is exactly
+the requirement. A LoadBalancer would provision a real external endpoint reachable from the
+public internet, which is more exposure than the requirement calls for, and depends on cloud
+provider support this scenario doesn't need.
+
+---
+
+**3. True or false: application code that connects to `redis-svc` by that plain hostname is
+relying on Kubernetes' internal DNS to resolve it.**
+
+*Answer:* True. Every Service automatically gets a DNS name; that's specifically what lets code
+use a stable hostname instead of hardcoding a Pod IP that could change at any time.
+
+---
+
+**4. A Service's Endpoints list is non-empty, but the application still can't connect. Does
+this rule out a Service-level problem entirely?**
+
+*Answer:* Not entirely — a non-empty Endpoints list means at least one Pod currently matches the
+selector, but the connection could still fail for other reasons (wrong port number on the
+Service, a NetworkPolicy blocking the traffic, the application inside the Pod not actually
+listening). A populated Endpoints list narrows the problem, it doesn't prove the whole path
+works.
+
+## Instructor Notes
+
+**Facilitation:** Question 1 is the single most transferable diagnostic habit from this module —
+worth explicitly calling out as "the first thing to check" for this entire class of problem.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,49 @@
+# Guided Exercise: Choosing the Right Service Type
+
+Paper-and-thinking exercise before the Lab.
+
+## The scenario
+
+You're deploying three components for a class project on a cloud-hosted cluster:
+
+1. A Postgres database that only your own backend application should ever talk to.
+2. A backend API that the frontend (also running in the cluster) calls internally.
+3. The frontend web application itself, which needs to be reachable by users on the public
+   internet.
+
+## Your task
+
+For each of the three components, decide: ClusterIP, NodePort, or LoadBalancer — and justify
+each choice in one sentence referencing WHO needs to reach it.
+
+## A worked answer to check yourself against
+
+1. **Postgres — ClusterIP.** Only your own backend (running inside the same cluster) needs to
+   reach it; there is no reason for it to be reachable from outside the cluster at all, and
+   exposing a database externally is a real, avoidable security risk.
+2. **Backend API — ClusterIP.** The frontend calls it from inside the cluster too — same
+   reasoning as the database. External users never talk to the backend directly; they only ever
+   go through the frontend.
+3. **Frontend — LoadBalancer** (on a real cloud-hosted cluster). Public internet users need to
+   reach it, and a cloud provider's LoadBalancer is the standard mechanism for that. NodePort
+   would technically work but is typically used for development/testing rather than a real
+   public-facing service on a cloud cluster.
+
+## Self-check
+
+If you chose LoadBalancer for the database or the backend API, reconsider — "internet-reachable
+by default" is not the safe default for anything that doesn't need to be, and getting this
+choice right the first time avoids a real security exposure later, not just a style issue.
+
+## Instructor Notes
+
+**Facilitation:** Push on the "why not just LoadBalancer everything, it works" instinct some
+students will have — this is a good early moment to connect Service-type choice to the security
+mindset that ROOT 09 builds on more fully (exposure should be intentional, not the path of
+least resistance).
+
+**Approximate timing:** 10 minutes live with discussion; 10 minutes self-paced.
+
+**Optional extension:** ask what would need to be added (not covered in this module) to let
+public users reach the frontend at a real domain name over HTTPS rather than a bare
+LoadBalancer IP — a natural forward pointer to Ingress, covered in the next module.
@@ -0,0 +1,40 @@
+# Launch Lab: Exposing an Application
+
+Time to create a real Service in your disposable Lab and connect it to a real Deployment.
+
+## What you're doing
+
+A `redis` Deployment is running, but other Pods can't reliably reach it because Pod IPs change
+whenever a Pod restarts — exactly the problem the lesson opened with. Your task is to create a
+stable ClusterIP Service in front of it.
+
+## Before you start
+
+Recall the request path from the lesson: your Service's `selector` has to match the Deployment
+Pods' actual labels, or you'll end up with the empty-Endpoints situation from the
+demonstration. Check the Deployment's Pod labels before writing your Service's selector, don't
+guess at them.
+
+## Your task in this Lab
+
+Create a ClusterIP Service exposing the `redis` Deployment on the correct port. Once it's
+created, verify it the same way the demonstration did: `kubectl get service`, then `kubectl get
+endpoints` to confirm it actually has a non-empty Endpoints list, not just that the Service
+object exists.
+
+This Lab has its own in-context hints if you get stuck.
+
+When you're done, return to this module for a reflection on why service discovery is
+infrastructure, not magic.
+
+## Instructor Notes
+
+**Classroom flow:** Encourage students to run `kubectl get endpoints` as their OWN verification
+step even though the Lab's automated validation will check this too — building the habit of
+checking Endpoints, not just "the Service exists," is the actual transferable skill here.
+
+**Approximate timing:** 10-15 minutes.
+
+**Common mistake to watch for:** a selector that matches on the wrong label key/value, or a
+port/targetPort mismatch (the Service's `port` is what clients connect to; `targetPort` is what
+the container actually listens on — conflating the two is a very common first-time error).
@@ -0,0 +1,40 @@
+# Reflection: Service Discovery Is Infrastructure, Not Magic
+
+You just created a Service that gives a moving set of Pods a stable address. Take a few minutes
+to connect this to real operational thinking.
+
+## Reflection questions
+
+1. Before this module, "the app can just connect to redis by name" might have seemed obvious or
+   automatic. What specific mechanism actually makes that true, and what would break it?
+2. If your Service's selector had been wrong (matching zero Pods), what would the SYMPTOM have
+   looked like from the application's side, versus what the actual CAUSE would have been?
+3. Why is checking `kubectl get endpoints` before assuming a networking/DNS/firewall problem a
+   good default habit, given how common a selector mismatch actually is?
+
+## Real Ops takeaway
+
+**"It's probably a networking issue" is often wrong, and Endpoints is how you find out fast.** A
+huge fraction of real "service X can't reach service Y" incidents in Kubernetes are Service
+selector mismatches, not actual network problems — checking `kubectl get endpoints` first, before
+escalating to firewall rules or DNS debugging, saves real time precisely because this failure
+mode produces zero errors at the layers people instinctively check first.
+
+**Stable addressing is what makes rolling updates and self-healing actually usable.** Everything
+you learned in ROOT 06 about Pods being replaced during a rollout or after a crash only works
+smoothly in practice because Services give callers a stable target that survives those
+replacements — without this layer, every Pod replacement would require updating every caller's
+configuration by hand.
+
+This module is complete. Continue to the next module.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** use question 2 as a discussion prompt — the
+symptom/cause gap is exactly why this class of bug is often under-diagnosed in real teams.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced writing.
+
+**Optional extension:** ask students to write the one-line runbook entry they'd want a future
+on-call engineer to have for "Service X seems unreachable" — a good exercise in turning a
+lesson into something operationally reusable.
@@ -0,0 +1,90 @@
+# Ingress and NetworkPolicy: What They Architecturally Do
+
+## Ingress: routing external HTTP(S) traffic by host/path
+
+You already know a LoadBalancer Service can expose something to the public internet. But a real
+application usually needs more than "one raw IP to one Service" — you might want
+`api.example.com` and `app.example.com` to route to different backend Services, all through one
+entry point, with TLS termination handled in one place instead of per-Service.
+
+**Ingress** is the Kubernetes object for exactly this: a set of HTTP routing rules (by hostname
+and/or URL path) that an Ingress controller reads and turns into actual load-balancer/proxy
+configuration.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: app-ingress
+spec:
+  rules:
+  - host: app.example.com
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: frontend-svc
+            port: { number: 80 }
+```
+
+An important distinction: Ingress is a set of ROUTING RULES, not a load balancer itself — an
+Ingress controller (a separate piece of software running in the cluster) is what actually reads
+these rules and does the routing. Without a controller installed, an Ingress object exists in
+the API but nothing acts on it.
+
+## NetworkPolicy: traffic reachability as something you declare, not assume
+
+By default, every Pod in a Kubernetes cluster can reach every other Pod — there is no built-in
+network isolation between them at all. This surprises people coming from a "obviously the
+network is locked down unless configured otherwise" assumption. It is exactly backwards from
+that assumption: **everything is reachable until you say otherwise.**
+
+A NetworkPolicy changes this for the Pods it selects, by declaring which traffic IS allowed —
+everything not explicitly allowed to a Pod covered by at least one NetworkPolicy is then denied.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: allow-frontend-to-backend
+spec:
+  podSelector:
+    matchLabels: { app: backend }
+  ingress:
+  - from:
+    - podSelector:
+        matchLabels: { app: frontend }
+```
+
+This example allows traffic to `backend` Pods only from `frontend` Pods — once this policy
+exists and selects `backend`, every OTHER Pod trying to reach `backend` is now blocked, even
+though nothing was true about that before the policy existed.
+
+## Why this matters architecturally, before it matters as a security control
+
+Right now, think of NetworkPolicy purely as "declaring intended reachability, not assuming it."
+ROOT 09 comes back to NetworkPolicy specifically as a SECURITY control (default-deny postures,
+least-privilege network access) — this module is deliberately just the architectural mental
+model: Kubernetes doesn't isolate network traffic for you by default, and NetworkPolicy is the
+mechanism for declaring the reachability you actually intend.
+
+## Instructor Notes
+
+**Approximate timing:** 15 minutes read; 10 minutes live.
+
+**Likely misconceptions to watch for:**
+- Students often assume Ingress by itself "does" the routing. Emphasize the controller
+  requirement — an Ingress object with no controller installed does nothing.
+- The "everything reachable by default" fact genuinely surprises most students the first time
+  they hear it — it's worth stating plainly and letting it land rather than rushing past it.
+
+**Discussion question:** "If NO NetworkPolicy exists anywhere in a Namespace, what's the actual
+reachability between Pods in that Namespace?" (Answer: completely open — every Pod can reach
+every other Pod, matching the "everything reachable by default" rule.)
+
+**Optional extension:** ask what would happen if you created a NetworkPolicy that selects
+`frontend` Pods but declares no `ingress` rules at all (answer: `frontend` Pods would become
+completely unreachable by anything — an empty ingress list inside a NetworkPolicy that HAS an
+ingress policyType means "deny all incoming," not "no policy applies").
@@ -0,0 +1,46 @@
+# Knowledge Check: Ingress & NetworkPolicy Foundations
+
+---
+
+**1. You create an Ingress object with correct routing rules, but no traffic is ever routed
+according to them. What's the most likely reason?**
+
+*Answer:* No Ingress controller is installed/running in the cluster. Ingress objects are just
+routing rules; a separate controller has to actually read and act on them, or nothing happens.
+
+---
+
+**2. True or false: by default, a Pod in Namespace A cannot reach a Pod in Namespace B unless a
+NetworkPolicy explicitly allows it.**
+
+*Answer:* False — the opposite is true by default. With NO NetworkPolicy in place at all,
+every Pod can reach every other Pod regardless of Namespace. NetworkPolicy is what RESTRICTS
+this default-open behavior, not what's required to enable connectivity in the first place.
+
+---
+
+**3. A NetworkPolicy selects Pods labeled `app: backend` and declares one ingress rule allowing
+traffic from Pods labeled `app: frontend`. What happens to traffic from a Pod labeled
+`app: admin-tool` trying to reach `backend`?**
+
+*Answer:* It's blocked. Once a NetworkPolicy selects a Pod, only traffic matching one of its
+explicit rules is allowed — everything else to that Pod is denied, including traffic that would
+have worked fine before the policy existed.
+
+---
+
+**4. Why is Ingress the right tool for exposing an HTTP application by hostname, rather than
+creating a separate LoadBalancer Service per hostname?**
+
+*Answer:* A LoadBalancer Service typically provisions its own external IP/load balancer per
+Service — one per hostname would mean paying for and managing N separate external endpoints.
+Ingress lets one entry point route to many backend Services by hostname/path, which is both
+cheaper and centralizes concerns like TLS termination.
+
+## Instructor Notes
+
+**Facilitation:** Question 2 catches a very common and consequential misconception — worth
+confirming out loud that everyone actually updated their mental model, not just guessed
+correctly.
+
+**Approximate timing:** 5 minutes.