From ad1d2be3cc508f4971115a8ad5f20a41574dbe6e Mon Sep 17 00:00:00 2001
From: xnoto <steven@makeitwork.cloud>
Date: Sat, 12 Sep 2026 21:33:29 -0600
Subject: [PATCH] docs: use default kubeconfig with k3s context name

Local kubectl access now standardizes on the default kubeconfig
(~/.kube/config) with a context named k3s instead of a dedicated
per-cluster kubeconfig file. The example becomes a merge fragment
(current-context dropped so it cannot hijack an existing default),
and the README documents the flatten-merge flow. Companion to
makeitworkcloud/tfroot-libvirt#28.
---
 README.md                    | 44 +++++++++++++++++++++---------------
 docs/kubeconfig.example.yaml |  3 +--
 2 files changed, 27 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index e52a8e1..c061890 100644
--- a/README.md
+++ b/README.md
@@ -92,15 +92,25 @@ and Kubernetes RBAC validate.
 Install `kubectl` and the `kubectl oidc-login` plugin. Confirm both commands are
 available before continuing.
 
-Create a dedicated kubeconfig such as `~/.kube/makeitworkcloud-k3s.yaml`, mode
-`0600`. Its cluster entry points to `https://api.makeitwork.cloud`; the public
-Cloudflare certificate uses normal system CA trust. The kubeconfig must not
-contain a token, client certificate, client key, or private cluster CA. Do not
-copy `/etc/rancher/k3s/k3s.yaml` off the node: it contains cluster-admin client
+Add the cluster to the default kubeconfig (`~/.kube/config`) with a context
+named `k3s`; do not create a dedicated per-cluster kubeconfig file. The cluster
+entry points to `https://api.makeitwork.cloud`; the public Cloudflare
+certificate uses normal system CA trust. The kubeconfig must not contain a
+token, client certificate, client key, or private cluster CA. Do not copy
+`/etc/rancher/k3s/k3s.yaml` off the node: it contains cluster-admin client
 credentials.
 
-Copy `docs/kubeconfig.example.yaml` to that dedicated path and set mode `0600`.
-Its user exec credential is:
+Merge the stanzas from `docs/kubeconfig.example.yaml` into the default
+kubeconfig, keeping the file mode `0600`:
+
+```bash
+cp ~/.kube/config ~/.kube/config.bak
+KUBECONFIG="$HOME/.kube/config:docs/kubeconfig.example.yaml" \
+  kubectl config view --flatten > ~/.kube/config.new
+chmod 600 ~/.kube/config.new && mv ~/.kube/config.new ~/.kube/config
+```
+
+The user exec credential is:
 
 ```yaml
 user:
@@ -119,24 +129,22 @@ user:
       - --token-cache-storage=keyring
 ```
 
-Give this cluster a distinct context name such as `makeitworkcloud-k3s`; never
-reuse an unrelated production or staging context. First confirm the dedicated
-file's current context, server, and user name without displaying credentials:
+The context is named `k3s`; never reuse an unrelated production or staging
+context name. First confirm the context's server and user name without
+displaying credentials:
 
 ```bash
-export KUBECONFIG="$HOME/.kube/makeitworkcloud-k3s.yaml"
-kubectl config current-context
-kubectl config view --minify \
+kubectl config view --minify --context=k3s \
   -o jsonpath='{.clusters[0].cluster.server}{"\n"}{.users[0].name}{"\n"}'
 ```
 
-The expected context is `makeitworkcloud-k3s`, the server is
-`https://api.makeitwork.cloud`, and the user is the dedicated OIDC exec user. Then
-verify the authenticated identity before performing any change:
+The expected server is `https://api.makeitwork.cloud` and the user is the
+dedicated OIDC exec user `makeitworkcloud-oidc`. Then verify the authenticated
+identity before performing any change:
 
 ```bash
-kubectl --context makeitworkcloud-k3s auth whoami
-kubectl --context makeitworkcloud-k3s auth can-i '*' '*' --all-namespaces
+kubectl --context k3s auth whoami
+kubectl --context k3s auth can-i '*' '*' --all-namespaces
 ```
 
 `auth whoami` should show your email and the `makeitworkcloud:admins` group;
diff --git a/docs/kubeconfig.example.yaml b/docs/kubeconfig.example.yaml
index ae927d6..6e1b285 100644
--- a/docs/kubeconfig.example.yaml
+++ b/docs/kubeconfig.example.yaml
@@ -23,8 +23,7 @@ users:
           - --oidc-pkce-method=S256
           - --token-cache-storage=keyring
 contexts:
-  - name: makeitworkcloud-k3s
+  - name: k3s
     context:
       cluster: makeitworkcloud-k3s
       user: makeitworkcloud-oidc
-current-context: makeitworkcloud-k3s