Inventory discovery

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

Inventory discovery

Use this when the user asks "what clusters / access do I have?", is starting fresh, says the list looks stale, or found fewer clusters than expected.

kuberoutectl asks each provider's own CLI (Azure, AWS, GCP) or reads local kubeconfig files, then records what it finds in a local JSON cache. Everything else — routing, triage — reads that cache.

Preconditions

• kuberoutectl on PATH (install).
• The provider's own CLI installed and logged in. doctor checks the first, not the second.
• AWS across more than one account: profiles must exist in ~/.aws/config first — step 3. Without them sync aws finds one account and the user assumes clusters are missing.

Commands

# read-only
kuberoutectl doctor
kuberoutectl inventory providers
kuberoutectl inventory sources
kuberoutectl inventory scopes
kuberoutectl target list
kuberoutectl target label list <alias|id|name>

# refresh — idempotent; user labels, collections, visibility all survive
kuberoutectl sync azure
kuberoutectl sync aws
kuberoutectl sync gcp
kuberoutectl sync kubeconfig

# writes ~/.aws/config — additive, confirm first
kuberoutectl setup aws-sso --sso-session <name>
kuberoutectl setup aws-sso --sso-session <name> --role <role> --region <region>

# cache cleanup — destructive, confirm first
kuberoutectl target delete <alias|id|name>
kuberoutectl target clear

Steps

1. Prerequisites. doctor. Anything not ok is an install problem — resolve it via the matching provider guide.
2. Providers in scope. Ask, or infer from doctor. Only sync clouds the user has; each unnecessary sync can trigger a login prompt.
3. AWS multi-account, if applicable. setup aws-sso enumerates every account reachable through an IAM Identity Center session and appends one kr-<account>-<role> profile per account. Needs a live session first — aws sso login --sso-session <name>, which the user runs. Pass --role deliberately: the default is AdministratorAccess when present, over-privileged for inspection. Pass --region if EKS lives outside the session's sso_region.
4. Sync, one provider at a time. Sync is not transactional — a failure midway leaves a partial cache, so read each result before starting the next.
5. Verify. target list, then inventory scopes for breadth. For AWS, expect one scope per account.

Reading the result

$ kuberoutectl doctor
CHECK                STATUS  DETAIL
provider:aws         ok      resolved at /usr/local/bin/aws
provider:gcp         ok      resolved at /opt/homebrew/bin/gcloud

$ kuberoutectl target list
ALIAS         PLATFORM  REGION        HEALTH  PROVIDER
cluster-test  gke       europe-west3  valid   gcp

• doctor — binary resolution only. ok means the CLI was found, not that the user is logged in. A fully green doctor with no session yields an empty sync.
• target list — ALIAS is a short handle but not unique across environments; see reference-resolution. Hidden targets are omitted unless you pass --all.
• inventory scopes — one row per subscription / account / project. Empty scopes is the diagnostic: the identity sees no administrative boundary, which is an auth or permissions problem, not a kuberoutectl one.

To show exactly what a sync changed, diff the ids:

kuberoutectl target list -o json > /tmp/before.json
kuberoutectl sync gcp
kuberoutectl target list -o json > /tmp/after.json
diff <(jq -r '.[].id' /tmp/before.json | sort) <(jq -r '.[].id' /tmp/after.json | sort)

MCP tools

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

Step	MCP tool	Fallback
List what was found	list_targets	—
Confirm breadth	list_scopes, list_sources	—
Provider capabilities	list_providers	—
Freshness of the cache	get_status → synced_at	—
Refresh	sync_provider	full mode only; absent under --read-only
Prerequisites	no tool	kuberoutectl doctor
AWS profile generation	no tool	kuberoutectl setup aws-sso
Cache cleanup	withheld on purpose	target delete / target clear, CLI only

Steps 1 and 3 are the CLI-only parts: doctor and setup aws-sso have no tool, so an MCP-only client cannot complete first-time setup and should say so rather than skipping the checks. Map: mcp-tools.

Fields

reading-output for field names, action_hint, and the freshness rule; selectors for grammar. id is the stable diff key — alias and name are not.

Safety

• doctor, inventory *, target list, label list are Tier 1.
• sync is Tier 2 — safe to re-run, never discards user labels, collections, or visibility. It may trigger the provider CLI's login; let the user complete it.
• setup aws-sso writes ~/.aws/config, additive only: appends missing profiles, never modifies existing ones. Name the file and confirm first. It creates nothing in AWS itself.
• target delete removes one target from the cache; a later sync re-adds it. No prompt, so confirm first. target clear removes all and prompts unless --yes — never pass --yes on the user's behalf.
• Never ask the user to paste a token, key, or session value.

Common pitfalls

• doctor all green, sync still empty. Not logged in — doctor does not test sessions.
• AWS shows one account when the user has many. Missing ~/.aws/config profiles, step 3. The single most common cause of "it only found some of my clusters".
• Profiles generated but still one scope. The SSO session expired between setup and sync. Re-login, re-sync.
• Empty target list after a successful sync. Check inventory scopes first. No scopes = permissions boundary. Scopes but no targets = no clusters there, or the wrong region.
• A re-created cluster loses its labels. Labels survive sync but attach to the target id; re-creating upstream mints a new id and the labels do not follow. Users mistake this for sync eating their labels.
• Reporting health: unknown as broken. It usually means never observed.
• target clear with no resync. Leaves an empty list and no explanation.

References

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