Updated project to improve guidance

terraform/cloud-init/agent.yaml.tpl

@@ -14,16 +14,30 @@ package_update: true
 packages:
   - curl
 
+# A script instead of a plain runcmd line for one reason: Terraform (see
+# main.tf's closing comment) brings all VMs up in parallel, with no
+# ordering guarantee that the server finishes installing k3s before an
+# agent tries to join it. Baking the retry loop into a script keeps that
+# concern out of runcmd, which just calls it once.
 write_files:
   - path: /usr/local/bin/join-k3s.sh
     permissions: '0755'
     content: |
       #!/bin/sh
       # Server may still be booting; retry the join until it answers.
+      # /ping is k3s's own unauthenticated liveness endpoint — this only
+      # confirms the API server is accepting connections yet, it's not a
+      # credential check (K3S_TOKEN below is what actually authorizes the
+      # join once it happens).
       until curl -sk https://${server_ip}:6443/ping >/dev/null 2>&1; do
         echo "waiting for k3s server at ${server_ip}..."
         sleep 5
       done
+      # Agents pass the token via environment variables to the installer
+      # rather than a config.yaml file (contrast server.yaml.tpl) because
+      # get.k3s.io's own install script reads K3S_URL/K3S_TOKEN directly
+      # for the "join an existing cluster" path — there's no separate
+      # agent config file it looks for the way the server has one.
       curl -sfL https://get.k3s.io | \
         K3S_URL="https://${server_ip}:6443" \
         K3S_TOKEN="${k3s_token}" \

terraform/cloud-init/network-config.yaml.tpl

@@ -1,3 +1,13 @@
+# cloud-init's network-config schema (distinct from the #cloud-config
+# user-data schema in server.yaml.tpl/agent.yaml.tpl — no "#cloud-config"
+# header here, and `version: 2` picks the netplan-style dialect). eth0 is
+# the interface name libvirt's virtio NIC presents as inside a fresh
+# Ubuntu cloud image — the only interface that exists at boot, since each
+# node has exactly one network_interface in main.tf's libvirt_domain.
+# `nameservers` points at the gateway rather than a public resolver
+# because that's also where libvirt's own DNS forwarder listens (the `dns
+# { enabled = true }` block on libvirt_network.k3s in main.tf) — it
+# resolves both k3s.local addresses and forwards everything else out.
 version: 2
 ethernets:
   eth0:

terraform/cloud-init/server.yaml.tpl

@@ -14,17 +14,34 @@ package_update: true
 packages:
   - curl
 
+# k3s reads /etc/rancher/k3s/config.yaml automatically on install — this
+# is the file, not command-line flags, specifically so the token never
+# shows up in `ps`/process listings or shell history on the node, and
+# `runcmd` below can stay a one-liner with no secrets in it. 0600 so only
+# root can read it.
 write_files:
   - path: /etc/rancher/k3s/config.yaml
     permissions: '0600'
     content: |
       token: "${k3s_token}"
+      # Every hostname a client might use to reach this server needs to be
+      # in the API server's TLS certificate up front, or that client's TLS
+      # handshake fails outright — it can't be added after the fact
+      # without regenerating the cert. `${hostname}` covers this node's
+      # own name; `${k8s_api_hostname}` is the LAN-only name
+      # docs/04-tofu.md step 5 sets up for kubectl access from elsewhere on
+      # the network — both need to be here even though nothing uses the
+      # second one yet at boot time.
       tls-san:
         - "${hostname}"
         - "${k8s_api_hostname}"
 
 runcmd:
   - curl -sfL https://get.k3s.io | sh -s - server
+  # k3s's own kubeconfig is generated readable only by root (it grants
+  # full cluster-admin access) — this copies it somewhere the unprivileged
+  # `k3s` user can read, so docs/04-tofu.md step 3 can fetch it over SSH
+  # without needing root on the node.
   - mkdir -p /home/k3s/.kube
   - k3s kubectl config view --raw > /home/k3s/.kube/config
   - chown -R k3s:k3s /home/k3s/.kube