Kubernetes Provisioner
The Kubernetes Provisioner lets you create a ready-to-use Kubernetes cluster from Cockpit in a few guided steps. Cockpit builds the virtual machines, installs a lightweight, fully compatible Kubernetes distribution (k3s), wires up networking and storage, and hands you a cluster you can connect to with the standard kubectl tool.
You do not need to prepare servers, run installers, or copy join commands by hand. You choose how big the cluster should be and where it should run, and Cockpit does the rest in the background while you keep working.
Who this guide is for
This guide is for people who want to run a Kubernetes cluster — application teams, platform operators, and administrators. It focuses on what you do in the Cockpit interface and how to use the cluster afterwards.
Before you start
Two things must be in place before your first cluster. If your administrator has already set up the environment, you can skip straight to Create a cluster.
- A cluster template. Cockpit clones every node from a prepared Ubuntu template image. This is usually provided for you and appears automatically as an option in the wizard.
- A suitable network. Every node in a cluster must be able to reach the others and reach the internet (to download Kubernetes components on first boot). See Choosing a network for how to pick the right one.
Create a cluster
- In the left-hand inventory tree, right-click your Cluster.
- Choose Kubernetes → New Cluster.
- The Kubernetes Provisioning Wizard opens with five short steps.
When you finish the wizard, Cockpit starts building the cluster in the background. You can close the wizard and watch progress in the Tasks panel. The cluster appears in the inventory and moves through provisioning to active when it is ready to use.
Step 1 — Identity & Version
| Field | What it does |
|---|---|
| Cluster Name | A friendly name for the cluster. Used in the inventory and in the downloaded config file. |
| Description | Optional notes for your own reference. |
| Network | The virtual network the nodes connect to. See Choosing a network. |
| Kubernetes Version | The k3s version to install. The list is kept current for you; pick the newest unless you have a reason not to. |
| Network Plugin (CNI) | How pods talk to each other. See Network plugins. Leave on Flannel if unsure. |
Step 2 — Control Plane
The control plane is the "brain" of the cluster. Choose how resilient it should be:
- Single (1 node) — Simplest and lightest. Good for development and testing. If that one node is lost, the cluster is unavailable until it recovers.
- High Availability (3 nodes) — Recommended for production. The cluster keeps running even if one control-plane node fails.
You also set the CPU, Memory, Datastore, and Disk size for each control-plane node, and a Placement choice:
- Auto-Distribute (recommended) — Cockpit spreads the three HA nodes across three different physical hosts automatically, so a single host outage cannot take down the whole control plane.
- Manual — You pick exactly which host each node runs on.
Step 3 — Worker Nodes
Workers run your actual applications. Set how many you want to start with and the CPU, Memory, Datastore, and Disk size for each. You can change the worker count at any time later — see Scale a cluster.
Placement works the same as for the control plane: Auto-Distribute balances workers across hosts, or use Manual to pin workers to specific hosts (useful when certain hosts have special hardware such as GPUs).
Step 4 — Access & Storage
- SSH Public Key — Optional. Paste a public key here if you want direct SSH access to the node VMs for troubleshooting. It is not required to use the cluster.
- Storage Tiers (CSI) — Choose how applications get persistent storage. You can enable more than one. See Storage for your applications.
Step 5 — Review & Create
Review the summary — the size of the cluster, the resources it will use, and which hosts the nodes will land on. Click Provision to start. The wizard closes and a task begins.
Choosing a network
The network you pick in Step 1 has the biggest impact on whether your cluster forms successfully, so it is worth a moment's thought.
Every node must sit on the same reachable network, get an IP address automatically (DHCP), and reach the internet during setup. Two common situations:
- A shared/routed network that spans your hosts — Nodes can be spread across multiple physical hosts and still talk to each other. This is the right choice for a High-Availability cluster that should survive a host failure.
- A host-local NAT network — This kind of network lives on a single host. When you choose one, Cockpit automatically keeps all nodes of the cluster on that one host so they can communicate. This is perfectly fine for development or a self-contained cluster, but it means the cluster shares the fate of that host.
WARNING
Avoid isolated networks that only connect VMs on the same host with no shared addressing across hosts, and networks without internet access. Nodes on such networks cannot find each other or download Kubernetes components, and the cluster will not finish provisioning.
If you are not sure which network to use, ask your administrator which one is intended for Kubernetes.
Network plugins (CNI)
The network plugin controls how pods communicate and whether you can enforce network security policies. You choose it once, in Step 1.
| Plugin | Best for | Notes |
|---|---|---|
| Flannel (default) | Most clusters, development, simple setups | Lightweight and reliable. No network policies. |
| Calico | Production with tenant isolation | Adds Kubernetes NetworkPolicy support for controlling pod-to-pod traffic. |
| Cilium | High-performance, advanced networking | eBPF-based, with rich L3–L7 policies and traffic visibility. |
If you have no specific requirement, Flannel is a safe default.
Storage for your applications
Applications that need to keep data (databases, file uploads, and so on) request storage through a storage tier. Enable the tiers you need in Step 4; you can turn on more than one and choose per-application which to use.
| Tier | What it gives you | When to use it |
|---|---|---|
| Local Path (on by default) | Fast storage on the node where the pod runs | Simple, high-speed storage. Data stays on one node, so it is not available if the pod moves to another node. |
| Shared (NFS) | Storage many pods can share at once, available across nodes | When pods need to share files, or keep their data when they move between nodes. |
| Replicated (Longhorn) | Highly available block storage, copied across nodes | Stateful workloads like databases that must survive a node failure. |
For Shared (NFS), you can either point to an NFS datastore already registered in Cockpit or enter an external NFS server address. Cockpit checks it can reach the server before it starts, so a typo is caught early rather than midway through provisioning.
Connect to your cluster
Once the cluster status is active, you can connect with kubectl, the standard Kubernetes command-line tool.
Open the cluster's detail page and click Download Kubeconfig. Cockpit gives you a ready-to-use file with the correct server address already filled in.
Save it and point
kubectlat it:bashmkdir -p ~/.kube mv ~/Downloads/kubeconfig-my-cluster.yaml ~/.kube/config-my-cluster chmod 600 ~/.kube/config-my-cluster export KUBECONFIG=~/.kube/config-my-clusterCheck it works:
bashkubectl get nodesYou should see your control-plane and worker nodes listed as Ready.
TIP
To avoid setting KUBECONFIG every time, add the export line to your shell profile (~/.bashrc or ~/.zshrc).
Scale a cluster
You can grow or shrink the number of worker nodes at any time, without rebuilding the cluster.
- Open the cluster and find the worker node pool.
- Set the new desired worker count and confirm.
Scaling up adds new worker VMs and joins them to the cluster automatically. When the new nodes show as Ready, they start accepting workloads.
Scaling down is done gracefully: before a node is removed, Cockpit drains it — moving its running workloads to the remaining nodes — so applications keep running. Only then is the VM removed and its resources freed.
If a node fails to be added
If a new worker cannot be created (for example, the chosen host is temporarily out of capacity), Cockpit cleans up the incomplete node automatically and adjusts the pool to the count it actually reached. Simply run scale-up again to retry — you will not be left with half-finished nodes.
Upgrade a cluster
Cockpit performs a rolling upgrade, moving the cluster to a newer Kubernetes version one node at a time so your applications stay available.
- Open the cluster and choose Upgrade.
- Pick the target version from the list.
- Confirm. Cockpit upgrades the control plane first, then the workers, one node at a time.
During the upgrade each node is drained, updated, and returned to service before the next node begins. You can follow the progress in the Tasks panel.
Monitor cluster health
After a cluster goes active, Cockpit keeps an eye on it and shows a health status on the cluster page:
- Healthy — All nodes are present and Ready.
- Degraded — One or more nodes are not Ready (for example, a node was stopped or lost network). The cluster is still running but has reduced capacity or resilience.
Health updates on its own as nodes recover or fail, so you can tell at a glance whether attention is needed.
Troubleshooting
The cluster is stuck in "provisioning" and never becomes active. The most common cause is the network. Confirm the network you chose gives every node an IP address automatically and has internet access. If nodes are spread across hosts, make sure the network actually spans those hosts. See Choosing a network.
A node shows as "NotReady" or the cluster is "Degraded". Check that the node's VM is running (it may have been stopped, or its host may be down). Once the VM is back and reconnected to the network, the node rejoins and the health status returns to Healthy on its own.
kubectl cannot connect after downloading the kubeconfig. Make sure KUBECONFIG points to the downloaded file and that your machine can reach the control-plane node's address on the network. Re-download the kubeconfig if the cluster's address has changed.
Applications lost their data after a pod moved to another node. This happens with the Local Path storage tier, which keeps data on a single node. For data that must follow the application, use the Shared (NFS) or Replicated (Longhorn) tier instead. See Storage for your applications.
Related topics
- Distributed Resource Scheduler (DRS) & High Availability — how Cockpit places and balances node VMs across hosts.
- Virtual Networking — networks your cluster nodes connect to.
- Storage & Datastores — shared datastores that let clusters run across hosts.