Kubernetes and k3s

What the Kubernetes tab does

The Kubernetes tab shows the cluster running on a server and lets you work with it without typing kubectl: see what needs attention, browse workloads, pods, services, nodes and namespaces, read pod logs, restart, scale, roll back, delete pods and apply manifests. Every action runs kubectl on the server over SSH with the cluster's kubeconfig. Nothing is installed inside the cluster to make the tab work.

When the tab appears

Server Compass looks for k3s, k0s, MicroK8s and kubeadm over SSH. It checks for their binaries and services, and for a kubeconfig in the usual places, including /etc/rancher/k3s/k3s.yaml, /var/lib/k0s/pki/admin.conf, /etc/kubernetes/admin.conf, the MicroK8s client config and ~/.kube/config. When a cluster answers, the Kubernetes tab appears next to Apps.

On a server without a cluster the tab stays hidden. Open Settings on the server: the Kubernetes card says Not installed, and Open Kubernetes tab takes you to the two ways in, Install k3s… and Connect an existing cluster. When a cluster is running, the same card shows its distribution and version.

Install k3s

Install k3s… (marked Recommended) installs a single-node Kubernetes from get.k3s.io over SSH. This server becomes both the control plane and the worker.

The dialog runs nine preflight checks before anything is installed:

• Root access: connected as root, or a user with passwordless sudo
• Existing cluster: no k3s, k0s, MicroK8s or kubeadm already installed
• Operating system: systemd, curl, and an x86_64, arm64 or armv7l CPU
• CPU and memory: under about 1.8 GB of RAM blocks the install; a single vCPU is only a warning
• Disk space: under 2 GB free on /var/lib blocks the install; under 5 GB is a warning
• Ports: 6443 and 10250 must be free
• Download: https://get.k3s.io must answer
• Firewall: what the install will add to UFW, if UFW is active
• Ingress on 80/443: whether a reverse proxy already owns the web ports

Two options follow the checks:

• Bundled Traefik ingress on ports 80/443 is off by default. It is Locked off when Server Compass manages domains with its own Traefik, when another proxy is installed, or when anything listens on 80/443, so k3s installs with --disable traefik and your existing domains keep working.
• Allow remote kubectl (open 6443/tcp in UFW) appears only when UFW is active and is off by default. Server Compass and the kubectl shell reach the API over SSH, so you only need it to run kubectl from another machine.

Install k3s runs the standard installer (curl -sfL https://get.k3s.io | sh -) as root. It installs whatever get.k3s.io currently serves; the version is not pinned. With UFW active, it also adds rules for the pod network (10.42.0.0/16) and the service network (10.43.0.0/16) so pods can reach cluster DNS. When it finishes, Open the cluster opens the tab. Use Re-check to run the preflight again after you fix something.

Connect an existing cluster

Connect an existing cluster → Choose kubeconfig… opens Use an existing kubeconfig. Enter the Path on the server, for example /home/deploy/.kube/config, or pick one of the Common locations. Check on server reads the file, finds a kubectl client and asks the cluster for its version. You will see Cluster answered or This kubeconfig cannot be used. Use this kubeconfig saves the path once the check passes.

Reading the cluster

The header shows the distribution and version, the node count, the kubeconfig in use and when it was last read, with Open kubectl shell and Apply manifest on the right.

Needs attention appears whenever something is wrong. It lists nodes that are not ready, workloads that are rolling out or short of replicas, and pods that are failing or pending. Each row has a short reason (for example CrashLoopBackOff, ImagePullBackOff, OOMKilled, or a pod pending on insufficient memory) and a link to the node or pods behind it.

Below it are five views: Workloads, Pods, Services & Ingress, Nodes and Namespaces. Use All namespaces to pick a namespace and the filter box to search by name. On k3s, system add-ons such as metrics-server, local-path-provisioner and helm-install jobs are hidden. The footer says how many, and Show add-ons brings them back.

Pod logs

View logs on a pod opens its logs read-only. Choose Lines (100, 200, 500 or 2000) and tick Previous instance to read the container that crashed before the current one. Find in logs highlights matches and Only these hides the other lines. Wrap wraps long lines, refresh reads the logs again, and Download saves them as a .log file. The footer shows the kubectl logs command being run.

Restart, scale, roll back and delete

Each workload row has three actions:

• Restart (rollout restart) replaces the workload's pods with new ones, one at a time, using the same spec. The tab follows the rollout for you.
• Scale sets how many pods a Deployment or StatefulSet runs, from 0 to 1000. The dialog shows the exact kubectl scale command under Runs on the server. DaemonSets run one pod per node and cannot be scaled.
• Roll back to a previous revision lists each revision with current and previous badges. Roll back to revision {n} applies your choice.

Delete pod removes a pod, and offers Force delete for one stuck terminating. You only have to type the pod name when no controller will recreate it.

Apply a manifest

Apply manifest walks three steps: Write, Dry run, Apply. Paste YAML or use Load file… (up to 1 MiB), and optionally choose a Namespace; by default the manifest decides. Dry run runs a server-side dry run (kubectl apply --dry-run=server). Apply stays locked until a dry run of that exact text has passed, and editing the manifest resets it.

kubectl shell

Open kubectl shell opens the Terminal tab with KUBECONFIG exported for the detected cluster (on k3s, /etc/rancher/k3s/k3s.yaml) and runs kubectl get nodes, so you can continue by hand.

Uninstall k3s

On a server where Server Compass can see the k3s control plane, Uninstall k3s… runs k3s's own uninstall script. It deletes every pod, workload, volume claim and the cluster state under /var/lib/rancher/k3s, and removes the UFW rules the install added. Data on hostPath volumes outside that directory is kept. You confirm by typing the server name.

AI agents, Unmanaged Apps and locked servers

Through AI Access, agents get ten Kubernetes tools. On the Read tier: k8s_overview, k8s_list, k8s_logs, k8s_rollout_status and k8s_rollout_history. On Operate: k8s_restart_workload, k8s_scale_workload, k8s_delete_pod and k8s_rollout_undo. On Deploy: k8s_apply_manifest. Installing or uninstalling k3s and choosing a kubeconfig are only possible in the app.

In Apps, ports owned by the cluster no longer appear as unmanaged processes. They fold into one Kubernetes workloads row with Open Kubernetes tab, and ports such as 6443 and 10250 are recognized as Kubernetes services.

A locked server refuses changes. Restart, scale, roll back, delete and apply are blocked in the tab and over MCP until you unlock it in Server Settings.