Primers
In-depth explainers that build the mental model — not Q&A drills. A connected arc of typed teaching blocks (analogy, how-it-works, worked example, misconception, when-to-use) with diagrams and runnable assets.
Argo CD, Commit to Pod: One Commit Traced End to End
Most Argo CD explanations stop at three boxes and an arrow. This interactive holds one architecture fixed — Git, argocd-server, the Application CRD, the application controller, the repo server, Redis, and a target cluster with its own kube API, etcd and workloads — and walks a single commit through 21 steps in two phases. Detect works out that something needs doing and never touches your cluster; Act is the only half that changes anything, and stepping off the end of one opens the other. Watch the parts people get backwards: argocd-server never calls the controller, it patches an annotation on a Kubernetes object and stops; the repo server checks Redis before it touches Git at all, so on a cache hit the fetch never happens; Helm is only ever used to inflate the chart, so no release is recorded; and the two queues are separate, which is why a sync can sit stuck while the cluster is perfectly healthy. Both etcds are drawn and list the records they hold — the Application, AppProject and Secrets in the control plane, the Deployment, Service, ConfigMap and hook Job in the cluster — with each write marked as it lands, including the refresh annotation the controller deletes once it has persisted the status. Hops already walked keep their labels, so the whole route reads at once. Behaviour, defaults and flag names checked against the Argo CD documentation and source, and every Kubernetes claim against kubernetes.io, in August 2026 (v3.5.x).
Seventy YAML Files, and the Change That Has to Touch Ten of Them
Helm is usually explained by its features, which is why it rarely lands. This starts with the estate instead: checkout and payments across dev, staging and three production clusters, written as plain Kubernetes manifests. Seven objects, two services, five clusters — seventy files before anyone has written application code. The number is not the problem. The problem shows up when you put the staging and production Deployments side by side: forty-one lines, six of which differ, and one of those six is an image tag pinned a version behind. Deliberate hold, or did somebody forget to promote? The file cannot tell you, because the deltas — the only part anybody actually chose — are buried in thirty-five identical lines. Then a four-line platform change arrives that has to land in ten files, one of which needs its label selector edited rather than pasted. The same estate as a chart puts that pinned tag in a six-line values file with a ticket number beside it. Along the way: why envsubst produces valid YAML that is quietly wrong, an honest account of where Kustomize is the better answer, the documented values precedence and the null trick for deleting a default, and what a release gives you that kubectl apply has no answer for. Checked against the Helm documentation and changelog in August 2026 — including that Helm 3 passed its bug-fix date on 8 July 2026 and loses security fixes on 11 November.
CoreDNS: One Lookup, All the Way Out
Cluster DNS is invisible until it is expensive. This interactive holds one EKS architecture fixed — the AWS-managed control plane with the payments Service and its ClusterIP, three data-plane nodes running checkout, CoreDNS and payments, a NodeLocal DNS cache on every node because it is a DaemonSet, and the VPC resolver, forwarding rule and outbound endpoint that carry anything the cluster does not own — and walks a single lookup through 23 steps. Look up a cluster name and the first search suffix is the right one: one call, one query, and the answer never leaves the cluster. Look up an external name and the same line of code costs five queries and four useless round trips, because ndots:5 counts dots rather than intent and decides that db.corp.example is a fragment. Two panels record what your one call actually became on the wire and what it left in every cache, growing line by line — including the three cached denials that are why a pod which started before its Service keeps failing long after you create it. Thirty-three questions sit behind the steps, aimed at what the drawing provokes: why CoreDNS is a Deployment while NodeLocal is a DaemonSet, why the query crosses to another node, why the connection is drawn as a separate arrow from the resolution, and which of the three fixes to reach for first. Behaviour, defaults and flag names checked against the Kubernetes, CoreDNS and AWS documentation in August 2026.
Istio, Visually: Zero to Hero on the Service Mesh Powering Your Pods
A service mesh looks like magic until you see the one picture it's built on. This interactive holds a single topology fixed — a checkout-api and payments service, istiod, an ingress Gateway, and the Envoy sidecars around each pod — and steps from raw pod-to-pod calls all the way to ambient mode across ten stages. Watch the core split beginners get backwards (istiod configures; Envoy carries the traffic), a pod gain its sidecar via the mutating webhook, a request stop talking to the network (app → local Envoy → remote Envoy → app), your VirtualService/DestinationRule travel from YAML through istiod over the xDS protocol into a running Envoy, a 90/10 canary, automatic rotating mTLS with a STRICT-vs-PERMISSIVE what-if, telemetry that costs no app code, and finally ztunnel + waypoint replacing per-pod sidecars. A Layers toggle isolates the control plane from the data plane — the single idea that makes the rest click. Every term is colour-bound to the diagram, and the checkout-api canary is the one thread you follow the whole way.
Internet → Pod on EKS: a Traffic-Path Troubleshooting Reference
A packet's journey from the internet to a Pod on EKS crosses more moving parts than any one team owns — DNS, an internet-facing ALB in a dedicated ingress VPC, path-based listener rules to different target groups, a Transit Gateway between VPCs, VPC routers and route tables, the Pod's branch ENI and security group, kube-proxy, and the service-mesh Envoy sidecar — and when it breaks, the on-call has to know which hop to inspect. This interactive holds one accurate topology fixed and steps the packet hop by hop: click a box or flow (or step 0–10) and it lights the active segment, shows a 'troubleshoot this hop' checklist naming the exact AWS/K8s object and the command to inspect it, and opens deep 'how does this actually work' questions — how the target group learns the Pod IP, who updates kube-proxy's iptables and when, who attaches the branch ENI, how traffic reaches the Envoy sidecar. A /svc-a · /svc-b toggle follows path-based routing to two different Pod sets, and a bottom reference block shows the real pod iptables that REDIRECT inbound to Envoy :15006. Real (anonymised) IPs, CIDRs, and route-table entries throughout. Built as an SRE reference.
The Five Pieces of Kubernetes, and How Each One Works
Kubernetes looks like a pile of moving parts, but it's really five kinds of thing around one spine: a control plane core (etcd + kube-apiserver) that holds and gatekeeps all state, webhooks the apiserver calls synchronously, controllers that watch and reconcile forever, node agents that run continuously on every node, and plugins those agents invoke locally. This interactive holds one architecture map fixed and lets you step — or click a numbered piece — to see how each differs on the axes that actually matter: how it's told there is work (a startup flag, a watched API object, a watch subscription, a file or socket), who invokes it (the apiserver, itself, or a node agent), and whether it's a loop that never stops or a one-shot call that runs and exits. Every mechanism is turned into a question you can open — the reconcile loop, the plugin invocation, admission's static-vs-dynamic wiring, the irony that the apiserver watches its own webhook config — and each answer is colour-bound to the same palette as the diagram. A faithful model of upstream Kubernetes on EKS; component names and flags are verbatim.
How a Pod Gets Created on EKS, Step by Step
From kubectl apply to a Pod serving traffic, an EKS Pod launch touches three worlds — the AWS-managed control plane, the worker node, and real AWS API calls off-cluster — and most engineers can name the pieces but not the order they fire in or where each one runs. This interactive holds one EKS topology fixed (the kube-apiserver hub, admission webhooks, scheduler, etcd and cluster controllers up top; a single worker node with kubelet, containerd/runc, VPC CNI, ebs-csi-node, kube-proxy and the Pod sandbox across the bottom; STS, EC2, ECR and ELB in a column on the right) and steps all 35 substeps across 7 phases. Each click lights the exact component and the real call it makes — token auth to sts:GetCallerIdentity, RBAC, the pod-identity and Istio mutating webhooks, PodSecurity, the /binding subresource, RunPodSandbox, CNI ADD and the IP from ipamd, PullImage from ECR, init-then-app containers, readiness, the EndpointSlice, RegisterTargets on the ALB — colour-coded by whether it happens on the control plane, on the node, or as an AWS API call. Every component name and mechanism is verbatim; the full 35-step reference sits underneath. One node is drawn to keep the canvas readable.
What Happens When EKS Scales Its Data Plane, Step by Step
A metric climbs, your Deployment sprouts pods, three sit Pending, a new node appears, the pods run — and ten minutes after traffic dies the node quietly vanishes. Most engineers can name the pieces (HPA, the scheduler, Karpenter or Cluster Autoscaler) but not the order they fire in, the signal each one watches, or the clock each runs on. This interactive holds one EKS cluster fixed and steps the whole scale-up-then-scale-down loop as labeled “A → B : message/API” hops — from the trigger (metrics-server → HPA → Deployment .spec.replicas → an Unschedulable pod) all the way to a node created, then deleted, closing the loop. A top toggle swaps only the diverging hops across three provisioners: a managed node group with Cluster Autoscaler (SetDesiredCapacity on an ASG, in-cluster), Karpenter (a NodeClaim → ec2:CreateFleet, no ASG, in-cluster), and EKS Auto Mode (AWS-managed Karpenter in the control plane, Bottlerocket managed instances, 21-day lifetime). Every state name, default, and API call is verbatim; the reference tables underneath compare the three and list the pitfalls. Step it, or press play.
De-mystifying EKS Worker-Node Networking, Step by Step
How an Amazon EKS worker node talks to its control plane is easy to hand-wave and hard to picture. This interactive holds one AWS-style architecture diagram fixed across two Availability Zones and steps it through the three API-endpoint access modes — public only, public + private, and private only — each shown in three moves: how the worker node reaches the control plane, how the control plane reaches back (kubectl exec / logs, always via the EKS-managed ENIs), and how a CLI user reaches the cluster. Watch Route 53 resolve to a public IP or a private ENI IP, the endpoint's reachability from the internet flip per mode (private-only severs the internet path entirely), and the active path light up on the canvas as the narrative names each hop. A faithful re-presentation of the AWS Containers blog, with endpoint-access mode and subnet layout called out as two independent choices. Step it, or press play.
An Argo CD Sync, Step by Step
GitOps reconciliation is easy to hand-wave and hard to actually picture. This interactive holds one Argo CD architecture diagram fixed — Git, repo-server, application-controller, the cluster — and steps its STATE through a full sync, so you learn from what changes, not from a new picture each slide. Watch the Sync status (Synced / OutOfSync / Unknown), the Health status (Healthy / Progressing / Degraded / …), and which component is working move through the real lifecycle: reconcile and drift detection, then the sync operation itself — PreSync hooks, apply-by-wave and prune, the wait for each wave to go Healthy, PostSync hooks — to Synced + Healthy, plus the SyncFail branch that actually pages you (a PreSync hook fails, so Sync never applies). Every status, phase, hook annotation and sync-wave rule is the verbatim Argo CD name, with the reference tables and argocd app sync flags underneath. Step it, or press play.
SLOs for Infrastructure Teams Whose Users Are Other Teams
The sequel to Article 17: that one taught the mechanics; this one handles the organizational reality that makes infrastructure SLOs genuinely harder than product SLOs. Infrastructure SLOs fail not because the math is hard but because the user is ambiguous — you're not measuring a service, you're measuring an interface between teams. Why product-SLO thinking breaks (fifty consumers, no single golden signal, their SLOs stacked on yours), identifying the actual consumer (define the SLI at your interface, one per capability — not an outcome three layers up), the responsibility boundary as the heart (measure at the Resolver endpoint, not the client; looser than your dependency composite; the SLI that turns 'the network is slow' into data), the infra SLI menu (availability / latency / correctness — plus the provisioning time-to-ready SLO nobody publishes), the negotiation ('what do you assume about us?' → usually 100%; publish it; tier at a chargeback price), error budgets when a consumer causes the burn (per-tenant SLIs, quotas, and why you don't freeze for their fault), and the anti-patterns. One shared capability threaded through all six steps into a published one-page contract.
SLOs from Scratch: Picking Your First SLI for a Network Service
Your first SLO should measure what consumers experience, be based on current performance — not aspiration — and ship with a budget policy, or it's a dashboard, not an SLO. The four terms kept surgically separate (SLI / SLO / error budget / SLA), the hard part for network services (what counts as an 'event' — flows, packets, queries), a worked first SLI for hybrid DNS (Route 53 Resolver + on-prem forwarders: valid = reaches the endpoint, good = non-SERVFAIL within 100 ms), setting the number from measurement and dependency math rather than vibes, error-budget arithmetic and the budget policy everyone skips, and why you alert on burn rate. Every claim sourced.
GitHub Actions, One Layer at a Time: From Six Lines to a Hardened Pipeline
Build one pipeline from six lines up, adding each concept only when the previous version hits a wall — steps vs jobs, why jobs are isolated (and how data actually crosses via artifacts / cache / outputs), the action as the reusable unit, the GITHUB_TOKEN and OIDC, Environments and approvals, the fork trust line and the three ways repos get owned, and matrix / concurrency / cost. The concepts arrive already motivated, not dumped. Every claim sourced.
Leading Without Authority: The Platform Tech Lead's Playbook
You own the outcome but can't order anyone to do anything — and for a platform team that gap isn't a bug in your title, it's the whole job. Why mandates backfire (resentment, shadow workflows, dead feedback), the operating model that works instead (credibility + Cohen & Bradford's currencies of influence + platform-as-product), and 11 concrete plays a platform tech lead actually runs — each tagged with who advocates it and whether it's evidence-based or named opinion. Attributed to Fournier, Larson, Reilly, Team Topologies, and DORA/DevEx research.
Agent Evaluation: Trajectories, Tool-Calls, Task Completion
The fourth primer in the series: how do you know the agent is any good? You stop grading it the way you graded a plain LLM app. A model hands you an output to check against a reference; an agent hands you a trajectory, and the output is only its last step — so you grade the path. Why final-answer eval is a trap for agents; the three layers worth measuring (final response, trajectory, single tool-call) and why most teams measure only the first; the two scorer families (reference-based vs reference-free / LLM-as-judge) and matching the scorer to the question; the two concrete ways to grade a trajectory from the open-source agentevals package (when you know the right path vs when you don't); pass^k — the reliability metric that exposes non-determinism that pass@1 hides; offline (pre-release, gate the PR) vs online (post-release, every production failure becomes a new dataset case) eval on the lifecycle; and a pre-ship checklist. With diagrams and runnable code.
Agent Memory Architectures
The third primer in the series: a stateless model forgets everything between calls, so the entire feeling of an agent that 'knows you' is an illusion you construct by deciding what text to re-send each turn. The two layers you must never conflate — short-term thread state (the checkpointer, keyed by thread_id) vs long-term cross-session knowledge (the store, scoped by user_id); the context window as a budget, not a bucket, and the compaction that keeps it honest; long-term memory's three jobs (semantic, episodic, procedural) and why one bucket for all three breaks retrieval; the recall and save nodes that bracket the loop; resuming a thread by its transcript vs greeting a fresh session with the user's facts; the line between memory and RAG; and a 17-row pre-ship checklist. With flow diagrams and runnable LangGraph code.
Tool Use & the Agent-Computer Interface
The sequel to The Agent Loop: how to design the tools an agent calls so it picks the right one, fills the arguments correctly, and recovers when they fail. Why a tool is model-facing documentation, not an API; the brain-in-a-jar mechanism of a single tool call traced on the wire (and why it's two API calls); curating a narrow-but-consolidated tool layer with the ~15-tool cap; schema hygiene (enums over naked strings, flat objects, additionalProperties:false, Pydantic validation at both ends); errors as instructions for self-correction; idempotent writes and stateless tools; routing instead of dumping past ~20 tools (progressive discovery, a single meta-tool, a hierarchical router, semantic retrieval); and evaluating tools against a golden set. With diagrams and runnable Anthropic-SDK and LangGraph code.
The Agent Loop
An in-depth primer on the one primitive every agent reduces to: a model in a loop with tools — think, act, observe, repeat. Walks ReAct as the base loop, when Plan-and-Execute and Reflection earn their place, how production layers all three into a hierarchical architecture (an outer planner, ReAct sub-agents per step, a reflection gate), and the deterministic guardrails that actually keep it safe — strict termination, context pruning, execution sandboxing, and human-in-the-loop interrupts. With diagrams and runnable Anthropic-SDK and LangGraph code.
Embeddings & Vector Search — a Primer
An in-depth, engineer-leaning explainer (not Q&A): the one mental model — an embedding turns meaning into coordinates, so search-by-meaning becomes find-nearest-points. Cosine vs dot product vs Euclidean and the magnitude trap, why on normalized vectors all three rank identically, why brute-force k-NN is exact but O(N) and breaks at scale, approximate nearest neighbor and the recall-vs-latency dial (recall@k), and how the HNSW graph index actually works (layered proximity graph, greedy descent, M/ef) alongside IVF and product quantization. With diagrams and a runnable zero-dependency notebook that makes cosine, dot, and L2 disagree then agree.
Evals for LLM Apps — a Primer
An in-depth, engineer-leaning explainer (not Q&A): the one mental model — an eval is a test suite for a non-deterministic system, so you measure quality with a grader over a dataset, not exact equality. The anatomy (dataset → task → grader → score), the three grading methods (code, human, LLM-as-judge) and their cost-vs-nuance trade, running LLM-as-judge well (rubrics, structured verdicts, reason-then-discard, a different model) and its real biases (position, verbosity, self-enhancement), plus offline vs online, regression testing as CI-for-prompts, and guardrail testing. With diagrams and a runnable eval-harness notebook that exposes the judge flipping under position bias.
Model Context Protocol (MCP) — a Primer
An in-depth, engineer-leaning explainer (not Q&A): the one mental model — MCP is a universal port that turns M×N custom integrations into M+N — then the host/client/server architecture (one client per server, 1:1), the JSON-RPC data layer inside the transport layer, the three server primitives (tools the model calls, resources the app loads, prompts the user picks), the lifecycle traced in real messages (initialize → negotiate capabilities → list → call → notify), stdio vs Streamable HTTP, and client primitives (sampling, elicitation). With diagrams and a runnable, zero-dependency protocol-handshake notebook.
RAG, End to End — a Primer
An in-depth, engineer-leaning explainer (not Q&A): the one mental model — RAG is a funnel that selects the model's input, not its weights — traced stage by stage (chunk → embed → retrieve → rerank → generate). Why 'similar' isn't 'relevant' (with a runnable zero-dependency demo where the answer-bearing chunk loses to a vocabulary match), retrieve-then-rerank (bi-encoder recall vs cross-encoder precision), the four-stage failure cascade where the right chunk gets dropped before the model sees it, and managed RAG on Bedrock Knowledge Bases — plus when RAG beats a bigger context window or fine-tuning. With diagrams, a runnable notebook, and a hands-on exercise.
AWS Direct Connect — a Primer
An in-depth, mixed-audience explainer (not Q&A): the one mental model — a dedicated private wire, not a tunnel — sliced into virtual interfaces where each slice reaches a different world (private→your VPC, public→AWS services not the internet, transit→many VPCs). The physical layer (cross-connect, LOA-CFA, dedicated vs hosted), the VIF reachability matrix (with a Terraform example), the gateways (VGW vs DXGW vs Transit Gateway, and why a DXGW is non-transitive), routing with BGP (advertise/receive prefixes; local-pref steers outbound, AS-path/communities steer inbound; BFD), resilience (the Resiliency Toolkit tiers, 99.9%/99.99%), and security/cost/when-to-use (private ≠ encrypted → MACsec or VPN-over-DX; port-hours + lower egress; the worth-it threshold). With diagrams and a design exercise.
Self-Improving AI Agents — a Primer
An in-depth, mixed-audience explainer (not Q&A): the one mental model — edit the producer, not the product — and the four levels improvement lives at (prompt/notes → memory/skills → tools/code → weights). The shallow end (Reflexion: reflect→store→retry with no weight updates, with a runnable zero-dependency notebook), the deep end (the Darwin Gödel Machine rewriting its own code; how Schmidhuber's 'prove it first' Gödel machine became 'test it'), where it breaks (the DGM faking its own test logs — reward hacking), and when self-improvement actually earns its place. With diagrams, a demo notebook, and a hands-on exercise.
AI Agent Factory — a Primer
An in-depth, mixed-audience explainer (not Q&A): the production-line mental model — from artisanal one-off agents to a governed factory — the moving parts (templates, orchestration, tools/connectors, governance, lifecycle), the agent lifecycle with governance gates, the four governance pillars, supervisor orchestration and define-once agent specs, and when a factory earns its weight vs an agent framework. With diagrams, a governance checklist, an agent-spec template, and a blueprint exercise.
No posts match — try a different keyword or clear the filters.