Fleet management

This chapter covers the Fleet tab of kube-dc bootstrap and the kubeconfig writer (kube-dc bootstrap kubeconfig).

Browse the fleet (kube-dc bootstrap)

The no-arg form opens the integrated bootstrap TUI on the Fleet tab, the single dashboard for every cluster the team operates. From there ] / [ cycle to other tabs (for example, Contexts), and Tab cycles pane focus within the Fleet view.

kube-dc bootstrap

What you should see:

• One row per clusters/<name>/ directory in the fleet repo.
• A status pill per row: Ready (green), Reconciling (blue), Drifted (orange), Failed (red), Unreachable (grey), Unknown (purple).
• The selected row's details (cluster, server, IP, ext-net, per-Kustomization breakdown, image-tag drift if any) in the bottom pane.

Pane focus & arrow scoping (BIOS-style)

The screen has two panes: cluster list (top) and cluster details (bottom). Exactly one pane has keyboard focus at a time, marked by a highlighted border.

• Tab cycles focus forward (list → details → list); Shift+Tab cycles backward.
• ↑ / ↓ (and pgup / pgdown / g / G) act on the focused pane only.
  • List pane focused → arrows move the cluster cursor.
  • Details pane focused → arrows move the cursor within the Kustomizations sub-list (or scroll the viewport when no Kustomization rows are present).
• Esc from any non-list pane jumps focus back to the cluster list.

This mirrors UEFI and BIOS setup, htop's field selector, and dialog-based installers. There are fewer collisions per screen, because a key such as ↵ can mean different things depending on which pane has focus.

Actionable status (↵ on a row runs the suggested fix)

When a cluster row's status detail says not logged in. Run: kube-dc login --domain X --admin or auth failed (403), pressing ↵ (Enter) on that row runs the suggested command without leaving the TUI. The TUI knows the cluster's domain and the canonical fleet identity is platform-admin, so there's no copy-paste step. While the dispatched login is in flight the row's status pill switches to Running so you see your click landed.

For Ready rows, ↵ shifts focus into the details pane so you can drill into Kustomizations directly without a Tab.

Drill-down for kustomizations (right-side panel)

When the details pane has focus and a Kustomization row is selected, pressing ↵ opens a right-side drill-down panel showing the full condition Reason and Message. Use it when a Kustomization is ✗ NoReadyCondition or Reconciliation failed and you need to see why without leaving the TUI.

• The bottom pane splits 60/40: details on the left, drill-down on the right.
• Focus moves to the drill-down panel automatically. Arrow keys scroll its content.
• The drill-down also surfaces the exact kubectl describe and flux logs commands so you can copy-paste for deeper investigation.
• Esc closes the drill-down and returns focus to the details pane.

Keys

The help bar at the bottom only lists keys that are actionable in the current state (for example, ↵ open only when the cursor sits on a row that has something to open). Press ? for the expanded list.

Key	Action
↑/k, ↓/j, pgup, pgdown, g, G	Navigate the focused pane
Tab / Shift+Tab	Cycle pane focus (list ↔ details ↔ drill-down)
↵	List: run row's FixAction (admin login) when present, else step into details. Details: open Kustomization drill-down.
Esc	Close drill-down / return focus to list
L	Admin login for the selected cluster. Suspends the TUI, runs kube-dc login --domain X --admin so the browser opens, then resumes and re-probes the row. Works on any row regardless of FixAction.
l	Organization login (the Organization prompt is not yet available here; run kube-dc login --org outside the TUI).
r	Refresh (re-runs probes against every cluster)
?	Toggle full help
q	Quit

The status pills refresh every 60 s in the background, so you do not need to keep pressing r.

First-time state

Every row will show Unreachable until you log in to the cluster (the probe needs a working OIDC token to call the API server). Press ↵ on a row, and the TUI routes to admin login. There is no Tab and no copy-paste.

---

Get a kubeconfig (kube-dc bootstrap kubeconfig)

Materialize a kubeconfig context for one cluster, without committing credentials anywhere.

kube-dc bootstrap kubeconfig <cluster>

By default the kubeconfig is wired for the admin identity (master realm). The context name is kube-dc/<cluster>/admin and the exec plugin will use --realm master. After the kubeconfig lands you still need one kube-dc login --domain <cluster-domain> --admin to mint OIDC tokens.

Examples:

# Default: admin-flavored kubeconfig
kube-dc bootstrap kubeconfig <cluster>
kube-dc login --domain <cluster-domain> --admin
kubectl get nodes        # cluster-admin

# Preview without modifying anything
kube-dc bootstrap kubeconfig <cluster> --dry-run

# Organization-realm override (rarely needed; prefer `kube-dc login --org` directly)
kube-dc bootstrap kubeconfig <cluster> --realm <org-name>

# Also commit the synthesised kubeconfig.template.yaml back to the fleet
kube-dc bootstrap kubeconfig <cluster> --commit

What it does:

• Reads clusters/<cluster>/cluster-config.env from the fleet.
• Probes the API server's TLS handshake to fetch the cluster CA (or skips when system trust covers it).
• Writes ONE new context into your ~/.kube/config, leaving every other context alone. The name is kube-dc/<cluster>/admin by default, or kube-dc/<cluster>/<realm> with an Organization-realm override.
• The user entry's exec plugin always pins --realm in args, so kubectl never silently picks up the wrong cached identity.

Flags:

Flag	Purpose
--realm <name>	Realm to wire the kubeconfig for. Empty / unset → master (admin). Pass an Organization name for an Organization-realm context.
--dry-run	Print what would change; touch nothing
--commit	Also write a kubeconfig.template.yaml back to clusters/<cluster>/ (does not push)
--ca-cert <path>	Bring your own CA file (skips the TLS-handshake fetch)
--insecure-skip-tls-verify	Last resort for self-signed test clusters
--set-current (default true)	Switch current-context to the new context

tip

Organization users rarely need this command. kube-dc login --domain X --org Y writes one named context per accessible Project, and kube-dc use X/Y/<project> selects the intended Project context. bootstrap kubeconfig is mostly an operator convenience for wiring kubectl before or outside an admin login.