Target selection

<!-- Frontmatter is generic metadata for humans and index/marketplace scanning. It is NOT parsed at runtime by any specific AI client. -->

Target selection

Use this when the user wants kubectl pointed at a specific cluster — "switch me to prod", "which one am I on?", "get me credentials for X".

target use fetches a cluster's credentials into ~/.kube/config and makes it the current context — an immediate change to what the user's kubectl talks to. Most of this skill is the verification that comes before that, because aliases and names are convenience strings and neither is unique: the same cluster name routinely exists in a dev subscription and a prod one.

Preconditions

• Inventory synced at least once — inventory-discovery.
• You know which environment the user means. Verification confirms a match; it cannot invent one. If you don't know, ask before selecting.

Commands

# read-only
kuberoutectl target list
kuberoutectl target list --all
kuberoutectl target list --wide
kuberoutectl target list --provider azure
kuberoutectl target list --selector env=prod
kuberoutectl target inspect <alias|id|name>
kuberoutectl current

# Tier 3 — rewrites ~/.kube/config and moves the active context
kuberoutectl target use <alias|id|name>
kuberoutectl target use <alias|id|name> --no-kubeconfig

Steps

1. Find candidates. target list, narrowed with --provider or --selector. --wide adds the full ID column.
2. Check ambiguity first. Count matches for the reference the user gave: target list -o json, filter client-side on name and alias. More than one match means the reference is unsafe — show the candidates with their scope_id and region, and ask. Never pick the first row.
3. Verify the identity facts. target inspect <ref> → ID, Scope, Region, Endpoint. Scope is the authority: the subscription / account / project a user can recognise. A name containing "prod" proves nothing.
4. Confirm in scope terms. Not "cluster-test?" but "the GKE cluster cluster-test in project project-9adf…, region europe-west3 — correct?"
5. Select using the full id when the phrasing was loose.
6. Confirm it answers. Selection is not reachability: kuberoutectl current, kubectl config current-context, kubectl cluster-info. The server address should match endpoint. If it fails, go to access-triage.

--no-kubeconfig records the choice without touching kubeconfig or the active context.

Reading the result

$ kuberoutectl target inspect cluster-test
Alias         cluster-test
ID            gcp:project-REDACTED:europe-west3:cluster-test
Region        europe-west3
Endpoint      https://203.0.113.10
Version       1.35.5
Health        valid
Action        use
Scope         gcp:project:project-REDACTED
Credential    gcp:account:[email protected]

Field	What it proves
id	The unambiguous handle — provider, scope, region, name
scope_id	Which subscription / account / project. Separates prod from dev
endpoint	Control plane address — the fingerprint to match against cluster-info
credential_id	Which identity is used. Hands off to access-triage
health / action_hint	Whether it is usable as of the last sync

alias, name, and platform prove nothing about which environment you are in.

$ kuberoutectl current
Target     cluster-test (cluster-test)
Health     valid
Action     use
Selected   7d ago
Last sync  1d ago

Selected and Last sync are two independent clocks — when the user chose it, and how old the provider-derived health is. Say which you mean.

MCP tools

Prefer the tool; drop to the CLI only where none exists, and say so.

Step	MCP tool	Fallback
Find candidates	list_targets (provider, selector)	—
Count matches for ambiguity	list_targets, filter client-side	—
Verify identity facts	get_target	—
Confirm current selection	get_status	—
Select	use_target + activate: true	full mode only; absent under --read-only
Record only, no kubeconfig	use_target, activate unset	full mode only
Confirm reachability	no tool	kubectl cluster-info

Steps 1–4 — the whole verification half — work under --read-only. Only the selection needs full mode, which is the boundary you want: an MCP client cannot move a user's kubectl context by accident. Note get_target errors on an unknown ref rather than returning empty. Map: mcp-tools.

Fields

reading-output for fields and action_hint; reference-resolution for alias vs id vs name; selectors for grammar.

Safety

• target list, inspect, current are Tier 1. Verification changes nothing — and stopping when the answer is ambiguous is the correct outcome, not a failure.
• target use is Tier 3: it rewrites ~/.kube/config and moves the active context. Confirm which cluster first, especially when prod and non-prod look alike.
• If target use reports a credential problem, go to access-triage.

Common pitfalls

• Acting on an alias the user said out loud. cluster-test in dev and in prod are different targets. Resolve to id first.
• Inferring environment from the name. "prod" in a name is a string; scope_id is the fact.
• Treating Health valid as live. It is the last sync's opinion.
• target use succeeded, kubectl still fails. Selection wrote kubeconfig; reachability is separate — network, RBAC, control plane.
• Assuming the active context is what kuberoutectl last selected. Anything can rewrite kubeconfig. current reports kuberoutectl's record; kubectl config current-context reports reality. Compare both.
• Missing that target also answers to clusters and cluster.

References

https://ymedlop.github.io/kuberoutectl/ · organizing