Add architecture diagrams to the six tutorial READMEs that lacked one

[paolosalvatori]

Motivation

Seven of the thirteen tutorial READMEs already open with an ## Architecture section and a Mermaid diagram; six did not. On the pages that have one, the diagram is what makes the walkthrough legible before you run a single script — it names the objects, shows which component acts on which, and marks where the identity boundary sits. The six pages without one asked the reader to build that picture from prose and a script table.

Three of the six are index pages (keda, key-vault-csi-driver, policies), where a diagram earns its place for a reason the child pages cannot cover: what the sibling tutorials share and where they diverge. That relationship is the whole point of those pages, and it was previously only stated in a table.

Changes

Six diagrams, each in an ## Architecture section placed right after the "Running on LocalStack?" note — the slot service-bus and ccm use — with a one-sentence lead-in before the block, matching the existing pages. All six reuse the house %%{init: ...}%% directive and the established shape vocabulary (([...]) for queues and external endpoints, [[...]] for the event hub, -.-> for "watched by / read by / enforced by").

README	What the diagram shows
tutorials/keda	The shared local-keda-uami-test identity and the single KEDA add-on on the left, then one lane per tutorial with its event source, trigger, role grant and HPA
tutorials/key-vault-csi-driver	One CSI driver plus Azure provider serving both namespaces, diverging only at the identity: federated token exchange vs. the add-on's azureKeyvaultSecretsProvider identity
tutorials/policies	Engine chosen at cluster creation → which CRD group each engine enforces → which tutorial requires it
calico-policy-tutorial	The cluster-wide default-deny, then the two namespaced policies re-opening egress and ingress
cilium/egress-tutorial	The DNS-proxy mechanism (kube-dns answers observed by cilium-agent) and the per-hostname verdict at each of the three tightenings
cilium/ingress-tutorial	The object-level view: rule1 reapplied at L3/L4 then L7, tiefighter dropped at L7 and xwing dropped at L3

In the three policy tutorials the edges are labelled with the script number that changes each outcome (blocked by 03, allowed from 05), so the diagram tracks the walkthrough instead of restating it.

Every name, label, selector, role and namespace was read out of the manifests and scripts rather than inferred. One thing that surfaced from doing so: event-hubs does grant the shared identity Azure Event Hubs Data Owner and Storage Blob Data Contributor (03-create-resources.sh) even though its scaler authenticates with a connection string, so the index diagram shows both grants.

Documentation only — no scripts, manifests or Terraform/Bicep touched. Additions only; no existing line was modified.

Tests

No test suite covers README content, so verification was rendering:

• Each of the six diagrams was rendered with mmdc (mermaid-cli) as a standalone file, then re-extracted from the committed READMEs and rendered again — all six render clean, which confirms the fenced blocks survived insertion intact.
• Each render was inspected visually, and two diagrams were reworked as a result: the KEDA index was spaghetti when grouped cluster-vs-Azure, so it is grouped by tutorial lane instead; and the egress targets left their subgraph because the stacked layout made three separate edges read as a chain.
• The existing event-hubs diagram was rendered the same way as a baseline. The subgraph-title overlap that appears on long nested titles is present there too, so it is pre-existing house behaviour and not introduced here.
• Confirmed all 13 tutorial READMEs now contain exactly one mermaid block, with no duplicates.

Worth a reviewer's opinion: cilium/ingress-tutorial already carries three PNGs from the Cilium docs illustrating the same progression. The Mermaid diagram still adds the actual Kubernetes objects where the PNGs are conceptual art, but it is the one to drop if you find it redundant. The nine samples/* READMEs also have no diagram and were left alone, since the scope here was the tutorials.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds an “## Architecture” section with Mermaid flowchart diagrams to six tutorial READMEs that previously lacked an up-front architecture overview, aligning them with the other tutorial pages that already include diagrams.

Changes:

• Added new ## Architecture sections with Mermaid diagrams to six tutorial READMEs.
• Standardized diagram placement (immediately after the “Running on LocalStack?” note) and formatting (%%{init: ...}%%, shared shape vocabulary).
• Documented tutorial-specific policy/identity relationships visually (e.g., per-engine policy CRDs, per-step policy effects).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tutorials/policies/README.md	Adds an architecture diagram summarizing how policy engine choice maps to CRDs and which tutorials require which engine.
tutorials/policies/cilium/ingress-tutorial/README.md	Adds an object-level Cilium ingress-policy diagram showing L3/L4 then L7 enforcement progression.
tutorials/policies/cilium/egress-tutorial/README.md	Adds a Cilium FQDN/DNS-observation diagram explaining the mechanism behind progressive tightening steps.
tutorials/policies/calico/calico-policy-tutorial/README.md	Adds a Calico policy-flow diagram illustrating default-deny plus selective egress/ingress reopening steps.
tutorials/key-vault-csi-driver/README.md	Adds an identity/access-mode architecture diagram for the CSI driver + Azure provider across the two samples.
tutorials/keda/README.md	Adds a KEDA index architecture diagram showing shared add-on/identity and per-tutorial event sources and scaling.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.