From a230cf00f7ed52f0a612d5f537a7cf97e9814ce3 Mon Sep 17 00:00:00 2001
From: Jamie Hannaford <jamie@limetree.org>
Date: Wed, 1 Nov 2017 15:51:24 +0100
Subject: [PATCH] Make kubeadm docs for extra args clearer

---
 docs/admin/kubeadm.md                         | 24 ++++++++++++++++++
 .../independent/create-cluster-kubeadm.md     | 25 +++++++++----------
 2 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/docs/admin/kubeadm.md b/docs/admin/kubeadm.md
index c49ab00c48..4b7ea2691e 100644
--- a/docs/admin/kubeadm.md
+++ b/docs/admin/kubeadm.md
@@ -1003,6 +1003,30 @@ In summary, `kubeadm init --feature-gates=SelfHosting=true` works as follows:
 
 This process (steps 3-6) can also be triggered with `kubeadm phase selfhosting convert-from-staticpods`.
 
+## Customising the control plane with custom arguments {#custom-args}
+
+If you would like to override or extend the behaviour of a control plane component, you can provide 
+extra arguments to kubeadm. When the component is deployed, it will use these additional arguments _in its 
+pod command_. 
+
+For example, to add flag `--feature-gates=APIResponseCompression=true` to kube-apiserver, your [configuration file](#sample-master-configuration) 
+will need to look like this:
+
+```
+apiVersion: kubeadm.k8s.io/v1alpha1
+kind: MasterConfiguration
+apiServerExtraArgs:
+   feature-gates: APIResponseCompression=true
+```
+
+To customise the scheduler or controller-manager, use `schedulerExtraArgs` and `controllerManagerExtraArgs` respectively.
+
+More information on custom arguments can be found here:
+
+- [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver/)
+- [kube-controller-manager](https://kubernetes.io/docs/admin/kube-controller-manager/)
+- [kube-scheduler](https://kubernetes.io/docs/admin/kube-scheduler/)
+
 ## Releases and release notes
 
 If you already have kubeadm installed and want to upgrade, run `apt-get update
diff --git a/docs/setup/independent/create-cluster-kubeadm.md b/docs/setup/independent/create-cluster-kubeadm.md
index bba320bc23..6d362781d4 100644
--- a/docs/setup/independent/create-cluster-kubeadm.md
+++ b/docs/setup/independent/create-cluster-kubeadm.md
@@ -101,26 +101,25 @@ kubeadm on, and run:
 kubeadm init
 ```
 
-**Note:**
+**Notes:**
 
- - You need to choose a Pod Network Plugin in the next step. Depending on what
+- Please refer to the [kubeadm reference doc](/docs/admin/kubeadm/) if you want to
+read more about the flags `kubeadm init` provides. You can also specify a 
+[configuration file](/docs/admin/kubeadm/#sample-master-configuration) instead of using flags.
+- You need to choose a Pod Network Plugin in the next step. Depending on what
 third-party provider you choose, you might have to set the `--pod-network-cidr` to
 something provider-specific. The tabs below will contain a notice about what flags
 on `kubeadm init` are required.
- - This will autodetect the network interface to advertise the master on
-as the interface with the default gateway. If you want to use a different
-interface, specify `--apiserver-advertise-address=<ip-address>` argument to `kubeadm
-init`.
-
-Please refer to the [kubeadm reference doc](/docs/admin/kubeadm/) if you want to
-read more about the flags `kubeadm init` provides.
-
-`kubeadm init` will first run a series of prechecks to ensure that the machine
+- Unless otherwise specified, kubeadm uses the default gateway's network interface 
+to advertise the master's IP. If you want to use a different network interface, specify 
+`--apiserver-advertise-address=<ip-address>` argument to `kubeadm init`.
+- If you would like to customise control plane components, you can do so by providing 
+extra args to each one, as documented [here](/docs/admin/kubeadm#custom-args).
+- `kubeadm init` will first run a series of prechecks to ensure that the machine
 is ready to run Kubernetes.  It will expose warnings and exit on errors. It
 will then download and install the cluster database and control plane
 components. This may take several minutes.
-
-You can't run `kubeadm init` twice without tearing down the cluster in between
+- You can't run `kubeadm init` twice without tearing down the cluster in between
 ([unless you're upgrading from v1.6 to v1.7](/docs/tasks/administer-cluster/kubeadm-upgrade-1-7/)),
 see [Tear Down](#tear-down).