From f3844bb2d844902f25b2bb1d36f7684b822e222f Mon Sep 17 00:00:00 2001
From: Mitchel Humpherys <mitch@directangular.com>
Date: Wed, 23 Oct 2019 17:38:35 -0700
Subject: [PATCH] docs: autoscaling: Add note about ASG tags for scaling up
 from 0

When the cluster-autoscaler adds a new node to a group, it grabs an
existing node in the group and builds a "template" to launch a new node
identical to the one it grabbed from the group.

However, when scaling up from 0 there aren't any live nodes to reference to
build this template.  Instead, the cluster-autoscaler relies on tags in the
ASG to build the new node template.  This can cause unexpected behavior if
the pods triggering the scale-out are using node selectors or taints; CA
doesn't have sufficient information to decide if a new node launched in the
group will satisfy the request.

The long and short of it is that for CA to do its job properly we must tag
our ASGs corresponding to our labels and taints.  Add a note in the docs
about this since scaling up from 0 is a fairly common use case.

References:

  - https://github.com/kubernetes/autoscaler/issues/2418
  - https://github.com/weaveworks/eksctl/issues/1066
---
 site/content/usage/04-autoscaling.md | 37 ++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/site/content/usage/04-autoscaling.md b/site/content/usage/04-autoscaling.md
index 6b628f883f3..ae5130277e7 100644
--- a/site/content/usage/04-autoscaling.md
+++ b/site/content/usage/04-autoscaling.md
@@ -15,6 +15,43 @@ eksctl create cluster --asg-access
 Once cluster is running, you will need to install [cluster autoscaler][] itself. This flag also sets `k8s.io/cluster-autoscaler/enabled`
 and `k8s.io/cluster-autoscaler/<clusterName>` tags, so nodegroup discovery should work.
 
+### Scaling up from 0
+
+If you'd like to be able to scale your node group up from 0 and you have
+labels and/or taints defined on your nodegroups you'll need corresponding
+tags on your ASGs.  You can do this with the `tags` key on your node group
+definitions.  For example, given a node group with the following labels and
+taints:
+
+```yaml
+nodeGroups:
+  - name: ng1-public
+    ...
+    labels:
+      my-cool-label: pizza
+    taints:
+      feaster: "true:NoSchedule"
+```
+
+You would need to add the following ASG tags:
+
+```yaml
+nodeGroups:
+  - name: ng1-public
+    ...
+    labels:
+      my-cool-label: pizza
+    taints:
+      feaster: "true:NoSchedule"
+    tags:
+      k8s.io/cluster-autoscaler/node-template/label/my-cool-label: pizza
+      k8s.io/cluster-autoscaler/node-template/taint/feaster: "true:NoSchedule"
+```
+
+You can read more about this
+[here](https://github.com/weaveworks/eksctl/issues/1066) and
+[here](https://github.com/kubernetes/autoscaler/issues/2418).
+
 [cluster autoscaler]: https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/README.md
 
 ### Zone-aware Auto Scaling