cluster-context-manager

Cluster Context Manager

Unified kubectl and talosctl context management using kubecm for kubectl contexts and native talosctl commands for talosctl contexts.

Autonomy Model

Auto-execute (read-only, safe):

• kubecm list -- list kubectl contexts
• kubecm switch <name> -- switch kubectl context
• kubecm export -- export a context to file
• talosctl config contexts -- list talosctl contexts
• talosctl config context <name> -- switch talosctl context
• kubectl config current-context -- show current context

Confirm before running (mutating):

• kubecm delete -- remove contexts
• kubecm clear -- remove unreachable contexts
• kubecm merge -- merge kubeconfig files
• kubecm rename -- rename a context
• kubecm add -- add kubeconfig from file
• talosctl config merge -- merge talosconfig files
• pass insert -- push configs to pass (overwrites existing)
• pass import workflows -- pull configs from pass and merge locally

Shell Integration

kubecm shell completions and environment live in ~/.zshrcd/conf.d/kubecm.zsh:

# kubecm - kubeconfig manager
# Skip faster listing by default (avoids cluster queries)
export KUBECM_DISABLE_K8S_MORE_INFO=true

# Completions
if command -v kubecm >/dev/null 2>&1; then
    source <(kubecm completion zsh)
fi

To create and track this file:

# Create the file
cat > ~/.zshrcd/conf.d/kubecm.zsh << 'EOF'
# kubecm - kubeconfig manager
export KUBECM_DISABLE_K8S_MORE_INFO=true

if command -v kubecm >/dev/null 2>&1; then
    source <(kubecm completion zsh)
fi
EOF

# Reload shell
source ~/.zshrcd/conf.d/kubecm.zsh

# Track with yadm
yadm add ~/.zshrcd/conf.d/kubecm.zsh
yadm commit -m "Add kubecm zsh configuration"
yadm push

Naming Conventions

kubectl Contexts

Follow the admin@cluster-name pattern:

Cluster	Context Name
Production	admin@annarchy
Staging	admin@staging
Ephemeral CMX	Keep default CMX name (e.g., k3s-31fb879f-default)

After talosctl kubeconfig generates a new context, rename if it doesn't match:

# Check current name
kubecm list

# Rename to convention if needed
kubecm rename <auto-generated-name> admin@annarchy

talosctl Contexts

talosctl contexts use short names matching the cluster:

Cluster	Context Name
Production	annarchy
Staging	staging

kubecm Command Reference

Command	Aliases	Purpose	Auto-execute?
kubecm list	ls, l	List all contexts with cluster info	Yes
kubecm switch	s, sw	Switch context (interactive or by name)	Yes
kubecm switch <name>		Switch to named context	Yes
kubecm namespace	ns	Switch namespace interactively	Yes
kubecm ns <name>		Switch to named namespace	Yes
kubecm export -f <file> <ctx>	e	Export context to standalone file	Yes
kubecm add -f <file>	a	Merge kubeconfig file into default	Confirm
kubecm add -f <file> --context-name <name>		Add with custom context name	Confirm
kubecm merge <files...>	m	Merge multiple kubeconfig files	Confirm
kubecm merge -f <dir>		Merge all files in directory	Confirm
kubecm delete <ctx>	d	Delete context (cleans orphans)	Confirm
kubecm rename <old> <new>	r	Rename a context	Confirm
kubecm clear		Remove unreachable/stale contexts	Confirm
kubecm alias -o zsh	al	Generate shell aliases for contexts	Confirm

Key Flags

Flag	Commands	Purpose
--context-name <name>	add	Override the context name on import
--context-prefix <pfx>	add, merge	Prefix prepended to context names
-c / --cover	add	Overwrite existing config (use carefully)
--select-context	add, merge	Interactive context selection from file
-f	add, merge, export	File path (input or output)

talosctl Context Reference

Command	Purpose	Auto-execute?
talosctl config contexts	List all talosctl contexts	Yes
talosctl config context <name>	Switch to named context	Yes
talosctl config merge <file>	Merge talosconfig from file	Confirm
talosctl kubeconfig --force	Generate kubectl config from cluster	Confirm

Pass Storage (Cross-Workstation Sync)

Kubeconfigs and talosconfigs are stored in pass for distribution across workstations. Pass is synced via GPG-encrypted git, so any workstation with the GPG key can pull configs.

Pass Layout

Pass Entry	Contents	Local File
fleet-infra/annarchy.net/kubeconfig	Production kubeconfig (single context: admin@annarchy)	~/.kube/config-annarchy
fleet-infra/staging.annarchy.net/kubeconfig	Staging kubeconfig (single context: admin@staging)	~/.kube/config-staging
fleet-infra/annarchy.net/talosconfig	Production talosconfig (single context: annarchy)	Merged into ~/.talos/config
fleet-infra/staging.annarchy.net/talosconfig	Staging talosconfig (single context: staging)	Merged into ~/.talos/config

Key difference: Kubeconfigs are stored as separate files per cluster. Talosconfigs are stored separately in pass but merged into a single ~/.talos/config locally.

Import from Pass (New Workstation / Restore)

Pull configs from pass and import them locally:

# 1. Import kubeconfigs from pass
pass fleet-infra/annarchy.net/kubeconfig > /tmp/kubeconfig-annarchy.yaml
pass fleet-infra/staging.annarchy.net/kubeconfig > /tmp/kubeconfig-staging.yaml

# 2. Place kubeconfig files (kubecm uses ~/.kube/config as default)
cp /tmp/kubeconfig-annarchy.yaml ~/.kube/config-annarchy
cp /tmp/kubeconfig-staging.yaml ~/.kube/config-staging
chmod 600 ~/.kube/config-annarchy ~/.kube/config-staging

# 3. Merge into kubecm-managed config
kubecm add -f ~/.kube/config-annarchy --context-name admin@annarchy
kubecm add -f ~/.kube/config-staging --context-name admin@staging

# 4. Import talosconfigs from pass
pass fleet-infra/annarchy.net/talosconfig > /tmp/talosconfig-annarchy.yaml
pass fleet-infra/staging.annarchy.net/talosconfig > /tmp/talosconfig-staging.yaml

# 5. Merge talosconfigs (creates ~/.talos/config if missing)
talosctl config merge /tmp/talosconfig-annarchy.yaml
talosctl config merge /tmp/talosconfig-staging.yaml

# 6. Clean up temp files
rm -f /tmp/kubeconfig-annarchy.yaml /tmp/kubeconfig-staging.yaml
rm -f /tmp/talosconfig-annarchy.yaml /tmp/talosconfig-staging.yaml

# 7. Verify
kubecm list
talosctl config contexts

Export to Pass (Push After Bootstrap / Rotation)

After generating new configs (cluster bootstrap, cert rotation, etc.), push to pass:

# 1. Push kubeconfigs to pass (multiline insert)
cat ~/.kube/config-annarchy | pass insert -m fleet-infra/annarchy.net/kubeconfig
cat ~/.kube/config-staging | pass insert -m fleet-infra/staging.annarchy.net/kubeconfig

# 2. Extract per-cluster talosconfigs from the merged ~/.talos/config
#    talosctl has no export command, so use yq to extract individual contexts
yq eval '{"context": "annarchy", "contexts": {"annarchy": .contexts.annarchy}}' ~/.talos/config > /tmp/talosconfig-annarchy.yaml
yq eval '{"context": "staging", "contexts": {"staging": .contexts.staging}}' ~/.talos/config > /tmp/talosconfig-staging.yaml

# 3. Push talosconfigs to pass
cat /tmp/talosconfig-annarchy.yaml | pass insert -m fleet-infra/annarchy.net/talosconfig
cat /tmp/talosconfig-staging.yaml | pass insert -m fleet-infra/staging.annarchy.net/talosconfig

# 4. Clean up
rm -f /tmp/talosconfig-annarchy.yaml /tmp/talosconfig-staging.yaml

# 5. Verify hashes match
echo "=== local vs pass (annarchy kubeconfig) ==="
diff <(cat ~/.kube/config-annarchy | shasum) <(pass fleet-infra/annarchy.net/kubeconfig | shasum)
echo "=== local vs pass (staging kubeconfig) ==="
diff <(cat ~/.kube/config-staging | shasum) <(pass fleet-infra/staging.annarchy.net/kubeconfig | shasum)

Note: talosctl has no export subcommand. Use yq to extract individual contexts from the merged ~/.talos/config.

Rotation Workflow

When cluster certs are rotated or a cluster is rebuilt:

1. Generate new kubeconfig: talosctl kubeconfig --force -n <node>
2. Rename context if needed: kubecm rename <auto-name> admin@annarchy
3. Export the updated kubeconfig file: kubecm export -f ~/.kube/config-annarchy admin@annarchy
4. Push to pass using the export workflow above
5. On other workstations: pull using the import workflow above

Workflows

Status Check

Show the full picture of both kubectl and talosctl contexts:

echo "=== kubectl contexts ==="
kubecm list

echo ""
echo "=== talosctl contexts ==="
talosctl config contexts

echo ""
echo "=== Current kubectl context ==="
kubectl config current-context

Post-Bootstrap Context Setup

After talosctl kubeconfig --force generates a new kubectl context during cluster bootstrap:

1. Check what was created:

   kubecm list
   

2. Rename to match convention:

   kubecm rename <auto-generated-name> admin@talos-staging
   

3. Verify:

   kubecm switch admin@talos-staging
   kubectl get nodes
   

Cross-reference: See proxmox-manager skill, talos-cluster-bootstrap runbook step 11.

Stale Context Cleanup

Remove contexts from destroyed clusters or expired CMX environments:

1. List current contexts:

   kubecm list
   

2. Identify stale entries (CMX contexts like k3s-*-default, or contexts for destroyed clusters).

3. Delete specific stale contexts:

   kubecm delete k3s-31fb879f-default
   

4. Or clear all unreachable contexts at once:

   kubecm clear
   

5. Verify cleanup:

   kubecm list
   

Cross-reference: See proxmox-manager skill, cluster-teardown runbook cleanup notes.

Merge External Kubeconfig

When you receive a kubeconfig file (from talosctl, Replicated CMX, a colleague, etc.):

# Add with custom context name
kubecm add -f ~/Downloads/new-cluster.yaml --context-name admin@new-cluster

# Or add with interactive selection (multi-context files)
kubecm add -f ~/Downloads/multi-cluster.yaml --select-context

# Or merge an entire directory of kubeconfig files
kubecm merge -f ~/.kube/configs/

Export a Context

Extract a specific context into a standalone kubeconfig file for sharing or backup:

kubecm export -f ~/exported-staging.yaml admin@talos-staging

Switch Context

# Interactive (arrow-key selection)
kubecm switch

# Direct
kubecm switch admin@talos-staging

# Switch talosctl context too
talosctl config context staging

Integration Points

proxmox-manager Skill

The proxmox-manager skill handles cluster lifecycle (bootstrap, upgrade, teardown). This skill handles the context management that follows:

• After bootstrap: Rename the auto-generated kubectl context with kubecm rename
• After teardown: Clean up stale contexts with kubecm delete or kubecm clear

replicated-cli Skill

Replicated CMX clusters generate kubeconfig via replicated cluster kubeconfig <id>. These contexts use auto-generated names like k3s-<hash>-default. Clean them up after the CMX cluster is removed.

pass (Password Store)

Kubeconfigs and talosconfigs are stored in pass under fleet-infra/<cluster>/. See the Pass Storage section above for the full layout and import/export workflows. Pass is the canonical distribution mechanism for syncing configs to other workstations.

• After cluster bootstrap or cert rotation, push updated configs to pass
• On a new workstation, import from pass after pass git pull

home-manager Agent

For kubeconfig or context management questions, home-manager should route to this skill.

zsh-config-manager Skill

The shell integration file (~/.zshrcd/conf.d/kubecm.zsh) follows conf.d conventions. Use zsh-config-manager for guidance on the conf.d pattern itself.

Troubleshooting

Problem	Diagnosis	Fix
kubecm list shows stale contexts	Cluster was destroyed	kubecm delete <ctx> or kubecm clear
Context name doesn't match convention	Auto-generated by talosctl/CMX	kubecm rename <old> admin@<cluster>
Duplicate context names after merge	Multiple files with same context	kubecm add -f <file> --context-name <unique-name>
kubecm switch hangs	Cluster info query on unreachable cluster	Set KUBECM_DISABLE_K8S_MORE_INFO=true
kubectl and talosctl point to different clusters	Contexts managed independently	Switch both: kubecm switch admin@talos-staging && talosctl config context staging
Shell completions not working	conf.d file not sourced	source ~/.zshrcd/conf.d/kubecm.zsh or exec zsh
kubecm command not found	Not installed	brew install kubecm
pass configs out of date	Configs rotated but not pushed	Run export-to-pass workflow, then pass git push
pass insert prompts for overwrite	Entry already exists	Pipe through stdin: cat file | pass insert -m path (confirms overwrite)
talosconfig merge fails	Duplicate context name conflict	Remove existing context first: talosctl config remove <name>, then re-merge
New workstation missing configs	pass not synced	pass git pull then run import-from-pass workflow