feat(site): fail fast when cluster nodes share a hostname (#697)

Add a preflight assertion to site.yml that confirms every host in the
k3s_cluster group reports a unique hostname. k3s registers each node keyed by
its hostname, so duplicate hostnames prevent nodes from joining the cluster
and are hard to troubleshoot. The check fails fast in the Pre tasks instead of
surfacing as a cryptic registration failure later.

- site.yml: assert (cluster_hostnames | unique | length) == length for the
  k3s_cluster group, skipping hosts outside that group
- README.md: document the unique-hostname requirement
- .github/scripts/test-unique-hostname-precheck.sh: regression test
- .pre-commit-config.yaml: wire the test into pre-commit

Closes #636

.github/scripts/test-unique-hostname-precheck.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+set -Eeuo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+site_play="$repo_root/site.yml"
+
+# #636: verify the "Pre tasks" play asserts that all k3s_cluster hosts have
+# unique hostnames, so a duplicate-hostname inventory fails fast instead of
+# silently breaking node registration/joining.
+grep -Fq -- 'Verify all cluster nodes have unique hostnames' "$site_play" || {
+  printf 'site.yml is missing the unique-hostname preflight check\n' >&2
+  exit 1
+}
+
+# The check must deduplicate the cluster hostname list via the `unique` filter
+# and compare lengths, i.e. groups['k3s_cluster'] must be referenced.
+grep -Fq -- "groups['k3s_cluster']" "$site_play" || {
+  printf 'unique-hostname check does not iterate the k3s_cluster group\n' >&2
+  exit 1
+}
+
+if ! grep -Eq -- 'cluster_hostnames.*\|.*unique|\| unique' "$site_play"; then
+  printf 'unique-hostname check does not deduplicate the hostname list\n' >&2
+  exit 1
+fi
+
+printf 'Unique hostname preflight regression test passed\n'

.pre-commit-config.yaml

@@ -62,6 +62,12 @@ repos:
         language: system
         pass_filenames: false
         files: ^roles/k3s_server/tasks/(main|join_master)\.yml$|^\.github/scripts/test-k3s-server-bootstrap\.sh$
+      - id: unique-hostname-precheck-test
+        name: Unique hostname precheck test
+        entry: .github/scripts/test-unique-hostname-precheck.sh
+        language: system
+        pass_filenames: false
+        files: ^site\.yml$|^\.github/scripts/test-unique-hostname-precheck\.sh$
       - id: cilium-bgp-manifest-test
         name: Cilium BGP manifest test
         entry: python3 .github/scripts/test-cilium-bgp-manifest.py

README.md

@@ -50,6 +50,10 @@ Supported processor architectures are:
 - Server and agent nodes should support passwordless SSH access. Otherwise, pass `--ask-pass --ask-become-pass` to
   each playbook command.
 
+- Every node in the cluster must have a **unique hostname**. k3s registers each node keyed by its hostname, so
+  two nodes with the same hostname cannot join the cluster. `site.yml` asserts this up front and fails fast if
+  any duplicate is found.
+
 ## 🚀 Getting Started
 
 ### 🍴 Preparation

site.yml

@@ -8,6 +8,23 @@
         msg: >
           "Ansible is out of date. See here for more info: https://docs.technotim.com/posts/ansible-automation/"
 
+    - name: Verify all cluster nodes have unique hostnames
+      ansible.builtin.assert:
+        that: (cluster_hostnames | unique | length) == (cluster_hostnames | length)
+        msg: >-
+          k3s nodes must have unique hostnames. Found a duplicate in:
+          {{ cluster_hostnames | unique }}. Each node registers in the cluster
+          keyed by its hostname, so matching hostnames prevent nodes from joining.
+      vars:
+        cluster_hostnames: >-
+          {{
+            groups['k3s_cluster']
+            | map('extract', hostvars, 'ansible_hostname')
+            | list
+          }}
+      run_once: true
+      when: "'k3s_cluster' in groups"
+
 - name: Prepare Proxmox cluster
   hosts: proxmox
   gather_facts: true