From de1100a4f4d416083b96ad72e88834f0b73fbfbd Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Tue, 22 Jun 2021 09:35:51 -0400
Subject: [PATCH 01/14] add k3s setup

---
 manifest.json           |  3 ++
 setup/kubernetes/k3s.md | 97 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 setup/kubernetes/k3s.md

diff --git a/manifest.json b/manifest.json
index 97bf42005..dd33cbc44 100644
--- 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
new file mode 100644
index 000000000..dbd6d461e
--- /dev/null
+++ b/setup/kubernetes/k3s.md
@@ -0,0 +1,97 @@
+---
+title: "k3s"
+description: Set up a Coder deployment with a Ubuntu + k3s
+---
+
+k3s is a lightweight Kubernetes distribution that works great with single-node
+or multi-node clusters alike.
+
+> This guide only covers installation on a new Ubuntu 20.04 LTS machine. If you
+> are looking to install on a local machine or an existing host,
+> [Kind](./kind.md) or k3d may be a better choice.
+
+## Prerequisites
+
+Before proceeding, please make sure that you have the following:
+
+1. **Ubuntu 20.04 machine**: This can be a bare metal or virtual machine. For
+   cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr, or DigitalOcean
+   all work. Make sure the machine specs satisfies Coder's
+   [resource requirements](../requirements.md)
+1. Network policy exposting ports 22, 80, 443, and 5522 (alternative SSH port)
+1. The following software installed on the machine:
+   - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+   - [helm](https://helm.sh/docs/intro/install/)
+
+### Resource allocation and performance
+
+Your experience with Coder is dependent on your system specs. See our
+[resource requirements](../requirements.md) for more details.
+
+## Change the default SSH port
+
+If you want to allow
+[SSH into workspaces](https://coder.com/docs/coder/v1.20/workspaces/ssh), you
+will need to change the host's default SSH port to free up port 22.
+
+[Follow this guide](https://linuxize.com/post/how-to-change-ssh-port-in-linux/)
+by Linuxize if you do not know how to do this.
+
+## Install k3s with Calico
+
+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 -
+   ```
+
+1. Install the Calico operator and CRDs
+
+   ```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 all of the pods are running
+
+   ```console
+   watch kubectl get pods --all-namespaces
+   ```
+
+See the
+[Calico docs](https://docs.projectcalico.org/getting-started/kubernetes/k3s/quickstart)
+for a more detailed tutorial and troubleshooting info.
+
+## Allow IP Forwarding
+
+Modify Calico so that IP forwarding is allowed in the container_settings
+section.
+
+Edit the value in the following places:
+
+```console
+vim /etc/cni/net.d/10-canal.conflist
+
+kubectl edit cm cni-config -n calico-system
+```
+
+```json
+"container_settings": {
+   "allow_ip_forwarding": true
+}
+```
+
+### Ensure `$KUBECONFIG` is defined
+
+Sometimes helm will not properly recognize the k3s cluster
+(k3s-io/[k3s#1126](k3s#1126)). To resolve this, add the following to your
+`~/.bashrc`:
+
+```console
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml`
+```
+
+## Next steps
+
+At this point, you're ready to proceed to [installation](../installation.md).

From 94041226a0b79f5e0234c2aac12c085dfc1d707e Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Tue, 22 Jun 2021 09:42:29 -0400
Subject: [PATCH 02/14] fix github link

---
 setup/kubernetes/k3s.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index dbd6d461e..3bb2ee7e6 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -85,8 +85,8 @@ kubectl edit cm cni-config -n calico-system
 ### Ensure `$KUBECONFIG` is defined
 
 Sometimes helm will not properly recognize the k3s cluster
-(k3s-io/[k3s#1126](k3s#1126)). To resolve this, add the following to your
-`~/.bashrc`:
+(k3s-io/[k3s#1126](https://github.com/k3s-io/k3s/issues/1126)). To resolve this,
+add the following to your `~/.bashrc`:
 
 ```console
 export KUBECONFIG=/etc/rancher/k3s/k3s.yaml`

From e1d09aab442332aa8299037af3f4455b27245ace Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Tue, 22 Jun 2021 09:55:33 -0400
Subject: [PATCH 03/14] fix wording

---
 setup/kubernetes/k3s.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 3bb2ee7e6..674cd356c 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -3,8 +3,8 @@ title: "k3s"
 description: Set up a Coder deployment with a Ubuntu + k3s
 ---
 
-k3s is a lightweight Kubernetes distribution that works great with single-node
-or multi-node clusters alike.
+k3s is a lightweight Kubernetes distribution that works well for single-node or
+multi-node clusters alike.
 
 > This guide only covers installation on a new Ubuntu 20.04 LTS machine. If you
 > are looking to install on a local machine or an existing host,
@@ -15,8 +15,8 @@ or multi-node clusters alike.
 Before proceeding, please make sure that you have the following:
 
 1. **Ubuntu 20.04 machine**: This can be a bare metal or virtual machine. For
-   cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr, or DigitalOcean
-   all work. Make sure the machine specs satisfies Coder's
+   cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr, DigitalOcean
+   work well. Make sure the machine specs satisfies Coder's
    [resource requirements](../requirements.md)
 1. Network policy exposting ports 22, 80, 443, and 5522 (alternative SSH port)
 1. The following software installed on the machine:

From 5f5a617de033e1eab9413f3fe6e4c2cc9445af96 Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Tue, 22 Jun 2021 16:17:29 -0400
Subject: [PATCH 04/14] edits from feedback

---
 setup/kubernetes/k3s.md | 58 +++++++++++++++++++++++++++++------------
 1 file changed, 41 insertions(+), 17 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 674cd356c..8614c57bf 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -6,9 +6,13 @@ description: Set up a Coder deployment with a Ubuntu + k3s
 k3s is a lightweight Kubernetes distribution that works well for single-node or
 multi-node clusters alike.
 
-> This guide only covers installation on a new Ubuntu 20.04 LTS machine. If you
-> are looking to install on a local machine or an existing host,
-> [Kind](./kind.md) or k3d may be a better choice.
+This guide covers installation on a new Ubuntu 20.04 LTS machine. If you are
+looking to install Coder on a local machine or an existing host,
+[Kind](./kind.md) or k3d may be a better choice.
+
+> This install method is not officially supported or tested by Coder. If you
+> have questions or run into issues, feel free to reach out on our
+> [community Slack channel](https://cdr.co/join-community).
 
 ## Prerequisites
 
@@ -18,7 +22,8 @@ Before proceeding, please make sure that you have the following:
    cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr, DigitalOcean
    work well. Make sure the machine specs satisfies Coder's
    [resource requirements](../requirements.md)
-1. Network policy exposting ports 22, 80, 443, and 5522 (alternative SSH port)
+1. Network firewall exposting ports 22 (SSH), 80 (HTTP), 443 (HTTPS), and 8443
+   (Kubernetes API).
 1. The following software installed on the machine:
    - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
    - [helm](https://helm.sh/docs/intro/install/)
@@ -32,21 +37,40 @@ Your experience with Coder is dependent on your system specs. See our
 
 If you want to allow
 [SSH into workspaces](https://coder.com/docs/coder/v1.20/workspaces/ssh), you
-will need to change the host's default SSH port to free up port 22.
+will need to change the host's default SSH port to free up port 22. You may also
+need to modify your network policy to open up the alternative port (e.g 5522)
 
 [Follow this guide](https://linuxize.com/post/how-to-change-ssh-port-in-linux/)
 by Linuxize if you do not know how to do this.
 
 ## Install k3s with Calico
 
-1. Create a single-node k3s cluster
+The following uses
+[Calico's quickstart guide](https://docs.projectcalico.org/getting-started/kubernetes/k3s/quickstart)
+to set up K3s. We will be disabling the 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 -
+   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 --dis55able=traefik" sh -
    ```
 
+   > From 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 directory with limited
+   > permissions, using K3S_KUBECONFIG_MODE environment you are assigning
+   > necessary permissions to the file and make it accessible for other users.
+
 1. Install the Calico operator and CRDs
 
+   Calico is used to implement network segmentation and tenant isolation.
+
    ```console
    kubectl create -f https://docs projectcalico.org/manifests tigera-operator.yaml
 
@@ -59,14 +83,10 @@ by Linuxize if you do not know how to do this.
    watch kubectl get pods --all-namespaces
    ```
 
-See the
-[Calico docs](https://docs.projectcalico.org/getting-started/kubernetes/k3s/quickstart)
-for a more detailed tutorial and troubleshooting info.
-
 ## Allow IP Forwarding
 
-Modify Calico so that IP forwarding is allowed in the container_settings
-section.
+IP forwarding is necessary for container networking. Modify Calico so that IP
+forwarding is allowed in the container_settings section.
 
 Edit the value in the following places:
 
@@ -82,16 +102,20 @@ kubectl edit cm cni-config -n calico-system
 }
 ```
 
-### Ensure `$KUBECONFIG` is defined
+### Copy your kubeconfig
 
 Sometimes helm will not properly recognize the k3s cluster
-(k3s-io/[k3s#1126](https://github.com/k3s-io/k3s/issues/1126)). To resolve this,
-add the following to your `~/.bashrc`:
+(k3s-io/[k3s#1126](https://github.com/k3s-io/k3s/issues/1126)).
 
 ```console
-export KUBECONFIG=/etc/rancher/k3s/k3s.yaml`
+# on the host machine:
+cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
 ```
 
+If you want to interface with the cluster from your local machine,,
+`/etc/rancher/k3s/k3s.yaml` to `~/.kube/config` on your local machine. Replace
+localhost or 127.0.0.1 with the host's public IP address.
+
 ## Next steps
 
 At this point, you're ready to proceed to [installation](../installation.md).

From 38339a6f5b594e0388f8b7b26055bbf63a9552f8 Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Tue, 22 Jun 2021 16:19:45 -0400
Subject: [PATCH 05/14] clarify wording

---
 setup/kubernetes/k3s.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 8614c57bf..8ed136be2 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -22,8 +22,8 @@ Before proceeding, please make sure that you have the following:
    cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr, DigitalOcean
    work well. Make sure the machine specs satisfies Coder's
    [resource requirements](../requirements.md)
-1. Network firewall exposting ports 22 (SSH), 80 (HTTP), 443 (HTTPS), and 8443
-   (Kubernetes API).
+1. Network policy or firewall accepting incoming traffic on ports 22 (SSH), 80
+   (HTTP), 443 (HTTPS), and 8443 (Kubernetes API).
 1. The following software installed on the machine:
    - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
    - [helm](https://helm.sh/docs/intro/install/)
@@ -38,7 +38,8 @@ Your experience with Coder is dependent on your system specs. See our
 If you want to allow
 [SSH into workspaces](https://coder.com/docs/coder/v1.20/workspaces/ssh), you
 will need to change the host's default SSH port to free up port 22. You may also
-need to modify your network policy to open up the alternative port (e.g 5522)
+need to modify your firewall to accept incoming traffic from the alternative
+port (e.g 5522)
 
 [Follow this guide](https://linuxize.com/post/how-to-change-ssh-port-in-linux/)
 by Linuxize if you do not know how to do this.

From a9067dfd8c7b6759f74dd8038f227ae58c3d0ceb Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Tue, 22 Jun 2021 16:36:52 -0400
Subject: [PATCH 06/14] add TURN port

---
 setup/kubernetes/k3s.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 8ed136be2..deab43965 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -23,7 +23,7 @@ Before proceeding, please make sure that you have the following:
    work well. Make sure the machine specs satisfies Coder's
    [resource requirements](../requirements.md)
 1. Network policy or firewall accepting incoming traffic on ports 22 (SSH), 80
-   (HTTP), 443 (HTTPS), and 8443 (Kubernetes API).
+   (HTTP), 443 (HTTPS), 5349 (Networking v2 / TURN), and 8443 (Kubernetes API).
 1. The following software installed on the machine:
    - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
    - [helm](https://helm.sh/docs/intro/install/)

From 02074c4493cab756a18d1cfa634e270ee48207e8 Mon Sep 17 00:00:00 2001
From: Katie Horne <katie@coder.com>
Date: Wed, 23 Jun 2021 13:17:47 -0500
Subject: [PATCH 07/14] Edit text

---
 setup/kubernetes/k3s.md | 107 ++++++++++++++++++++--------------------
 1 file changed, 54 insertions(+), 53 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index deab43965..7ab402c60 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -1,63 +1,65 @@
 ---
-title: "k3s"
-description: Set up a Coder deployment with a Ubuntu + k3s
+title: "K3s"
+description: Set up K3s on an Ubuntu machine to deploy Coder.
 ---
 
-k3s is a lightweight Kubernetes distribution that works well for single-node or
-multi-node clusters alike.
+This article will show you how to install K3s onto a new Ubuntu 20.04 LTS
+machine for use with Coder.
 
-This guide covers installation on a new Ubuntu 20.04 LTS machine. If you are
-looking to install Coder on a local machine or an existing host,
-[Kind](./kind.md) or k3d may be a better choice.
+[K3s](https://k3s.io/) is a lightweight Kubernetes distribution that works well
+for both single-node or multi-node clusters. This guide covers the installation
+of K3s onto a new Ubuntu 20.04 LTS machine, but if you want to install Coder on
+a local machine or an existing host, [Kind](./kind.md) or [k3d](https://k3d.io/)
+are better choices.
 
-> This install method is not officially supported or tested by Coder. If you
-> have questions or run into issues, feel free to reach out on our
+> 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).
 
 ## Prerequisites
 
-Before proceeding, please make sure that you have the following:
+Before proceeding, please make sure that:
 
-1. **Ubuntu 20.04 machine**: This can be a bare metal or virtual machine. For
-   cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr, DigitalOcean
-   work well. Make sure the machine specs satisfies Coder's
-   [resource requirements](../requirements.md)
-1. Network policy or firewall accepting incoming traffic on ports 22 (SSH), 80
-   (HTTP), 443 (HTTPS), 5349 (Networking v2 / TURN), and 8443 (Kubernetes API).
-1. The following software installed on the machine:
+1. You have an **Ubuntu 20.04 machine**: This can be a bare metal or a virtual
+   machine. For cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr,
+   and DigitalOcean all work well.
+
+   Ensure that the machine's specs satisfies
+   Coder's [resource requirements](../requirements.md), since your experience
+   with Coder is dependent on your system specs.
+
+1. 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/)
 
-### Resource allocation and performance
+1. Your network policy or firewall accepts incoming traffic on ports 22 (SSH),
+   80 (HTTP), 443 (HTTPS), 5349 (Networking v2 / TURN), and 8443 (Kubernetes
+   API).
 
-Your experience with Coder is dependent on your system specs. See our
-[resource requirements](../requirements.md) for more details.
+## Step 1: Change the default SSH port
 
-## Change the default SSH port
+To allow [SSH into
+workspaces](https://coder.com/docs/coder/v1.20/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 5522).
 
-If you want to allow
-[SSH into workspaces](https://coder.com/docs/coder/v1.20/workspaces/ssh), you
-will need to 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 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/)
 
-[Follow this guide](https://linuxize.com/post/how-to-change-ssh-port-in-linux/)
-by Linuxize if you do not know how to do this.
+## Step 2: Install K3s with Calico
 
-## 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 the default network policies and
+Traefik in favor of Calico and nginx-ingress.
 
-The following uses
-[Calico's quickstart guide](https://docs.projectcalico.org/getting-started/kubernetes/k3s/quickstart)
-to set up K3s. We will be disabling the default network policies and Traefik in
-favor of Calico and nginx-ingress.
-
-1. Create a single-node k3s cluster.
+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 --dis55able=traefik" sh -
    ```
 
-   > From the
+   > 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
@@ -68,9 +70,8 @@ favor of Calico and nginx-ingress.
    > permissions, using K3S_KUBECONFIG_MODE environment you are assigning
    > necessary permissions to the file and make it accessible for other users.
 
-1. Install the Calico operator and CRDs
-
-   Calico is used to implement network segmentation and tenant isolation.
+1. Install the Calico operator and CRDs (Calico is used to implement network
+   segmentation and tenant isolation):
 
    ```console
    kubectl create -f https://docs projectcalico.org/manifests tigera-operator.yaml
@@ -78,18 +79,15 @@ favor of Calico and nginx-ingress.
    kubectl create -f https://docs.projectcalico.org/manifests/custom-resources.yaml
    ```
 
-1. Confirm all of the pods are running
+1. Confirm that all of the pods are running:
 
    ```console
    watch kubectl get pods --all-namespaces
    ```
 
-## Allow IP Forwarding
+## Step 3: Allow IP Forwarding
 
-IP forwarding is necessary for container networking. Modify Calico so that IP
-forwarding is allowed in the container_settings section.
-
-Edit the value in the following places:
+Modify Calico to enable IP forwarding, which is needed for container networking.
 
 ```console
 vim /etc/cni/net.d/10-canal.conflist
@@ -97,26 +95,29 @@ 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
 }
 ```
 
-### Copy your kubeconfig
+## Step 4: Copy over the kubeconfig
 
-Sometimes helm will not properly recognize the k3s cluster
-(k3s-io/[k3s#1126](https://github.com/k3s-io/k3s/issues/1126)).
+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` on your local
+machine. Ensure that you replace
+`localhost` or `127.0.0.1` with the host's public IP address:
 
 ```console
 # on the host machine:
 cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
 ```
 
-If you want to interface with the cluster from your local machine,,
-`/etc/rancher/k3s/k3s.yaml` to `~/.kube/config` on your local machine. Replace
-localhost or 127.0.0.1 with the host's public IP address.
-
 ## Next steps
 
-At this point, you're ready to proceed to [installation](../installation.md).
+At this point, you're ready to proceed to [installing Coder](../installation.md).

From 6738ada25b4762f79c6b583a180490d8e04ecc62 Mon Sep 17 00:00:00 2001
From: Katie Horne <katie@coder.com>
Date: Fri, 25 Jun 2021 11:21:14 -0500
Subject: [PATCH 08/14] Edit text

---
 setup/kubernetes/k3s.md | 51 ++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 21 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 7ab402c60..dbd088fcb 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -7,7 +7,7 @@ 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 both single-node or multi-node clusters. This guide covers the installation
+for single-node or multi-node clusters. This guide covers the installation
 of K3s onto a new Ubuntu 20.04 LTS machine, but if you want to install Coder on
 a local machine or an existing host, [Kind](./kind.md) or [k3d](https://k3d.io/)
 are better choices.
@@ -15,16 +15,18 @@ are better choices.
 > 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:
 
 1. You have an **Ubuntu 20.04 machine**: This can be a bare metal or a virtual
-   machine. For cloud compute, AWS EC2, GCP Compute Engine, Azure VMs, Vultr,
-   and DigitalOcean all work well.
+   machine. AWS EC2, GCP Compute Engine, Azure VMs, Vultr,
+   and DigitalOcean all offer options that work well for cloud computing.
 
-   Ensure that the machine's specs satisfies
+   Ensure that the machine's specs satisfy
    Coder's [resource requirements](../requirements.md), since your experience
    with Coder is dependent on your system specs.
 
@@ -32,16 +34,19 @@ Before proceeding, please make sure that:
    - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
    - [helm](https://helm.sh/docs/intro/install/)
 
-1. Your network policy or firewall accepts incoming traffic on ports 22 (SSH),
-   80 (HTTP), 443 (HTTPS), 5349 (Networking v2 / TURN), and 8443 (Kubernetes
-   API).
+1. Your network policy or firewall accepts incoming traffic on:
+   - Port 22 (SSH)
+   - Port 80 (HTTP)
+   - Port 443 (HTTPS)
+   - Port 5349 (Networking v2 / TURN)
+   - **Optional**: Port 8443 (Kubernetes API)
 
 ## Step 1: Change the default SSH port
 
 To allow [SSH into
 workspaces](https://coder.com/docs/coder/v1.20/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 5522).
+firewall to accept incoming traffic from the alternative port (e.g. `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/)
@@ -56,22 +61,22 @@ 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 --dis55able=traefik" sh -
+   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):
+   > 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
+   > 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 directory with limited
-   > permissions, using K3S_KUBECONFIG_MODE environment you are assigning
-   > necessary permissions to the file and make it accessible for other users.
+   > 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 is used to implement network
-   segmentation and tenant isolation):
+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
@@ -109,9 +114,13 @@ 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` on your local
-machine. Ensure that you replace
-`localhost` or `127.0.0.1` with the host's public IP address:
+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:

From a56c8f20d64917d7d6b76e345f757ddcbe69b37d Mon Sep 17 00:00:00 2001
From: Katie Horne <katie@coder.com>
Date: Fri, 25 Jun 2021 11:24:14 -0500
Subject: [PATCH 09/14] Lint

---
 setup/kubernetes/k3s.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index dbd088fcb..49ee2650b 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -15,7 +15,7 @@ are better choices.
 > 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

From f68147f9a664a3cc92b038e0fae1027e908aaca8 Mon Sep 17 00:00:00 2001
From: Katie Horne <katie@coder.com>
Date: Fri, 25 Jun 2021 12:59:26 -0500
Subject: [PATCH 10/14] Update text

---
 setup/kubernetes/k3s.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 49ee2650b..202b467f6 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -45,8 +45,9 @@ Before proceeding, please make sure that:
 
 To allow [SSH into
 workspaces](https://coder.com/docs/coder/v1.20/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. `5522`).
+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/)
@@ -55,7 +56,7 @@ firewall to accept incoming traffic from the alternative port (e.g. `5522`).
 
 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 the default network policies and
+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:

From 2ff110c510613e65b46a26c09869c812d456b58d Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Mon, 28 Jun 2021 10:10:06 -0400
Subject: [PATCH 11/14] networking v2 -> TURNS

Co-authored-by: Jonathan Yu <jonathan@coder.com>
---
 setup/kubernetes/k3s.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 202b467f6..6deda2c05 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -38,7 +38,7 @@ Before proceeding, please make sure that:
    - Port 22 (SSH)
    - Port 80 (HTTP)
    - Port 443 (HTTPS)
-   - Port 5349 (Networking v2 / TURN)
+   - Port 5349 (TURNS)
    - **Optional**: Port 8443 (Kubernetes API)
 
 ## Step 1: Change the default SSH port

From 2279f4bdc22a5a6a5944a45b19ff7d8bd4c3ff4c Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Mon, 28 Jun 2021 10:18:00 -0400
Subject: [PATCH 12/14] apply jawnsy feedback

---
 setup/kubernetes/k3s.md | 44 +++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 6deda2c05..772edf6aa 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -7,10 +7,11 @@ 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, but if you want to install Coder on
-a local machine or an existing host, [Kind](./kind.md) or [k3d](https://k3d.io/)
-are better choices.
+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
@@ -23,14 +24,14 @@ are better choices.
 Before proceeding, please make sure that:
 
 1. You have an **Ubuntu 20.04 machine**: This can be a bare metal or a virtual
-   machine. AWS EC2, GCP Compute Engine, Azure VMs, Vultr,
-   and DigitalOcean all offer options that work well for cloud computing.
+   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.
+   Ensure that the machine's specs satisfy Coder's
+   [resource requirements](../requirements.md), since your experience with Coder
+   is dependent on your system specs.
 
 1. 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/)
 
@@ -43,19 +44,18 @@ Before proceeding, please make sure that:
 
 ## Step 1: Change the default SSH port
 
-To allow [SSH into
-workspaces](https://coder.com/docs/coder/v1.20/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`).
+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)
+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.
 
@@ -65,8 +65,8 @@ Traefik in favor of Calico and nginx-ingress.
    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):
+   > 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
@@ -111,8 +111,9 @@ Under `container_settings`, set `allow_ip_forwarding` to `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).
+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`.
@@ -130,4 +131,5 @@ cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
 
 ## Next steps
 
-At this point, you're ready to proceed to [installing Coder](../installation.md).
+At this point, you're ready to proceed to
+[installing Coder](../installation.md).

From 9060c04bf382caff89d243378e4afbf27014af77 Mon Sep 17 00:00:00 2001
From: Ben Potter <me@bpmct.net>
Date: Mon, 28 Jun 2021 10:57:35 -0400
Subject: [PATCH 13/14] mention networking v2

---
 setup/kubernetes/k3s.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 772edf6aa..6a718b705 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -44,10 +44,15 @@ Before proceeding, please make sure that:
 
 ## Step 1: Change the default SSH port
 
-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 enable Networking v2 after installing Coder (in
+`Manage > Admin > Infrastructure`), this step is not necessary to SSH into
+workspaces, as TURNS is used instead.
+
+Otherwise, in order 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/)

From 2a07a99918287c8aade78a005ee0fd1dd8f19d49 Mon Sep 17 00:00:00 2001
From: Katie Horne <katie@coder.com>
Date: Wed, 30 Jun 2021 09:57:26 -0500
Subject: [PATCH 14/14] Edit text

---
 setup/kubernetes/k3s.md | 63 +++++++++++++++++++++--------------------
 1 file changed, 32 insertions(+), 31 deletions(-)

diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md
index 6a718b705..ab88e9be9 100644
--- a/setup/kubernetes/k3s.md
+++ b/setup/kubernetes/k3s.md
@@ -9,9 +9,9 @@ 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.
+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
@@ -23,44 +23,45 @@ set up/tear down clusters with little hassle.
 
 Before proceeding, please make sure that:
 
-1. You have an **Ubuntu 20.04 machine**: This can be a bare metal or a virtual
+- 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.
+   Ensure that the machine's specs satisfy Coder's [resource
+   requirements](../requirements.md), since your experience with Coder is
+   dependent on your system specs.
 
-1. You have the following software installed on your machine:
+- 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/)
+  - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+  - [helm](https://helm.sh/docs/intro/install/)
 
-1. 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)
+- 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 enable Networking v2 after installing Coder (in
-`Manage > Admin > Infrastructure`), this step is not necessary to SSH into
-workspaces, as TURNS is used instead.
+> 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.
 
-Otherwise, in order 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`).
+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/)
+> [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)
+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.
 
@@ -70,8 +71,8 @@ Traefik in favor of Calico and nginx-ingress.
    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):
+   > 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
@@ -136,5 +137,5 @@ cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
 
 ## Next steps
 
-At this point, you're ready to proceed to
-[installing Coder](../installation.md).
+At this point, you're ready to proceed to [installing
+Coder](../installation.md).