Updated docs for cloud-init (#554)

* docs: provided detailed cloud-init instructions

Signed-off-by: sandeep <sandeep0814@gmail.com>

Author: hyder

README.adoc

@@ -37,6 +37,7 @@
 :uri-terraform-hashircorp-examples: https://github.com/hashicorp/terraform-guides/tree/master/infrastructure-as-code/terraform-0.12-examples
 :uri-topology: {uri-docs}/topology.adoc
 :uri-upgrade: {uri-docs}/upgrade.adoc
+:uri-cloudinit: {uri-docs}/cloudinit.adoc
 
 {uri-oke}[Oracle Container Engine] (OKE) is {uri-oracle}[Oracle]'s managed {uri-kubernetes}[Kubernetes] service on {uri-oci}[Oracle Cloud Infrastructure (OCI)].
 
@@ -54,6 +55,8 @@ This {uri-repo}[Terraform OKE Installer] for {uri-oci}[Oracle Cloud Infrastructu
 
 * {uri-topology}[Topology]
 
+* {uri-cloudinit}[Configuring cloud-init]
+
 * {uri-terraform-options}[Terraform Options]
 
 * {uri-upgrade}[Upgrading OKE]

docs/cloudinit.adoc

@@ -2,37 +2,59 @@
 :idprefix:
 :idseparator: -
 :sectlinks:
-:sectnums:
 :toc: auto
 
 :uri-cloudinit: https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengusingcustomcloudinitscripts.htm
+:uri-source-cloudinit-doc: https://github.com/oracle-terraform-modules/terraform-oci-oke/blob/main/docs/instructions.adoc#configuring-cloud-init-for-the-nodepools
+:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-oke
+:uri-worker-script: link:{uri-repo}/modules/oke/cloudinit/worker.template.sh
 
-== Instructions:
 
-* {uri-cloudinit}[Using cloud-init in OKE] 
-* The default cloud-init script used by this module is as below:
-----
-#!/bin/bash
+== Configuring cloud-init scripts for node pools:
+There are 2 types of cloud-init scripts that can be configured for node pools:
 
-# DO NOT MODIFY
-curl --fail -H "Authorization: Bearer Oracle" -L0 http://169.254.169.254/opc/v2/instance/metadata/oke_init_script | base64 --decode >/var/run/oke-init.sh
+. Common: these are cloud-init scripts that are common to all node pools
+. Node pool specific: these are cloud-init scripts that are specific to particular node pools.
 
-## run oke provisioning script
-bash -x /var/run/oke-init.sh
+=== Default cloud-init
 
-### adjust block volume size
-/usr/libexec/oci-growfs -y
+By default, the {uri-worker-script}[worker template] is used. The default worker template runs `oci-growfs` and `timedatectl` to configure the boot volume size and timezone respectively. 
 
-timedatectl set-timezone ${worker_timezone}
-----
+=== Script precedence
+
+If no value is configured for `cloudinit_nodepool_common` or for `cloudinit_nodepool`, this default template is used.
+
+If a value is configured for `cloudinit_nodepool_common`, then this value is used instead. 
+
+If a value is configured for `cloudinit_nodepool`, then this value is used for the specific nodepool only instead. Other nodepools will utilize whatever script is common.
+
+The flowchart below depicts the script selection workflow:
+
+.cloud-init script selection
+image::images/cloud-init-flowchart.png[align="cloud-init script selection"]
 
-* To customize this you can modify the above script and pass the script as input variable to `cloudinit_nodepool_common`. This script will be used across all the nodepools.
 
-* To use specific cloud-init script for a nodepool pass the script as input variable to `cloudinit_nodepool` as a map.This will take precedence over `cloudinit_nodepool_common` for that nodepool.
-Ex: cloudinit_nodepool        = {
-  #np1 = "/tmp/np1cloudinit.sh"
-  #np3 = "/tmp/np3cloudinit.sh"
-#}
+== Overriding default cloud-init
 
+=== Overriding the common cloud-init
+
+The common cloud-init script for all node pools can be overriden as follows:
+
+```
+cloudinit_nodepool_common = "/tmp/cloudinit_nodepool_common.sh"
+```
+
+=== Specifying a cloud-init script for specific node pools
+
+Sometimes, it may be desirable to configure additional settings for specific node pools without affecting the behaviour of existing or other node pools. In this case, you can override cloud-init as follows:
+
+----
+cloudinit_nodepool        = {
+  np1 = "/tmp/np1_cloud-init.sh"
+  np3 = "/tmp/np3_cloud-init.sh"
+}
+----
 
+In the above example, node pool `np1` and `np3` will use `/tmp/np1_cloud-init.sh` and `/tmp/np3_cloud-init.sh` respectively for their cloud-init. 
 
+NOTE: You must ensure that the node pool name specified for cloud-init matches those you defined in the `node_pools` variable. 

docs/configuration.adoc

@@ -42,6 +42,7 @@
 :uri-terraform-oke-sample: https://github.com/terraform-providers/terraform-provider-oci/tree/master/examples/container_engine
 :uri-terraform-options: {uri-docs}/terraformoptions.adoc
 :uri-topology: {uri-docs}/topology.adoc
+:uri-cloudinit: {uri-docs}/cloudinit.adoc
 
 == Assumptions
 
@@ -207,6 +208,8 @@ The OKE Node Pool parameters control the following:
 
 An empty value for boot volume size will default the boot volume to 50GB. This value is updatable. However the effect will be effective in newly created nodes _only_.
 
+Refer to {uri-cloudinit}[cloudinit] for specifying how to configure cloud-init scripts for nodepools.
+
 Refer to {uri-topology}[topology] for more thorough examples.
 
 == Configure OKE Load Balancer parameters

docs/images/cloud-init-flowchart.png

@@ -286,82 +286,6 @@ Scaling changes to the number and size of node pools are immediate after changin
 
 Set the parameter *node_pools* to the desired quantities to scale the node pools accordingly. Refer to {uri-topology}#node-pools[Nodepool].
 
-== Configuring cloud-init for the nodepools
-
-To install additional packages, configure settings or execute certain extra commands on node pools, you can use cloud-init to do that for you.
-
-By default, there is a `worker.template.sh` file under the cloudinit directory in the `oke` module. Follow the following steps to add your own:
-
-. Add your own script in the cloudinit directory. An example is provided by `second.template.sh`. If you need to parameterize the script, enclose the parameter within `${}`. For example:
-
-+
-----
-yum install -y package-${version}
-----
-
-
-. Declare your script as a template in the cloudinit.tf in the locals section. A corresponding example for the `second.template.sh` is provided. 
-
-+
-If you do *_not_* need to pass a parameter to the script, leave the 2^nd^ argument to the template file function as empty:
-
-+
-----
-second_script_template = templatefile("${path.module}/cloudinit/second.template.sh",{})
-----
-
-+
-Otherwise, pass a parameter to the template script as follows:
-
-+
-----
-  second_script_template = templatefile("${path.module}/cloudinit/second.template.sh",
-    {
-      version = "5.4.0"
-    }
-  )
-----
-
-. Add the part in the `cloudinit_config worker` section:
-
-+  
-----
-part {
-  filename     = "second.sh"
-  content_type = "text/x-shellscript"
-  content      = local.second_script_template
-}
-----
-
-. You can add more scripts and have them loaded in the order you need. For example:
-
-+
-----
-data "cloudinit_config" "worker" {
-  gzip          = false
-  base64_encode = true
-
-  part {
-    filename     = "worker.sh"
-    content_type = "text/x-shellscript"
-    content      = local.worker_script_template
-  }
-  
-  part {
-    filename     = "second.sh"
-    content_type = "text/x-shellscript"
-    content      = local.second_script_template
-  }
-
-  part {
-    filename     = "third.sh"
-    content_type = "text/x-shellscript"
-    content      = local.third_script_template
-  }
-}
-----
-
-
 == Accessing the Kubernetes dashboard
 
 By default, the Kubernetes dashboard is now disabled. To enable it, set the *dashboard_enabled = true* _before_ creating the cluster. The dashboard will then be deployed.