chore: clarify version support policy (#232)

jawnsy · Katie Horne · web-flow · commit 654441546990 · 2021-07-12T16:07:53.000-07:00
Recommend that users track supported Kubernetes versions, and remove
the reference to version 1.13.

Co-authored-by: Katie Horne &lt;katie@coder.com&gt;
diff --git a/admin/workspace-management/cvms.md b/admin/workspace-management/cvms.md
@@ -44,11 +44,11 @@ Google, Azure, and Amazon to support CVMs.
 To use CVMs with GKE, [create a cluster](../../setup/kubernetes/google.md) using
 the following parameters:
 
-- GKE Master version `>= 1.17`
-- `node-version >= 1.17`
+- GKE Master version `latest`
+- `node-version = "latest"`
 - `image-type = "UBUNTU"`
 
-You can also provide `latest` instead of specific version numbers. For example:
+For example:
 
 ```console
 gcloud beta container clusters create "YOUR_NEW_CLUSTER" \
diff --git a/guides/ssl-certificates/cloudflare.md b/guides/ssl-certificates/cloudflare.md
@@ -22,18 +22,14 @@ you can enable HTTPS on your Coder deployment.
 
 You must have:
 
-- A Kubernetes cluster (v1.15 or greater) with internet connectivity
+- A Kubernetes cluster [meeting Coder's
+  requirements](../../setup/kubernetes/index.md) with internet connectivity
 - kubectl with patch version
   [greater than v1.18.8, v1.17.11, or v1.16.14](https://cert-manager.io/docs/installation/upgrading/upgrading-0.15-0.16/#issue-with-older-versions-of-kubectl)
 
 ## Step 1: Add cert-manager to your Kubernetes cluster
 
 ```console
-# Kubernetes 1.16+
-$ kubectl apply --validate=false -f \
-https://github.com/jetstack/cert-manager/releases/download/v1.0.1/cert-manager.yaml
-
-# Kubernetes <1.16
 $ kubectl apply --validate=false -f \
 https://github.com/jetstack/cert-manager/releases/download/v1.0.1/cert-manager-legacy.yaml
 ```
diff --git a/guides/ssl-certificates/route53.md b/guides/ssl-certificates/route53.md
@@ -23,8 +23,8 @@ configure your Coder hostname and dev URLs.
 
 You must have:
 
-- A [Kubernetes cluster](../../setup/kubernetes/index.md) (v1.17 or greater)
-  with internet connectivity
+- A Kubernetes cluster [meeting Coder's
+  requirements](../../setup/kubernetes/index.md) with internet connectivity
 - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
 
 You should also:
diff --git a/setup/kubernetes/aws.md b/setup/kubernetes/aws.md
@@ -84,13 +84,14 @@ SSH_KEY_PATH="<PATH/TO/KEY>.pub"
 REGION="YOUR_REGION"
 ```
 
-The following will spin up a Kubernetes cluster using `eksctl`:
+The following will spin up a Kubernetes cluster using `eksctl` (be sure to
+update the parameters as necessary, especially the version number):
 
 ```console
 
   eksctl create cluster \
   --name "$CLUSTER_NAME" \
-  --version 1.17 \
+  --version <version> \
   --region "$REGION" \
   --nodegroup-name standard-workers \
   --node-type t3.medium \
@@ -172,7 +173,7 @@ as a workspace deployment option, you'll need to
    kind: ClusterConfig
 
    metadata:
-     version: "1.17"
+     version: "<YOUR_K8s_VERSION"
      name: <YOUR_CLUSTER_NAME>
      region: <YOUR_AWS_REGION>
 
diff --git a/setup/kubernetes/index.md b/setup/kubernetes/index.md
@@ -1,13 +1,35 @@
 ---
 title: Kubernetes
-description: Learn how to set up a K8 cluster for your Coder deployment.
+description: Learn how to set up a Kubernetes cluster for your Coder deployment.
 ---
 
-You can install and deploy Coder onto any Kubernetes cluster (version 1.13.7+)
-that meets the [requirements](../requirements.md).
+This section contains guides for creating a compatible cluster on common cloud
+platforms, including Microsoft Azure, Google Cloud Platform, and Amazon Web
+Services. If you already have a Kubernetes cluster, you may wish to proceed to
+the [installation guide].
 
-To help you get up and running, Coder offers the following deployment guides (if
-you're already set up with a Kubernetes cluster, please proceed to
-[installation](../installation.md)):
+## Supported Kubernetes versions
+
+You can deploy Coder to any [compatible Kubernetes cluster]. Coder follows the
+[Kubernetes upstream version support policy], and the latest stable release
+version of Coder supports the previous two minor releases as well as the current
+release of Kubernetes at time of publication.
+
+Coder may run successfully with
+older versions of Kubernetes. However, we strongly recommend running one of the
+currently-supported versions so that you receive applicable fixes, including
+security updates, from the Kubernetes project maintainers.
+
+Coder continuously removes usage of deprecated Kubernetes API versions once
+the minimum baseline version of Kubernetes supports the necessary features in
+a stable version. We follow this policy to ensure that Coder stops
+using deprecated features before they are removed from new versions of
+Kubernetes.
+
+[compatible kubernetes cluster]: ../requirements.md
+[kubernetes upstream version support policy]:
+  https://kubernetes.io/docs/setup/release/version-skew-policy/
+
+[installation guide]: ../installation.md
 
 <children></children>
