This article will show you how to install K3s onto a new Ubuntu 20.04 LTS machine for use with Coder.
K3s is a lightweight Kubernetes distribution that works well for single-node or multi-node clusters. This guide covers the installation of K3s onto a new Ubuntu 20.04 LTS machine. If you want to install Coder on a local machine or an existing host, a kind cluster or k3d cluster may be a better choice, as it leverages Docker to set up/tear down clusters with little hassle.
This installation method is not officially supported or tested by Coder. If you have questions or run into issues, feel free to reach out using our community Slack channel.
We do not recommend using K3s for production deployments of Coder.
Before proceeding, please make sure that:
You have an Ubuntu 20.04 machine: This can be a bare metal or a virtual machine.
Ensure that the machine's specs satisfy Coder's resource requirements, since your experience with Coder is dependent on your system specs.
You have the following software installed on your machine:
Your network policy or firewall accepts incoming traffic on:
- Port 22 (SSH)
- Port 80 (HTTP)
- Port 443 (HTTPS)
- Port 5349 (TURNS)
- Optional: Port 443 (Kubernetes API)
If you've enabled Networking v2 after installing Coder (you can do so by going to Manage > Admin > Infrastructure), this step to SSH into workspaces isn't necessary, since TURNS is used instead.
To allow SSH into workspaces, you must change the host's
default SSH port to free up port
22. You may also need to modify your firewall
to accept incoming traffic from the alternative port (e.g., if you rename port
5522, then your firewall must accept traffic from
If you don't know how to change the SSH port in Linux, please review this guide from Linuxize
The following steps are based on Calico's quickstart guide for setting up K3s. However, you will disable K3s' default network policies and Traefik in favor of Calico and nginx-ingress.
Create a single-node K3s cluster:
curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" INSTALL_K3S_EXEC="--flannel-backend=none --cluster-cidr=192.168.0.0/16 --disable-network-policy --disable=traefik" sh -
Per the Calico docs:
192.168.0.0/16is already in use within your network, you must select a different pod network CIDR by replacing
192.168.0.0/16in the above command.
K3s installer generates kubeconfig file in
/etcwith limited permissions; by using the
K3S_KUBECONFIG_MODEenvironment, you are assigning the necessary permissions to the file and making it accessible for other users.
Install the Calico operator and CRDs (Calico implements Kubernetes pod networking and policy enforcement):
kubectl create -f https://docs.projectcalico.org/manifests/tigera-operator.yaml kubectl create -f https://docs.projectcalico.org/manifests/custom-resources.yaml
Confirm that all of the pods are running:
watch kubectl get pods --all-namespaces
Modify Calico to enable IP forwarding, which is needed for container networking.
kubectl edit cm cni-config -n calico-system
Occasionally, Helm will not recognize the K3s cluster (see k3s-io/k3s#1126 for more information).
If this happens, but you want to interface with the cluster from your local
After copying this file from the K3s node to your local workstation:
- Ensure that you replace
127.0.0.1with the host's public IP address in the copied file
- Ensure that your firewall permits traffic through port
# on the host machine:
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config