Merge pull request #1727 from MrHohn/dns-autoscaling-doc

Adds documentation for dns horizontal autoscaling feature

_data/tasks.yml

@@ -31,6 +31,8 @@ toc:
   section:
   - title: Assigning Pods to Nodes
     path: /docs/tasks/administer-cluster/assign-pods-nodes/
+  - title: Autoscaling the DNS Service in a Cluster
+    path: /docs/tasks/administer-cluster/dns-horizontal-autoscaling/
 - title: Managing Stateful Applications
   section:
   - title: Upgrading from PetSets to StatefulSets

docs/admin/dns.md

@@ -356,3 +356,5 @@ for more information.
 
 - [Docs for the DNS cluster addon](http://releases.k8s.io/{{page.githubbranch}}/build-tools/kube-dns/README.md)
 
+## What's next
+- [Autoscaling the DNS Service in a Cluster](/docs/tasks/administer-cluster/dns-horizontal-autoscaling/).

docs/tasks/administer-cluster/dns-horizontal-autoscaler.yaml

@@ -0,0 +1,31 @@
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: kube-dns-autoscaler
+  namespace: kube-system
+  labels:
+    k8s-app: kube-dns-autoscaler
+spec:
+  template:
+    metadata:
+      labels:
+        k8s-app: kube-dns-autoscaler
+    spec:
+      containers:
+      - name: autoscaler
+        image: gcr.io/google_containers/cluster-proportional-autoscaler-amd64:1.0.0
+        resources:
+            requests:
+                cpu: "20m"
+                memory: "10Mi"
+        command:
+          - /cluster-proportional-autoscaler
+          - --namespace=kube-system
+          - --configmap=kube-dns-autoscaler
+          - --mode=linear
+          - --target=<SCALE_TARGET>
+          # When cluster is using large nodes(with more cores), "coresPerReplica" should dominate.
+          # If using small nodes, "nodesPerReplica" should dominate.
+          - --default-params={"linear":{"coresPerReplica":256,"nodesPerReplica":16,"min":1}}
+          - --logtostderr=true
+          - --v=2

docs/tasks/administer-cluster/dns-horizontal-autoscaling.md

@@ -0,0 +1,238 @@
+---
+---
+
+{% capture overview %}
+This page shows how to enable and configure autoscaling of the DNS service in a
+Kubernetes cluster.
+{% endcapture %}
+
+{% capture prerequisites %}
+
+* {% include task-tutorial-prereqs.md %}
+
+* Make sure the [DNS feature](/docs/admin/dns/) itself is enabled.
+
+* Kubernetes version 1.4.0 or later is recommended.
+
+{% endcapture %}
+
+{% capture steps %}
+
+### Determining whether DNS horizontal autoscaling is already enabled
+
+List the Deployments in your cluster in the kube-system namespace:
+
+    kubectl get deployment --namespace=kube-system
+
+The output is similar to this:
+
+    NAME                  DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+    ...
+    kube-dns-autoscaler   1         1         1            1           ...
+    ...
+
+If you see "kube-dns-autoscaler" in the output, DNS horizontal autoscaling is
+already enabled, and you can skip to
+[Tuning autoscaling parameters](#tuning-autoscaling-parameters).
+
+### Getting the name of your DNS Deployment or ReplicationController
+
+List the Deployments in your cluster in the kube-system namespace:
+
+    kubectl get deployment --namespace=kube-system
+
+The output is similar to this:
+
+    NAME         DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+    ...
+    kube-dns     1         1         1            1           ...
+    ...
+
+In Kubernetes versions earlier than 1.5 DNS is implemented using a
+ReplicationController instead of a Deployment. So if you don't see kube-dns,
+or a similar name, in the preceding output, list the ReplicationControllers in
+your cluster in the kube-system namespace:
+
+    kubectl get rc --namespace=kube-system
+
+The output is similar to this:
+
+    NAME            DESIRED   CURRENT   READY     AGE
+    ...
+    kube-dns-v20    1         1         1         ...
+    ...
+
+### Determining your scale target
+
+If you have a DNS Deployment, your scale target is:
+
+    Deployment/<your-deployment-name>
+
+where <dns-deployment-name> is the name of your DNS Deployment. For example, if
+your DNS Deployment name is kube-dns, your scale target is Deployment/kube-dns.
+
+If you have a DNS ReplicationController, your scale target is:
+
+    ReplicationController/<your-rc-name>
+
+where <your-rc-name> is the name of your DNS ReplicationController. For example,
+if your DNS ReplicationController name is kube-dns-v20, your scale target is
+ReplicationController/kube-dns-v20.
+
+### Enabling DNS horizontal autoscaling
+
+In this section, you create a Deployment. The Pods in the Deployment run a
+container based on the `cluster-proportional-autoscaler-amd64` image.
+
+Create a file named `dns-horizontal-autoscaler.yaml` with this content:
+
+{% include code.html language="yaml" file="dns-horizontal-autoscaler.yaml" ghlink="/docs/tasks/administer-cluster/dns-horizontal-autoscaler.yaml" %}
+
+In the file, replace `<SCALE_TARGET>` with your scale target.
+
+Go to the directory that contains your configuration file, and enter this
+command to create the Deployment:
+
+    kubectl create -f dns-horizontal-autoscaler.yaml
+
+The output of a successful command is:
+
+    deployment "kube-dns-autoscaler" created
+
+DNS horizontal autoscaling is now enabled.
+
+### Tuning autoscaling parameters
+
+Verify that the kube-dns-autoscaler ConfigMap exists:
+
+    kubectl get configmap --namespace=kube-system
+
+The output is similar to this:
+
+    NAME                  DATA      AGE
+    ...
+    kube-dns-autoscaler   1         ...
+    ...
+
+Modify the data in the ConfigMap:
+
+    kubectl edit configmap kube-dns-autoscaler --namespace=kube-system
+
+Look for this line:
+
+    linear: '{"coresPerReplica":256,"min":1,"nodesPerReplica":16}'
+
+Modify the fields according to your needs. The "min" field indicates the
+minimal number of DNS backends. The actual number of backends number is
+calculated using this equation:
+
+    replicas = max( ceil( cores * 1/coresPerReplica ) , ceil( nodes * 1/nodesPerReplica ) )
+
+Note that the values of both `coresPerReplica` and `nodesPerReplica` are
+integers.
+
+The idea is that when a cluster is using nodes that have many cores,
+`coresPerReplica` dominates. When a cluster is using nodes that have fewer
+cores, `nodesPerReplica` dominates.
+
+There are other supported scaling patterns. For details, see
+[cluster-proportional-autoscaler](https://github.com/kubernetes-incubator/cluster-proportional-autoscaler).
+
+### Disable DNS horizontal autoscaling
+
+There are a few options for turning DNS horizontal autoscaling. Which option to
+use depends on different conditions.
+
+#### Option 1: Scale down the kube-dns-autoscaler deployment to 0 replicas
+
+This option works for all situations. Enter this command:
+
+    kubectl scale deployment --replicas=0 kube-dns-autoscaler --namespace=kube-system
+
+The output is:
+
+    deployment "kube-dns-autoscaler" scaled
+
+Verify that the replica count is zero:
+
+    kubectl get deployment --namespace-kube-system
+
+The output displays 0 in the DESIRED and CURRENT columns:
+
+    NAME                  DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+    ...
+    kube-dns-autoscaler   0         0         0            0           ...
+    ...
+
+#### Option 2: Delete the kube-dns-autoscaler deployment
+
+This option works if kube-dns-autoscaler is under your own control, which means
+no one will re-create it:
+
+    kubectl delete deployment kube-dns-autoscaler --namespace=kube-system
+
+The output is:
+
+    deployment "kube-dns-autoscaler" deleted
+
+#### Option 3: Delete the kube-dns-autoscaler manifest file from the master node
+
+This option works if kube-dns-autoscaler is under control of the
+[Addon Manager](https://github.com/kubernetes/kubernetes/blob/master/cluster/addons/README.md)'s
+control, and you have write access to the master node.
+
+Sign in to the master node and delete the corresponding manifest file.
+The common path for this kube-dns-autoscaler is:
+
+    /etc/kubernetes/addons/dns-horizontal-autoscaler/dns-horizontal-autoscaler.yaml
+
+After the manifest file is deleted, the Addon Manager will delete the
+kube-dns-autoscaler Deployment.
+
+{% endcapture %}
+
+{% capture discussion %}
+
+### Understanding how DNS horizontal autoscaling works
+
+* The cluster-proportional-autoscaler application is deployed separately from
+the DNS service.
+
+* An autoscaler Pod runs a client that polls the Kubernetes API server for the
+number of nodes and cores in the cluster.
+
+* A desired replica count is calculated and applied to the DNS backends based on
+the current schedulable nodes and cores and the given scaling parameters.
+
+* The scaling parameters and data points are provided via a ConfigMap to the
+autoscaler, and it refreshes its parameters table every poll interval to be up
+to date with the latest desired scaling parameters.
+
+* Changes to the scaling parameters are allowed without rebuilding or restarting
+the autoscaler Pod.
+
+* The autoscaler provides a controller interface to support two control
+patterns: *linear* and *ladder*.
+
+### Future enhancements
+
+Control patterns, in addition to linear and ladder, that consider custom metrics
+are under consideration as a future development.
+
+Scaling of DNS backends based on DNS-specific metrics is under consideration as
+a future development. The current implementation, which uses the number of nodes
+and cores in cluster, is limited.
+
+Support for custom metrics, similar to that provided by
+[Horizontal Pod Autoscaling](http://kubernetes.io/docs/user-guide/horizontal-pod-autoscaling/),
+is under consideration as a future development.
+
+{% endcapture %}
+
+{% capture whatsnext %}
+Learn more about the
+[implementation of cluster-proportional-autoscaler](https://github.com/kubernetes-incubator/cluster-proportional-autoscaler).
+{% endcapture %}
+
+
+{% include templates/task.md %}

docs/tasks/index.md

@@ -26,6 +26,7 @@ single thing, typically by giving a short sequence of steps.
 #### Administering a Cluster
 
 * [Assigning Pods to Nodes](/docs/tasks/administer-cluster/assign-pods-nodes/)
+* [Autoscaling the DNS Service in a Cluster](/docs/tasks/administer-cluster/dns-horizontal-autoscaling/)
 
 #### Managing Stateful Applications