coder · bpmct · Jul 2, 2021 · Jun 22, 2021 · Jun 22, 2021 · Jun 22, 2021
diff --git a/manifest.json b/manifest.json
@@ -125,6 +125,9 @@
             {
               "path": "./setup/kubernetes/local-preview.md"
             },
+            {
+              "path": "./setup/kubernetes/k3s.md"
+            },
             {
               "path": "./setup/kubernetes/aws.md"
             },

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
@@ -0,0 +1,141 @@
+---
+title: "K3s"
+description: Set up K3s on an Ubuntu machine to deploy Coder.
+---
+
+This article will show you how to install K3s onto a new Ubuntu 20.04 LTS
+machine for use with Coder.
+
+[K3s](https://k3s.io/) 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](./kind.md) or [k3d
+cluster](https://k3d.io/) 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](https://cdr.co/join-community).
+>
+> **We do not recommend using K3s for production deployments of Coder.**
+
+## Prerequisites
+
+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](../requirements.md), since your experience with Coder is
+   dependent on your system specs.
+
+- You have the following software installed on your machine:
+
+  - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+  - [helm](https://helm.sh/docs/intro/install/)
+
+- Your network policy or firewall accepts incoming traffic on:
+
+  - Port 22 (SSH)
+  - Port 80 (HTTP)
+  - Port 443 (HTTPS)
+  - Port 5349 (TURNS)
+  - **Optional**: Port 8443 (Kubernetes API)
+
+## Step 1: Change the default SSH port
+
+> 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](../../workspaces/ssh), 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
+`22` to `5522`, then your firewall must accept traffic from `5522`).
+
+> If you don't know how to change the SSH port in Linux, please review this
+> [guide from
+> Linuxize](https://linuxize.com/post/how-to-change-ssh-port-in-linux/)
+
+## Step 2: Install K3s with Calico
+
+The following steps are based on [Calico's quickstart
+guide](https://docs.projectcalico.org/getting-started/kubernetes/k3s/quickstart)
+for setting up K3s. However, you will disable K3s' default network policies and
+Traefik in favor of Calico and nginx-ingress.
+
+1. Create a single-node K3s cluster:
+
+   ```console
+   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](https://docs.projectcalico.org/getting-started/kubernetes/k3s/quickstart):
+   >
+   > If `192.168.0.0/16` is already in use within your network, you must select
+   > a different pod network CIDR by replacing `192.168.0.0/16` in the above
+   > command.
+   >
+   > K3s installer generates kubeconfig file in `/etc` with limited permissions;
+   > by using the `K3S_KUBECONFIG_MODE` environment, you are assigning the
+   > necessary permissions to the file and making it accessible for other users.
+
+1. Install the Calico operator and CRDs (Calico implements Kubernetes pod
+   networking and policy enforcement):
+
+   ```console
+   kubectl create -f https://docs projectcalico.org/manifests tigera-operator.yaml
+
+   kubectl create -f https://docs.projectcalico.org/manifests/custom-resources.yaml
+   ```
+
+1. Confirm that all of the pods are running:
+
+   ```console
+   watch kubectl get pods --all-namespaces
+   ```
+
+## Step 3: Allow IP Forwarding
+
+Modify Calico to enable IP forwarding, which is needed for container networking.
+
+```console
+vim /etc/cni/net.d/10-canal.conflist
+
+kubectl edit cm cni-config -n calico-system
+```
+
+Under `container_settings`, set `allow_ip_forwarding` to `true`:
+
+```json
+"container_settings": {
+   "allow_ip_forwarding": true
+}
+```
+
+## Step 4: Copy over the kubeconfig
+
+Occasionally, Helm will not recognize the K3s cluster (see
+k3s-io/[k3s#1126](https://github.com/k3s-io/k3s/issues/1126) for more
+information).
+
+If this happens, but you want to interface with the cluster from your local
+machine, copy `/etc/rancher/k3s/k3s.yaml` to `~/.kube/config`.
+
+After copying this file from the K3s node to your local workstation:
+
+- Ensure that you replace `localhost` or `127.0.0.1` with the host's public IP
+  address in the copied file
+- Ensure that your firewall permits traffic through port `8443`
+
+```console
+# on the host machine:
+cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
+```
+
+## Next steps
+
+At this point, you're ready to proceed to [installing
+Coder](../installation.md).
-Original file line number
+Diff line change
@@ Expand Up / @@ -125,6 +125,9 @@ @@
                 {
                   "path": "./setup/kubernetes/local-preview.md"
                 },
+                {
+                  "path": "./setup/kubernetes/k3s.md"
+                },
                 {
                   "path": "./setup/kubernetes/aws.md"
                 },
@@ Expand Down @@