Not every workload belongs in a public cloud. Data rules, latency or plain cost keep plenty of apps on servers you own. k3s is a lightweight, certified Kubernetes distribution that runs well on a single machine or a small group of them. This guide takes a fresh Linux server to a cluster you can deploy to from Shipfast.
What you need
- A Linux server or VM with at least 2 CPU cores and 4 GB of memory for a small cluster.
- Outbound HTTPS from the server to your Shipfast workspace. No inbound ports are needed.
- A Shipfast workspace and a user with permission to add clusters.
1. Install k3s
On the server, run the official k3s installer:
$ curl -sfL https://get.k3s.io | sh - $ sudo k3s kubectl get nodes NAME STATUS ROLES AGE VERSION onprem-01 Ready control-plane,master 40s v1.30.4+k3s1
k3s writes its kubeconfig to /etc/rancher/k3s/k3s.yaml. To add more servers as agents, follow the k3s documentation for joining nodes.
2. Add the cluster in Shipfast
In Shipfast, open Clusters, choose to connect an existing cluster, and give it a name. Shipfast shows an install command for that cluster. It contains a one-time token that is valid for 15 minutes:
$ sudo k3s kubectl apply -f https://<your-workspace>/k8s/apply/<token>
Run it on the server. It installs a small controller and the Shipfast agent in their own namespace, with only the permissions they need.
3. Wait for the first sync
The agent connects out to your workspace over HTTPS and a WebSocket, and the cluster's status changes to configured after its first sync, usually within a minute or two. From then on Shipfast never connects in: every connection starts from your server. That is why this works behind a firewall or NAT without opening ports or setting up a VPN.
4. Deploy something
Create an application from a template and choose your new cluster. Once the application is approved, Shipfast creates its namespace and the agent applies it. Logs, events, metrics and a browser terminal are available straight away.
Troubleshooting
- The token expired. Tokens last 15 minutes. Generate a new install command in Shipfast and run it again.
- The cluster never syncs. Check that the server can reach your workspace address over HTTPS, including through any proxy.
- Pods stay pending. A single small server fills up quickly. Check node capacity in Shipfast and add a node or reduce requests.
Read more about creating and connecting clusters, or see the docs.