Initial import: phase docs, configs, Claude conventions

Phase 1-3 runbooks and design notes, version pins, config templates, project-history conventions, cluster-inspector read-only credentials setup. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 00:58:52 +02:00
commit 5fd998c5f9
26 changed files with 1124 additions and 0 deletions
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Mint a read-only kubeconfig for the cluster-inspector agent.
+#
+# Usage: make-kubeconfig.sh <name> [options]
+#   <name>                   cluster name, e.g. lab-mgmt or lab1 -> kubeconfigs/<name>.kubeconfig
+#   --admin-kubeconfig PATH  admin kubeconfig used to apply RBAC / mint the token (default: $KUBECONFIG or ~/.kube/config)
+#   --context CTX            context inside the admin kubeconfig
+#   --server URL             override API server URL (k3s.yaml says https://127.0.0.1:6443)
+#   --duration DUR           token lifetime (default 168h); re-run the script to refresh
+#   --apply-rbac             kubectl apply rbac.yaml first (needed once per cluster)
+set -euo pipefail
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+name=""; admin="${KUBECONFIG:-$HOME/.kube/config}"; ctx=""; server=""; duration="168h"; apply=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --admin-kubeconfig) admin="$2"; shift 2 ;;
+    --context)          ctx="$2"; shift 2 ;;
+    --server)           server="$2"; shift 2 ;;
+    --duration)         duration="$2"; shift 2 ;;
+    --apply-rbac)       apply=1; shift ;;
+    -h|--help)          sed -n '2,10p' "$0"; exit 0 ;;
+    -*)                 echo "unknown option $1" >&2; exit 1 ;;
+    *)                  name="$1"; shift ;;
+  esac
+done
+[[ -n "$name" ]] || { sed -n '2,10p' "$0" >&2; exit 1; }
+
+k=(kubectl --kubeconfig "$admin")
+[[ -n "$ctx" ]] && k+=(--context "$ctx")
+
+if (( apply )); then "${k[@]}" apply -f "$here/rbac.yaml"; fi
+
+token="$("${k[@]}" -n kube-system create token readonly-inspector --duration "$duration")"
+[[ -n "$server" ]] || server="$("${k[@]}" config view --raw --minify --flatten -o jsonpath='{.clusters[0].cluster.server}')"
+ca="$("${k[@]}" config view --raw --minify --flatten -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')"
+[[ -n "$ca" ]] || { echo "no certificate-authority-data in admin kubeconfig" >&2; exit 1; }
+
+mkdir -p "$here/kubeconfigs"
+out="$here/kubeconfigs/$name.kubeconfig"
+umask 077
+cat > "$out" <<EOF
+apiVersion: v1
+kind: Config
+clusters:
+- name: $name
+  cluster:
+    server: $server
+    certificate-authority-data: $ca
+users:
+- name: $name-readonly-inspector
+  user:
+    token: $token
+contexts:
+- name: $name-ro
+  context:
+    cluster: $name
+    user: $name-readonly-inspector
+current-context: $name-ro
+EOF
+echo "wrote $out (context $name-ro, server $server, token valid $duration)"
+
+echo "verification (expect yes, yes, no, no, no; CAPI rows say no on workload clusters):"
+for check in "list pods" "get machines.cluster.x-k8s.io" "delete machines.cluster.x-k8s.io" \
+             "patch machinedeployments.cluster.x-k8s.io" "get secrets"; do
+  printf '  %-45s %s\n' "$check" "$(KUBECONFIG="$out" kubectl auth can-i $check -A 2>/dev/null || true)"
+done