Initial commit: GitOps Starter Pack

A teaching-first, single-cluster GitOps setup: Talos Linux + Argo CD with
an app-of-apps layout, MetalLB pre-installed for real LoadBalancer IPs on
bare metal, a demo app, and a progressive docs/ walkthrough with a
CLAUDE.md tutor persona and guided bootstrap checklist.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/metallb/Chart.yaml

@@ -0,0 +1,21 @@
+# An "umbrella" chart: it declares a dependency on the upstream MetalLB
+# chart below, AND carries two templates of its own
+# (apps/metallb/templates/) — the IPAddressPool and L2Advertisement that
+# configure it. Argo CD detects this as a Helm source because a Chart.yaml
+# exists at this path, resolves the dependency, and syncs the combined
+# rendered output as one Application — exactly like any other app in
+# apps/. This is the real, working example of the Helm-based app pattern
+# mentioned in docs/07-adding-new-apps.md: use it as a template if you want
+# to bring in another third-party chart later.
+apiVersion: v2
+name: metallb-app
+description: Installs MetalLB from the upstream chart, for this repo's bare-metal LoadBalancer support
+version: 0.1.0
+dependencies:
+  - name: metallb
+    # A version *range* rather than an exact pin, so this doesn't silently
+    # go stale. For a fully reproducible install, check
+    # https://artifacthub.io/packages/helm/metallb/metallb for the current
+    # release and pin an exact version here instead.
+    version: ">=0.14.3"
+    repository: https://metallb.github.io/metallb

apps/metallb/templates/ipaddresspool.yaml

@@ -0,0 +1,29 @@
+# Tells MetalLB which IP addresses it's allowed to hand out to Services.
+# Pick a small range on your LAN that nothing else will ever assign —
+# especially your router's DHCP server. MetalLB doesn't coordinate with
+# your router or DHCP server at all; it just answers network requests for
+# whatever address a Service claims from this range. If it overlaps your
+# DHCP range, you'll eventually get two devices claiming the same IP.
+#
+# >> Ask Claude to help you pick this range before editing it — it needs
+#    to know your LAN's subnet and DHCP range, which it can't guess.
+#    A typical home LAN answer looks like "my router hands out
+#    192.168.1.100–192.168.1.199, so let's use 192.168.1.240–192.168.1.250."
+#
+# This file lives under apps/metallb/templates/ alongside MetalLB's own
+# Helm-installed resources, rather than as a separate app, because it
+# depends on the CRD that chart installs — Kubernetes needs to know what
+# an IPAddressPool *is* before it can accept one. The sync-wave annotation
+# is what keeps that order correct: Argo CD applies wave "0" (this chart's
+# own resources, including the CRDs) first, waits for it to be healthy,
+# then applies wave "1" (this file and l2advertisement.yaml).
+apiVersion: metallb.io/v1beta1
+kind: IPAddressPool
+metadata:
+  name: default-pool
+  namespace: metallb-system
+  annotations:
+    argocd.argoproj.io/sync-wave: "1"
+spec:
+  addresses:
+    - 192.168.1.240-192.168.1.250 # EDIT ME — replace with your chosen range

apps/metallb/templates/l2advertisement.yaml

@@ -0,0 +1,19 @@
+# L2Advertisement is what actually makes addresses from the pool reachable:
+# it tells MetalLB to answer ARP requests for whichever address a Service
+# was given, from whichever node currently hosts that Service. This is
+# "Layer 2 mode" — the simplest of MetalLB's two modes, and the right
+# choice here since it needs no cooperation from your router (the
+# alternative, BGP mode, does — worth knowing exists if you outgrow a
+# single L2 segment, not needed for this setup).
+# Same sync-wave reasoning as ipaddresspool.yaml — deferred to wave "1" so
+# it applies after MetalLB's own chart resources are up.
+apiVersion: metallb.io/v1beta1
+kind: L2Advertisement
+metadata:
+  name: default
+  namespace: metallb-system
+  annotations:
+    argocd.argoproj.io/sync-wave: "1"
+spec:
+  ipAddressPools:
+    - default-pool

apps/metallb/values.yaml

@@ -0,0 +1,9 @@
+# Values for the upstream MetalLB chart, nested under `metallb:` (the
+# dependency's name in Chart.yaml — Helm nests subchart values under the
+# subchart's name automatically). Empty by default: MetalLB's own chart
+# defaults are sane for a small single-cluster setup. Add overrides here if
+# you ever need them, e.g.:
+#
+# metallb:
+#   speaker:
+#     tolerations: []