From f0f6212577396b8af92fa0bcf3f2d1870ff2ef46 Mon Sep 17 00:00:00 2001 From: Zihong Zheng Date: Thu, 17 Nov 2016 20:46:09 -0800 Subject: [PATCH] Adds docs for dns horizontal autoscaling feature --- _data/tasks.yml | 2 + docs/admin/dns.md | 2 + .../dns-horizontal-autoscaler.yaml | 31 +++ .../dns-horizontal-autoscaling.md | 238 ++++++++++++++++++ docs/tasks/index.md | 1 + 5 files changed, 274 insertions(+) create mode 100644 docs/tasks/administer-cluster/dns-horizontal-autoscaler.yaml create mode 100644 docs/tasks/administer-cluster/dns-horizontal-autoscaling.md diff --git a/_data/tasks.yml b/_data/tasks.yml index 1dc775ef73..24e19c35c1 100644 --- a/_data/tasks.yml +++ b/_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 diff --git a/docs/admin/dns.md b/docs/admin/dns.md index d75acfa093..372d9a026e 100644 --- a/docs/admin/dns.md +++ b/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/). diff --git a/docs/tasks/administer-cluster/dns-horizontal-autoscaler.yaml b/docs/tasks/administer-cluster/dns-horizontal-autoscaler.yaml new file mode 100644 index 0000000000..ce6a7c4b09 --- /dev/null +++ b/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= + # 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 diff --git a/docs/tasks/administer-cluster/dns-horizontal-autoscaling.md b/docs/tasks/administer-cluster/dns-horizontal-autoscaling.md new file mode 100644 index 0000000000..6ccc505468 --- /dev/null +++ b/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/ + +where 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/ + +where 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 `` 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 %} diff --git a/docs/tasks/index.md b/docs/tasks/index.md index 486d8f4af2..d8e46cff09 100644 --- a/docs/tasks/index.md +++ b/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