anton-remote-access

name	anton-remote-access
description	Remote access reference for Anton — how to reach the cluster from off-LAN via talosctl, kubectl, and Tailscale MagicDNS. Use when working with talosconfig, kubectl context, tailscale, remote access, or when you cannot reach k8s nodes.
allowed-tools	Read, Bash

Anton remote access

How to reach the cluster and nodes from a workstation. This is the primary access path — the workstation is not assumed to be on the node LAN.

TL;DR

# Talos (node management) — via Tailscale MagicDNS hostnames
talosctl --talosconfig ./talos/clusterconfig/talosconfig \
  -e k8s-1 -n k8s-1,k8s-2,k8s-3 <command>

# Kubernetes — via kubeconfig generated by task bootstrap / talhelper
kubectl get nodes

Access paths

The cluster nodes (k8s-1, k8s-2, k8s-3) are reachable two ways:

1. LAN — the 192.168.x.x addresses in talos/talconfig.yaml. Only works when the workstation is on the home network.
2. Tailscale — every node runs the Tailscale extension and is advertised on the tailnet as a MagicDNS host: k8s-1, k8s-2, k8s-3. This is the default remote path. Prefer MagicDNS hostnames over Tailscale 100.x.x.x IPs in any output that might be saved or shared.

The Tailscale extension is configured per-node in talos/patches/<hostname>/; the auth key is in talos/talenv.sops.yaml. State is in memory (TS_STATE_DIR=mem:), so nodes re-register with a -1 suffix after reboot — clean up the old node in the Tailscale admin console.

talosctl

The generated talosconfig at talos/clusterconfig/talosconfig is gitignored (produced by task talos:generate-config). It bakes in the LAN IPs as default endpoints, so when working off-LAN you must override with -e:

# Single node
talosctl --talosconfig ./talos/clusterconfig/talosconfig -e k8s-1 -n k8s-1 <cmd>

# Fan out to all nodes (pick any reachable node as the -e endpoint)
talosctl --talosconfig ./talos/clusterconfig/talosconfig \
  -e k8s-1 -n k8s-1,k8s-2,k8s-3 <cmd>

Common read-only queries:

talosctl ... get disks        # block devices (NVMe, loops, rbd)
talosctl ... get members      # cluster membership
talosctl ... get addresses    # interface addresses
talosctl ... version          # server vs client version skew
talosctl ... dmesg -f         # kernel log (follow)
talosctl ... logs <service>   # machined / kubelet / etcd / etc.

If talosctl errors with failed to determine endpoints or talos config file is empty, the default ~/.talos/config has no context set — always pass --talosconfig ./talos/clusterconfig/talosconfig explicitly from the repo root.

kubectl

Kubernetes API access also flows over Tailscale when remote. The cluster_api_addr in cluster.yaml is a LAN VIP, so the kubeconfig server URL may need to point at a Tailscale-reachable endpoint (a node hostname or the VIP if it is also advertised on the tailnet). Check the active context before troubleshooting connectivity:

kubectl config current-context
kubectl config view --minify

What NOT to commit

Per the top-level CLAUDE.md rule: never write the real tailnet name into any file under git. Use the placeholder <tailnet-name>.ts.net in documentation, examples, and commit messages. MagicDNS short hostnames (k8s-1 etc.) are fine — they are not tailnet-identifying on their own. Tailscale 100.x.x.x IPs should also be avoided in committed files.

If you discover a real tailnet name in the working tree, do not commit until it has been replaced with the placeholder.

Troubleshooting

Symptom	Likely cause	Fix
failed to determine endpoints	no -e flag and default config has no context	pass --talosconfig ./talos/clusterconfig/talosconfig -e <host>
talos config file is empty	~/.talos/config has never been populated	same — point at the repo's talosconfig explicitly
i/o timeout on a 192.168.x.x IP	off-LAN; LAN addresses unreachable	switch to Tailscale MagicDNS hostname (k8s-1 etc.)
server version X is older than client version Y	client/server skew, harmless until a major release	plan a Talos upgrade via the upgrade-talos-or-k8s skill
Tailscale host not resolving	device signed out / key expired	re-auth the node's Tailscale extension via the patch under talos/patches/<hostname>/
kubectl hangs from off-LAN	kubeconfig server URL is the LAN VIP, no Tailscale route to it	confirm with kubectl config view --minify; switch to a tailnet-reachable endpoint

Related skills

• Upgrading Talos or Kubernetes versions → upgrade-talos-or-k8s
• Adding or replacing a node → add-or-replace-node
• Triaging a Flux sync that looks broken from a remote workstation → debug-flux-reconciliation