Skip to content

Self-hosted Kubernetes cluster with K3S

If you want to keep infrastructure under your control and avoid managed Kubernetes costs, you can connect your own server to Wodby as a K3S cluster.

Why use K3S instead of Managed Kubernetes?

Learn more about the benefits of K3S in our blog

K3S is a certified lightweight distribution of Kubernetes.

Requirements

  • A server with at least 2 GB of RAM and 2 CPUs
  • A server with dedicated, non-shared CPU
  • Supported OS: Ubuntu/Debian, Fedora/CentOS, OpenSUSE
  • Currently only amd64 machines are supported
  • At least 20 GB of disk space

For more details, see the official K3S installation requirements.

Connect server flow

  1. Open Kubernetes > Connect server in the dashboard.
  2. Select the cluster Owner. Choose Organization <organization> for an organization-owned cluster or Project <project> for a project-owned cluster.
  3. Enter the cluster name and title.
  4. Decide whether to leave Enable monitoring turned on. It is enabled by default.
  5. Create the cluster.

New K3S clusters are created in the Awaiting state. This means Wodby is waiting for you to run the generated installation command on your server.

Installation command

After creation, Wodby redirects you to the cluster page and shows a one-time installation command.

  • Run the command on the target server as root or with sudo
  • The download token inside that command expires after 15 minutes
  • If it expires, reload the cluster page to generate a fresh command

The generated script performs the current bootstrap flow for you. It:

  • installs the rollback command at /usr/local/bin/wodby-k3s-uninstall
  • disables swap
  • installs required NFS client packages
  • installs firewall rules that restrict public access to the K3S API endpoint
  • installs K3S
  • installs Helm
  • installs Cilium for pod networking and NetworkPolicy enforcement
  • prepares local kubeconfig on the server
  • installs Wodby's proxy client so the cluster can securely connect back to Wodby
  • sends the final initialization request to Wodby

Uninstall after a failed installation

If the installation script fails partway through, run the rollback command on the same server before retrying:

sudo /usr/local/bin/wodby-k3s-uninstall

The rollback command is installed at the beginning of the bootstrap script. It is safe to run after a partial installation and continues cleanup even when some components were never installed.

The command removes:

  • Wodby k3s API firewall rules and systemd unit
  • the Wodby proxy client Helm release, when Kubernetes is reachable
  • the Cilium Helm release, when Kubernetes is reachable
  • Cilium host networking artifacts and stale kube-router network policy rules
  • K3S, using the official /usr/local/bin/k3s-uninstall.sh script when available
  • root kubeconfig generated by the bootstrap script
  • Helm, only when Helm was installed by the Wodby K3S bootstrap script

The command does not remove NFS client packages and does not re-enable swap. After it completes, reload the cluster page to generate a fresh installation command and run it again.

What happens next

After the script completes successfully, Wodby initializes the cluster and deploys the required infrastructure components.

  • Envoy Gateway is deployed for public HTTP, HTTPS, TCP, and UDP entrypoints
  • Cilium enforces app instance network policies
  • Monitoring components are deployed if you left monitoring enabled
  • The cluster moves out of Awaiting and eventually becomes ready for app deployments

Once the cluster is ready, create new apps and choose that cluster from My clusters.

Infrastructure upgrades

New K3S clusters use the current Wodby cluster infrastructure version. Existing K3S clusters can be marked as outdated when Wodby releases a K3S-specific infrastructure upgrade.

The current K3S-specific upgrade path is described in Kubernetes cluster infrastructure. It replaces the default K3S flannel/kube-router networking setup with Cilium.

The upgrade can briefly interrupt pod networking while K3S restarts and Cilium takes over. Run it during a maintenance window for production workloads.

Single server model

K3S clusters connected to Wodby are single-server clusters.

Wodby does not support joining additional K3S nodes to the cluster. Multi-node self-hosted Kubernetes requires extra decisions around networking, storage, and node operations that are outside the supported K3S flow.

In the dashboard, K3S clusters are shown as one-node clusters. They do not have the Control page and cannot be scaled from Wodby.

Envoy Gateway still uses a Kubernetes LoadBalancer service on K3S. K3S handles that service through its built-in ServiceLB controller, so Wodby does not create a cloud provider load balancer for K3S.

Troubleshooting

  • If the command has expired, reload the cluster page and use the new command.
  • If the cluster stays in Awaiting, the bootstrap script likely never completed the final initialization step.
  • If the script fails, fix the server issue, run sudo /usr/local/bin/wodby-k3s-uninstall, and then rerun a fresh command from the cluster page.
  • Make sure the server can reach the public internet and the Wodby API endpoints during installation.