Clusters
K3s cluster list and detail pages with nodes, endpoints, and live status
What you see
URL: /clusters (list), /clusters/[id] (detail)
The clusters page shows all K3s clusters managed by PodWarden. You can switch between two view modes using the toggle in the top-right corner:
- List view -- A table with sortable columns.
- Tile view -- Cards showing each cluster with key metrics at a glance.
Fields / columns
| Column | Description |
|---|---|
| Name | Cluster display name |
| Environment | Label such as production, staging, or development |
| Nodes | Number of nodes in the cluster (live count from the K3s API) |
| Endpoints | Number of service endpoints exposed by the cluster (live) |
| Workload pods | Number of running pods across all workload namespaces (live) |
| Kubeconfig | Indicates whether a kubeconfig is stored for this cluster |
Live columns are refreshed each time the page loads or when you click Refresh.
Available actions
| Action | Where | What it does |
|---|---|---|
| Refresh | List page toolbar | Re-fetches live data (nodes, endpoints, pods) from all clusters |
| Toggle view | List page toolbar | Switches between Tile and List view modes |
| Create | List page toolbar | Opens the cluster creation form |
| Delete | List page / Detail page | Removes the cluster record. A confirmation modal shows all affected resources (assignments, ingress rules, deployments) that will be orphaned |
| View detail | Click a cluster row or tile | Opens the cluster detail page |
| CI snippet | Detail page | Generates a .gitlab-ci.yml snippet with cluster-specific values for build and deploy stages |
Delete confirmation
Before deleting a cluster, PodWarden shows a confirmation dialog listing all resources that depend on it -- deployments, ingress rules, and deployments. This helps you understand the impact before proceeding.
Cluster detail page
URL: /clusters/[id]
The detail page shows comprehensive information about a single cluster:
Cluster info
- Name and Environment label
- API server URL -- The K3s API endpoint (auto-detected or manually overridden)
- Effective API server URL -- The URL PodWarden actually uses for kubectl. If you set an override, it shows
(override)next to the URL. - Kubeconfig -- Download or view the stored kubeconfig
- Created at -- When the cluster was registered
- Network types -- Available connectivity (
public,mesh,lan)
API Server URL Override
PodWarden auto-detects the best API server URL based on the control plane host's internal IP, Tailscale IP, or SSH address. If the auto-detected URL doesn't work for your setup (e.g., you use a load balancer or custom DNS), you can set a manual override:
- Click the API server URL to edit it
- Enter your custom URL (e.g.,
https://my-lb.example.com:6443) - Click Reset to Auto to clear the override
Nodes
A table of all nodes in the cluster:
| Column | Description |
|---|---|
| Name | Kubernetes node name |
| Role | control-plane, worker, or both |
| Status | Ready, NotReady, or Unknown |
| IP | Internal IP address |
| OS | Operating system and kernel version |
| Resources | CPU and memory capacity |
Longhorn Storage
If Longhorn distributed storage is installed, a Longhorn Storage card shows the current status:
| Status | Badge | Meaning |
|---|---|---|
| ready | Green | All pods running, nodes schedulable — storage is fully operational |
| starting | Amber | Longhorn is still initializing (pods not all ready yet) |
| degraded | Red | All pods running but storage nodes not schedulable (usually disk space) |
The card shows:
- Pod count -- e.g., "19/19 ready"
- Node schedulability -- per-node status
- Run Speed Test button -- runs a 100 MB write/read benchmark using
ddthrough a temporary PVC, reports throughput in MB/s
If Longhorn is not installed, this card does not appear.
Storage classes
Lists all Kubernetes StorageClasses available in the cluster. If no storage classes exist, PodWarden shows a recommendation to install Longhorn or OpenEBS.
Endpoints
A list of service endpoints exposed by the cluster, showing the service name, namespace, port, and protocol.
Node management
The cluster detail page provides node-level operations for maintenance and workload migration:
| Action | Description |
|---|---|
| Cordon | Marks a node as unschedulable — no new pods will be placed on it, but existing pods continue running |
| Uncordon | Marks a cordoned node as schedulable again |
| Drain | Evicts all pods from a node. Automatically cordons the node first. Useful before hardware maintenance or node removal |
| Delete node | Removes a node from the K3s cluster |
Drain options
| Option | Default | Description |
|---|---|---|
force | false | Force drain even if pods aren't managed by a controller |
ignore_daemonsets | true | Skip DaemonSet pods (they're expected on every node) |
delete_emptydir_data | true | Delete pods with emptyDir volumes |
timeout_seconds | 120 | How long to wait before giving up |
Workload migration
To migrate a deployment from one node to another:
- Cordon the source node (prevents new scheduling)
- Drain the node (evicts all pods)
- Update the deployment's placement to the target node
- Redeploy the workload
With Longhorn distributed storage, persistent volumes are replicated across nodes — no manual data migration is needed. PodWarden runs a pre-flight check to verify the target node is in the volume's allowed node affinity list before deploying.
After deployment, PodWarden performs a post-deploy health check (polls pod readiness for up to 90 seconds) and transitions the deployment to error if pods don't become healthy.
Status badges
| Badge | Meaning |
|---|---|
| connected | PodWarden can reach the K3s API |
| unreachable | API server is not responding |
| no kubeconfig | No kubeconfig stored -- cluster cannot be managed |
Related docs
- Hosts -- Servers that form cluster nodes
- Cloud Provider Support -- Deploying on AWS, GCP, Azure, and other cloud platforms
- Deployments -- Deploy workloads to clusters
- Networking guide -- Network types and connectivity requirements