Getting started

Getting started

Where clusters come from

Sextant reads the same kubeconfig as kubectl:

1. the files listed in the KUBECONFIG environment variable (every file, merged the way kubectl merges them: the first file that defines a name wins), or, if it is not set, ~/.kube/config;
2. kubeconfig files you add from disk;
3. kubeconfig text you paste;
4. clusters you find in the cloud (Amazon EKS, Google GKE, Azure AKS), which Sextant keeps in a kubeconfig of its own (see Cloud clusters).
5. kubeconfig files you merge into Sextant's own merged.yaml (see Kubeconfig management).

Every context is one entry in the cluster list on the left of the window ("the cluster rail"). Two contexts that point to the same server are two clusters. Sextant does not change ~/.kube/config or any other kubeconfig of yours unless you turn on Allow Sextant to edit for that file, and then only after showing you a preview, with a backup before every write (see Kubeconfig management). Client certificates, tokens, basic authentication and exec plugins (cloud CLIs such as aws, gke-gcloud-auth-plugin or kubelogin) are supported.

If no kubeconfig is found, the welcome screen says "No clusters found" and lists the paths it checked.

A program started from a desktop launcher or the Dock may not see the KUBECONFIG you set in your shell profile. If your clusters are missing, either start Sextant from a terminal or add the file with Add cluster below.

Adding clusters

Press + (Add cluster) in the cluster rail, below your clusters:

• Add kubeconfig file opens a file chooser. Sextant remembers the path and reads the file every time; changes to the file are picked up when you press Refresh kubeconfig (the circular arrows below +).
• Paste kubeconfig takes the text of a kubeconfig. Sextant keeps a private copy in its data folder (see Settings).
• From cloud finds the clusters of your cloud account and adds the ones you tick. See the next section.

Sextant checks a kubeconfig before adding it, without connecting: that it is valid YAML and a kubeconfig, that every context's cluster and user exist, that server addresses are URLs, that certificates are valid and named files exist, that credentials have not expired, and that the login program of an exec plugin is installed (it is looked up, never run). If something is wrong, the Kubeconfig check dialog lists it per context, with Check connection to try a context once, and Add anyway to add the file regardless. A kubeconfig without problems is added at once. See Checking a kubeconfig when you add it.

To remove a source, open Settings → Clusters → Kubeconfig and press Remove next to it. Removing a file only forgets it (the file stays on disk); removing a pasted or merged source deletes Sextant's private copy. KUBECONFIG and ~/.kube/config cannot be removed here.

If one file cannot be read or parsed, the clusters from the other files still work, and the problem is shown next to the source in the cluster rail and in Settings. Fix the file and press Refresh kubeconfig.

Cloud clusters (EKS, GKE, AKS)

Add cluster has a From cloud tab. It uses the cloud command-line tools that are already installed and signed in on your computer: aws (Amazon EKS), gcloud (Google GKE) and az (Azure AKS). Sextant never signs in for you, never asks a tool to write to ~/.kube/config, and never sees a cloud password or token.

1. The tab lists each tool it finds with its version. A tool that is not installed shows Installation guide, a link to the vendor's instructions. Sextant looks the tools up in PATH every time, so one installed while Sextant is running is found when you open the tab again.

2. Choose what to search in:

   Cloud	Tool	You choose
   Amazon EKS	aws	A Profile (from aws configure list-profiles; the one in AWS_PROFILE, or default, is preselected) and one or more Regions (the profile's own region is preselected). With no profiles at all, Sextant uses the credentials from the environment (Credentials from the environment).
   Google GKE	gcloud	A Project (from gcloud projects list; the current one is preselected). All locations of the project are searched.
   Azure AKS	az	A Subscription (from az account list; the default one is preselected).

3. Press Find clusters. The list shows each cluster with its location, version and status; tick the ones you want.

4. Press Add N clusters. They appear in the cluster rail like any other cluster. Adding a cluster that is already there replaces its entry.

How the clusters are stored. For each cloud Sextant keeps one kubeconfig of its own in its data folder, kubeconfigs/cloud-aws.yaml, kubeconfigs/cloud-gcp.yaml or kubeconfigs/cloud-azure.yaml (readable only by you on Linux and macOS; see Settings for the folder). It holds the cluster's address and certificate authority, and no credentials: authentication goes through an exec plugin that asks the cloud tool for a short-lived token each time the cluster connects. The file is registered as a kubeconfig source, so the clusters stay after a restart. ~/.kube/config is not changed.

Cloud	Exec plugin in the kubeconfig
Amazon EKS	aws eks get-token --cluster-name <name> --region <region> [--profile <profile>]
Google GKE	gke-gcloud-auth-plugin. Install it with gcloud components install gke-gcloud-auth-plugin if the tab says it is missing.
Azure AKS	kubelogin get-token --login azurecli …. Install it with az aks install-cli if the tab says it is missing.

A missing plugin does not stop you from adding the clusters, but connecting needs it.

AKS needs Microsoft Entra ID. Sextant signs in to AKS with the token of your az login, so only clusters with Entra ID (Azure AD) integration work. Clusters that only use local accounts are not supported.

When something is wrong, the tab (and the "Cannot connect" screen of a cloud cluster) explains it and shows the command to fix it, with Copy command and Open terminal. Open terminal opens a local terminal tab in the dock with the command already typed; press Enter to run it. Sextant does not run it for you. The commands are aws sso login --profile <profile> (or aws configure --profile <profile> for a profile with access keys), gcloud auth login and az login. After signing in, press Find clusters or Reconnect again. See Troubleshooting.

To remove cloud clusters, open Settings → Kubeconfig and press Remove next to the source marked "cloud". Its clusters disappear from the list and Sextant's cloud-<provider>.yaml is deleted. Your cloud tools and ~/.kube/config are not touched.

Connecting

Click a cluster to open it; Sextant connects. The dot on its icon shows the state: disconnected, connecting, connected or connection failed. Several clusters can be connected at the same time.

Right-click a cluster (or use its menu) for Open, Connect / Reconnect, Disconnect, Settings and Change icon…, the kubeconfig changes Rename context…, Set default namespace…, Duplicate with namespace… and Delete context… (see Kubeconfig management), and, for a connected cluster that has no Flux or Argo CD, Install Flux… and Install Argo CD… (see Installing Flux and Argo CD). Disconnecting closes everything that cluster had open: watches, logs, shells and port forwards.

If the connection fails, the window says "Cannot connect to " with the reason and a Reconnect button. A slow cluster shows how many seconds the attempt has taken. See Troubleshooting for common causes.

A cluster behind a proxy is reached through the proxy-url of its kubeconfig entry, as with kubectl: http://, https:// or socks5:// (the SOCKS proxy resolves host names; write socks5://, not socks5h://). See Troubleshooting for an example.

The window

The layout will look familiar if you have used Lens.

Area	What it is
Cluster rail (far left)	The workspace button at the top (see [[Views and workspaces
Sections (left)	Your favourites and saved views of this cluster at the top, if you have any, then the tree of kinds and pages of the selected cluster: Cluster, Nodes, Workloads, Config, Network, Storage, Namespaces, Events, Helm, Access Control, Flux, Argo CD and Custom Resources. Flux and Argo CD appear only in clusters where they are installed.
Main view	The table of the selected kind, or a page such as the cluster overview.
Details panel (right)	Opens when you click an object.
Dock (bottom)	Tabs for logs, shells, the local terminal and YAML editors.

A freshly connected cluster opens the Cluster overview: nodes ready, pods and workloads by state, current CPU and memory use, last-hour charts and warnings. Sidebar and dock sizes can be dragged. In a narrow window (down to 360 px) the cluster rail and the sections move into a menu.

Sextant also puts an icon in the system tray (the menu bar on macOS) with Show / Hide, About Sextant… and Quit. By default, closing the window quits Sextant; an option in Settings → Window keeps it running in the tray instead. See Settings.

Next: Using Sextant.