Merge pull request #3699 from CecileRobertMichon/cabpk-docs-2

📖 Move CABPK docs to book and add examples

bootstrap/kubeadm/README.md → docs/book/src/tasks/kubeadm-bootstrap.md

@@ -1,16 +1,13 @@
 # Cluster API bootstrap provider kubeadm
 ## What is the Cluster API bootstrap provider kubeadm?
 
-Cluster API bootstrap provider Kubeadm (CABPK) is a component of
-[Cluster API](https://github.com/kubernetes-sigs/cluster-api/blob/master/README.md) 
-that is responsible of generating a cloud-init script to
-turn a Machine into a Kubernetes Node; this implementation uses [kubeadm](https://github.com/kubernetes/kubeadm) 
-for kubernetes bootstrap.
+Cluster API bootstrap provider Kubeadm (CABPK) is a component responsible for generating a cloud-init script to
+turn a Machine into a Kubernetes Node. This implementation uses [kubeadm](https://github.com/kubernetes/kubeadm) 
+for Kubernetes bootstrap.
 
 ### Resources
 
 * [design doc](https://github.com/kubernetes-sigs/cluster-api/blob/master/docs/proposals/20190610-machine-states-preboot-bootstrapping.md)
-* [cluster-api.sigs.k8s.io](https://cluster-api.sigs.k8s.io)
 * [The Kubebuilder Book](https://book.kubebuilder.io)
 
 ## How does CABPK work?
@@ -75,13 +72,13 @@ spec:
     kind: DockerMachine
     apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
     name: my-control-plane1-docker
-  version: "v1.14.2"
+  version: "v1.18.8"
 ```
 
 CABPK's main responsibility is to convert a `KubeadmConfig` bootstrap object into a cloud-init script that is
 going to turn a Machine into a Kubernetes Node using `kubeadm`.
 
-The cloud-init script will be saved into the `KubeadmConfig.Status.BootstrapData` and then the infrastructure provider
+The cloud-init script will be saved into a secret `KubeadmConfig.Status.DataSecretName` and then the infrastructure provider
 (CAPD in this example) will pick up this value and proceed with the machine creation and the actual bootstrap.
 
 ### KubeadmConfig objects
@@ -92,7 +89,7 @@ CABPK will fill in some values if they are left empty with sensible defaults:
 
 | `KubeadmConfig` field                           | Default                                                      |
 | ----------------------------------------------- | ------------------------------------------------------------ |
-| `clusterConfiguration.KubernetesVersion`        | `Machine.Spec.Version` [1]                                     |
+| `clusterConfiguration.KubernetesVersion`        | `Machine.Spec.Version`                                     |
 | `clusterConfiguration.clusterName`              | `Cluster.metadata.name`                                      |
 | `clusterConfiguration.controlPlaneEndpoint`     | `Cluster.status.apiEndpoints[0]` |
 | `clusterConfiguration.networking.dnsDomain` | `Cluster.spec.clusterNetwork.serviceDomain`              |
@@ -102,9 +99,6 @@ CABPK will fill in some values if they are left empty with sensible defaults:
 
 > IMPORTANT! overriding above defaults could lead to broken Clusters.
 
-[1] if both `clusterConfiguration.KubernetesVersion` and `Machine.Spec.Version` are empty, the latest Kubernetes
-version will be installed (as defined by the default kubeadm behavior). 
-
 #### Examples
 Valid combinations of configuration objects are:
 - at least one of `InitConfiguration` and `ClusterConfiguration` for the first control plane node only
@@ -170,16 +164,105 @@ The user can choose two approaches for certificate management:
 should be provided as a `Secrets` objects in the management cluster.
 2. let CABPK to generate the necessary `Secrets` objects with a self-signed certificate authority for kubeadm
 
-TODO: Add more info about certificate secrets
+See [here](ttps://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/) for more info about certificate management with kubeadm. 
 
 ### Additional Features
-The `KubeadmConfig` object supports customizing the content of the config-data:
+The `KubeadmConfig` object supports customizing the content of the config-data. The following examples illustrate how to specify these options. They should be adapted to fit your environment and use case.
+
+- `KubeadmConfig.Files` specifies additional files to be created on the machine, either with content inline or by referencing a secret.
+
+    ```yaml
+    files:
+    - contentFrom:
+        secret:
+          key: node-cloud.json
+          name: ${CLUSTER_NAME}-md-0-cloud-json
+      owner: root:root
+      path: /etc/kubernetes/cloud.json
+      permissions: "0644"
+    - path: /etc/kubernetes/cloud.json
+      owner: "root:root"
+      permissions: "0644"
+      content: |
+        {
+          "cloud": "CustomCloud"
+        }
+    ```
 
-- `KubeadmConfig.Files` specifies additional files to be created on the machine
 - `KubeadmConfig.PreKubeadmCommands` specifies a list of commands to be executed before `kubeadm init/join`
+
+    ```yaml
+    preKubeadmCommands:
+      - hostname "{{ ds.meta_data.hostname }}"
+      - echo "{{ ds.meta_data.hostname }}" >/etc/hostname
+    ```
+
 - `KubeadmConfig.PostKubeadmCommands` same as above, but after `kubeadm init/join`
+
+    ```yaml
+    postKubeadmCommands:
+      - echo "success" >/var/log/my-custom-file.log
+    ```
+
 - `KubeadmConfig.Users` specifies a list of users to be created on the machine
+
+    ```yaml
+    users:
+      - name: capiuser
+        sshAuthorizedKeys:
+        - '${SSH_AUTHORIZED_KEY}'
+        sudo: ALL=(ALL) NOPASSWD:ALL
+    ```
+
 - `KubeadmConfig.NTP` specifies NTP settings for the machine
+
+  ```yaml
+  ntp:
+    servers:
+      - IP_ADDRESS
+    enabled: true
+  ```
+
 - `KubeadmConfig.DiskSetup` specifies options for the creation of partition tables and file systems on devices.
+
+  ```yaml
+  diskSetup:
+    filesystems:
+    - device: /dev/disk/azure/scsi1/lun0
+      extraOpts:
+      - -E
+      - lazy_itable_init=1,lazy_journal_init=1
+      filesystem: ext4
+      label: etcd_disk
+    - device: ephemeral0.1
+      filesystem: ext4
+      label: ephemeral0
+      replaceFS: ntfs
+    partitions:
+    - device: /dev/disk/azure/scsi1/lun0
+      layout: true
+      overwrite: false
+      tableType: gpt
+  ```
+
 - `KubeadmConfig.Mounts` specifies a list of mount points to be setup.
+
+    ```yaml
+    mounts:
+    - - LABEL=etcd_disk
+      - /var/lib/etcddisk
+    ```
+
 - `KubeadmConfig.Verbosity` specifies the `kubeadm` log level verbosity
+
+    ```yaml
+    verbosity: 10
+    ```
+
+- `KubeadmConfig.UseExperimentalRetryJoin` replaces a basic kubeadm command with a shell script with retries for joins. This will add about 40KB to userdata.
+
+    ```yaml
+    useExperimentalRetryJoin: true
+    ```
+
+For more information on cloud-init options, see [cloud config examples](https://cloudinit.readthedocs.io/en/latest/topics/examples.html).