From 29d5494940a90d2ee6a48678d61a0227431b1b06 Mon Sep 17 00:00:00 2001
From: Ole Markus With <o.with@sportradar.com>
Date: Sun, 21 Mar 2021 07:38:53 +0100
Subject: [PATCH] Add docs about dedicated apiserver ndoes

---
 docs/advanced/experimental.md |  1 +
 docs/operations/scaling.md    | 39 +++++++++++++++++++++++++++++++++++
 docs/releases/1.21-NOTES.md   |  9 ++++++++
 mkdocs.yml                    |  1 +
 4 files changed, 50 insertions(+)
 create mode 100644 docs/operations/scaling.md

diff --git a/docs/advanced/experimental.md b/docs/advanced/experimental.md
index 5ce34a3d2e..4282010674 100644
--- a/docs/advanced/experimental.md
+++ b/docs/advanced/experimental.md
@@ -23,3 +23,4 @@ The following experimental features are currently available:
 * `+SkipEtcdVersionCheck` - Bypasses the check that etcd-manager is using a supported etcd version
 * `+TerraformJSON` - Produce kubernetes.tf.json file instead of writing HCLv2 syntax. Can be consumed by terraform 0.12+
 * `+VFSVaultSupport` - Enables setting Vault as secret/keystore
+* `+APIServerNodes` - Enables support for dedicated API server nodes
diff --git a/docs/operations/scaling.md b/docs/operations/scaling.md
new file mode 100644
index 0000000000..d86da79d5c
--- /dev/null
+++ b/docs/operations/scaling.md
@@ -0,0 +1,39 @@
+# Scaling kOps
+
+## Scaling the control plane
+
+### Dedicated API Server nodes
+
+{{ kops_feature_table(kops_added_default='1.21') }}
+
+A common bottleneck of the control plane is the API server. As the number of pods and nodes grow, you will want to add more resources to handle the load.
+
+You can scale the API server horizontally by adding instance groups dedicated to running API server nodes. You can do so by adding an instance group with the `APIServer` role:
+
+```yaml
+apiVersion: kops.k8s.io/v1alpha2
+kind: InstanceGroup
+metadata:
+  creationTimestamp: null
+  labels:
+    kops.k8s.io/cluster: <cluster name>
+  name: apiserver-eu-central-1a
+spec:
+  image: 099720109477/ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-20201026
+  machineType: t3.small
+  maxSize: 3
+  minSize: 3
+  nodeLabels:
+    kops.k8s.io/instancegroup: apiserver-eu-central-1a
+  role: APIServer
+  subnets:
+  - eu-central-1a
+
+```
+
+or run `kops create ig --name=<cluster name> apiserver-eu-central-1a --subnet=eu-central-1a`
+
+Because the labels, taints, and domains can change, this feature is currently behind a feature gate.
+```sh
+export KOPS_FEATURE_FLAGS="+APIServerNodes"
+```
\ No newline at end of file
diff --git a/docs/releases/1.21-NOTES.md b/docs/releases/1.21-NOTES.md
index 32498271fe..c01f277cdd 100644
--- a/docs/releases/1.21-NOTES.md
+++ b/docs/releases/1.21-NOTES.md
@@ -4,8 +4,17 @@
 
 # Significant changes
 
+## Dedicated API Server nodes.
+
+kOps now supports extending the control plane with [dedicated apiserver nodes](https://kops.sigs.k8s.io/operations/scaling). These nodes run in dedicated instance groups that can be scaled horizontally.
+
+In 1.21, this feature is behind a feature flag as node role name, labels, taints, and domains can change based on feedback from the community.
+
+# Other significant changes
+
 * Protokube now runs as a systemd process rather than a docker container.
 
+
 # Breaking changes
 
 # Required Actions
diff --git a/mkdocs.yml b/mkdocs.yml
index 82bf160574..579dfe8aa9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -75,6 +75,7 @@ nav:
     - Working with Instance Groups: "tutorial/working-with-instancegroups.md"
     - Using Manifests and Customizing: "manifests_and_customizing_via_api.md"
     - High Availability: "operations/high_availability.md"
+    - Scaling: "operations/scaling.md"
     - Instancegroup images: "operations/images.md"
     - Cluster configuration management: "changing_configuration.md"
     - Cluster Templating: "operations/cluster_template.md"