Access triage

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

Access triage

Use this when access is not working — kubectl errors, target use fails, a cluster is missing, a login expired — or when you need baseline facts (version, selection, freshness, prerequisites) before diagnosing anything.

Four causes look identical from outside: a missing prerequisite, an expired or never-established identity, a stale cache, or a cluster that is genuinely gone. The step order separates them cheapest-first.

Preconditions

• kuberoutectl on PATH.
• The user can name the cluster, or at least the provider. If not, resolve the reference via target-selection first.

Commands

# read-only
kuberoutectl version
kuberoutectl current
kuberoutectl doctor
kuberoutectl target inspect <alias|id|name>
kuberoutectl credential list
kuberoutectl credential list --provider azure
kuberoutectl credential show <id>
kuberoutectl inventory providers
kuberoutectl inventory scopes

# Tier 4 — re-authenticates a real identity, may open a browser. Confirm first.
kuberoutectl credential renew <id>

Steps

1. Baseline. version, current, doctor — which binary, what is selected, how stale, whether provider CLIs resolve. Not ok in doctor is an install problem; stop there.

2. Freshness. Last sync from current. Older than ~a day makes everything below a hypothesis: note it, continue, re-sync before delivering a verdict.

3. The target's view. target inspect <ref> → Health, Action, Credential. Action routes:

   Action	Meaning	Go to
   use	identity is fine	step 6 — not an identity problem
   renew	expired, re-authenticable	step 5
   manual	cannot re-auth from here	step 5

4. The identity behind it. credential show <credential-id>, taking the id from the Credential line. That field is the join from "cluster unreachable" to "identity expired".

5. Can this provider renew? inventory providers → RENEW. no means renew cannot succeed; the fix is at the source (provider login, AWS profile, kubeconfig file) — name that source. yes plus action_hint: renew is the only case where offering renew is correct.

6. Cluster missing? inventory scopes. No scopes = the identity sees no subscription / account / project, an auth or permissions boundary. Scopes present but target absent = deleted upstream, or this identity lost visibility.

7. Identity fine, still unreachable. kuberoutectl has told you all it knows; what remains is network, RBAC, or control plane. Say you have moved past the brokering layer, then kubectl cluster-info / kubectl auth can-i get pods.

Reading the result

$ kuberoutectl credential list
ID                            PROVIDER  IDENTITY          HEALTH   ACTION
gcp:account:[email protected]  gcp       [email protected]  valid    use
aws:default                   aws                         unknown  manual

Two different situations:

• valid / use — ready. If a cluster on this provider is unreachable, the cause is not this credential. Go to step 7.
• unknown / manual / no identity — no session was ever established. Fix is aws sso login, not credential renew. The identity key is absent from the JSON, not empty; code testing identity == "" misses it.

$ kuberoutectl inventory providers
PROVIDER    RENEW  REAUTH  SCOPES  SWITCH  STATIC
aws         yes    yes     yes     yes     yes
kubeconfig  no     no      yes     yes     yes

RENEW no — static credentials must be replaced at the file; renewal is impossible.

version prints 1.0.0 for a release (no leading v) or 0.0.0-snapshot-<sha> for a development build. A snapshot is not an outdated release.

MCP tools

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

Step	MCP tool	Fallback
1 — selection + freshness	get_status	—
1 — version	initialize → serverInfo.version	kuberoutectl version
1 — prerequisites	no tool	kuberoutectl doctor
3 — the target's view	get_target	—
4 — the identity	list_credentials, filter on the id	credential show <id>
5 — can this provider renew	list_providers → can_renew	—
5 — renew	withheld on purpose	credential renew, CLI only
6 — cluster missing	list_scopes	—

The whole read path works under --read-only. credential renew has no tool in either mode — the guardrail, not a gap: the one step that re-authenticates a real identity stays a deliberate CLI action. doctor is a genuine gap, so an MCP-only client cannot rule out a missing provider binary — report that as a gap in your evidence rather than skipping step 1. Map: mcp-tools.

Fields

action_hint table, health semantics, freshness rule: reading-output.

target.credential_id  → credential.id   which identity reaches this cluster
target.scope_id       → scope.id        which account/project it lives in

Safety

• Steps 1–4, 6, 7 are Tier 1.
• credential renew is Tier 4: it re-authenticates a real identity and may open a browser. Confirm first, and never run it when RENEW is no.
• kuberoutectl stores no secrets. Never ask the user to paste a token or password.
• Separate facts from interpretation. "Last sync was 3 days ago, so this health may be stale" is a fact about your evidence — say it rather than asserting a conclusion you cannot support.

Common pitfalls

• Running renew first. Most disruptive step, and wrong for manual and for RENEW no providers. It is step 5.
• Calling unknown broken. It usually means never observed.
• Renewing the wrong identity. One provider holds many credentials — take the id from the affected target's Credential line.
• Diagnosing on stale data. Check Last sync first.
• Blaming kuberoutectl for a permissions boundary. Empty inventory scopes is the cloud saying no.
• Stopping at "identity is valid". That is a finding: the problem is downstream. Say so and hand off rather than looping.
• Reporting a snapshot build as outdated.

References

https://ymedlop.github.io/kuberoutectl/ · provider guides