Skip to content
KSail

Day-2 Operations

A cluster that exists is only half the story — day-2 is where you live. KSail bundles the commands you reach for after cluster create:

You want to…Run
See cluster status and endpointsksail cluster info
List all clusters across providersksail cluster list
Jump to another cluster's contextksail cluster switch
Browse the cluster interactivelyksail cluster connect (K9s)
Find out why something is failingksail cluster diagnose
Check config drift before it bitesksail cluster diff — see Drift Detection
Fix corrupted local state filesksail cluster repair

Diagnosing a Failing Cluster

Section titled “Diagnosing a Failing Cluster”

ksail cluster diagnose inspects the live cluster via the Kubernetes API and reports pods that are not running successfully, nodes that are not Ready, and PersistentVolumeClaims stuck in Pending. Each finding carries a severity, and known failure patterns come with a proactive remediation suggestion.

A health score (0–100) summarizes the whole picture: each critical finding deducts 25 points, each warning deducts 10.

Terminal window
ksail cluster diagnose                 # human-readable findings + health score
ksail cluster diagnose --output json  # structured output for scripts and CI

The output is intentionally compact so it can be consumed by people and machines — the AI chat assistant and MCP server expose diagnose through the cluster_read tool and feed the findings back to the model as context for root-cause analysis.

Switching Between Clusters

Section titled “Switching Between Clusters”

Running several clusters side by side is the norm with KSail — cluster switch makes hopping between them painless. Give it a cluster name and it resolves the right kubeconfig context automatically, checking all distribution prefixes (kind-, k3d-, k3k-, admin@, vcluster-docker_, kwok-) so you never type a prefixed context name by hand:

Terminal window
ksail cluster switch dev       # resolves to kind-dev, k3d-dev, … automatically
ksail cluster switch           # interactive picker

Called without arguments, an interactive picker opens with your five most recently used clusters at the top, followed by the rest alphabetically (history persists to ~/.ksail/switch-history.json). Press / to filter the list by keyword, Esc to clear the filter.

If two distributions both have a cluster with the same name, the command errors with the matching contexts rather than guessing.

Repairing Local State

Section titled “Repairing Local State”

ksail cluster repair detects and fixes known corruption patterns in local state files. Every repair is idempotent and writes a timestamped backup of any file it modifies before touching it.

Terminal window
ksail cluster repair

Currently supported: talosconfig-ca — fixes a single-byte BasicConstraints corruption in the Talos talosconfig CA that prevents cluster update from establishing a Talos client.

Section titled “Related”