(chore) : improving documentation

Signed-off-by: Archisman <[email protected]>

Author: Archisman-Mridha

README.md

@@ -20,13 +20,31 @@ In a separate terminal window, use `make exec-container-dev` to execute into the
 
 Once you're inside the container, use `make generate-sample-config-aws-dev` to generate a sample config file at [./outputs/kubeaid-bootstrap-script.config.yaml](./outputs/kubeaid-bootstrap-script.config.yaml), targetting the AWS cloud provider. Adjust the config file according to your needs.
 
-Export your AWS credentials as environment variables and then run `make bootstrap-cluster-dev` to bootstrap the cluster!
+Export your AWS credentials as environment variables like such :
 
-### Debugging
+```sh
+export AWS_REGION=""
+export AWS_ACCESS_KEY_ID=""
+export AWS_SECRET_ACCESS_KEY=""
+export AWS_SESSION_TOKEN=""
+```
 
-- Check ClusterAPI related pod logs.
+Then run `make bootstrap-cluster-dev-aws` to bootstrap the cluster!
 
-- SSH into the control-plane node. In case of AWS, you can view cloud-init logs stored at `/var/log/cloud-init-output.log`.
+> [!NOTE]
+> If the `clusterawsadm bootstrap iam create-cloudformation-stack` command errors out with this message :
+>
+>     	the IAM CloudFormation Stack create / update failed and it's currently in a `ROLLBACK_COMPLETE` state
+>
+> then that means maybe there are pre-existing IAM resources with overlapping name. Then first delete them manually from the AWS Console and then retry running the script. Filter the IAM roles and policies in the corresponding region with the keyword : `cluster` / `clusterapi`.
+
+If cluster provisioning gets stuck, then debug by :
+
+- checking logs of ClusterAPI related pod.
+
+- SSHing into the control-plane node. You can view cloud-init output logs stored at `/var/log/cloud-init-output.log`.
+
+If you want to delete the provisioned cluster, then execute : `make delete-provisioned-cluster-dev-aws`.
 
 ## TODOs
 

cmd/kubeaid-bootstrap-script/cluster/bootstrap/aws.go

@@ -8,7 +8,8 @@ import (
 )
 
 var AWSCmd = &cobra.Command{
-	Use: "aws",
+	Use:   "aws",
+	Short: "Bootstrap a self-managed Kubernetes cluster in AWS",
 	Run: func(cmd *cobra.Command, args []string) {
 		core.BootstrapCluster(cmd.Context(), skipKubeAidConfigSetup, skipClusterctlMove, aws.NewAWSCloudProvider(), false)
 	},

cmd/kubeaid-bootstrap-script/cluster/bootstrap/hetzner.go

@@ -8,7 +8,8 @@ import (
 )
 
 var HetznerCmd = &cobra.Command{
-	Use: "hetzner",
+	Use:   "hetzner",
+	Short: "Bootstrap a self-managed Kubernetes cluster in Hetzner (bare-metal)",
 	Run: func(cmd *cobra.Command, args []string) {
 		core.BootstrapCluster(cmd.Context(), skipKubeAidConfigSetup, skipClusterctlMove, hetzner.NewHetznerCloudProvider(), false)
 	},

cmd/kubeaid-bootstrap-script/cluster/delete/delete.go

@@ -6,7 +6,8 @@ import (
 )
 
 var DeleteCmd = &cobra.Command{
-	Use: "delete",
+	Use:   "delete",
+	Short: "Delete a provisioned cluster",
 	Run: func(cmd *cobra.Command, args []string) {
 		core.DeleteCluster(cmd.Context())
 	},

config/config.go

@@ -37,6 +37,14 @@ type (
 		APIServer APIServerConfig `yaml:"apiServer"`
 	}
 
+	// REFER : https://github.com/kubernetes-sigs/cluster-api/blob/main/controlplane/kubeadm/config/crd/bases/controlplane.cluster.x-k8s.io_kubeadmcontrolplanes.yaml.
+	//
+	// NOTE : Generally, refer to the KubeadmControlPlane CRD instead of the corresponding GoLang
+	//        source types linked below.
+	//        There are some configuration options which appear in the corresponding GoLang source type,
+	//        but not in the CRD. If you set those fields, then they get removed by the Kubeadm
+	//        control-plane provider. This causes the capi-cluster ArgoCD App to always be in an
+	//        OutOfSync state, resulting to the KubeAid Bootstrap Script not making any progress!
 	APIServerConfig struct {
 		ExtraArgs    map[string]string     `yaml:"extraArgs" default:"{}"`
 		ExtraVolumes []HostPathMountConfig `yaml:"extraVolumes" default:"[]"`
@@ -54,7 +62,7 @@ type (
 		// Defaults to true.
 		//
 		// NOTE : If you want the mount to be read-only, then set this true.
-		//        Otherwise, omit setting this field. It gets removed by the kubeadm control-plane
+		//        Otherwise, omit setting this field. It gets removed by the Kubeadm control-plane
 		//        provider component, which results to the capi-cluster ArgoCD App always being in
 		//        OutOfSync state.
 		ReadOnly bool `yaml:"readOnly,omitempty"`

config/files/templates/aws.sample.config.yaml.tmpl

@@ -1,50 +1,111 @@
-forks:
-  kubeaidConfig: https://github.com/xxxxxxxxxx/kubeaid-config
-
+# Git credentials used to authenticate against the Git platform you're using (Github / Gitlab etc.).
+# KubeAid Bootstrap Script will use these credentials to :
+#
+#   (1) Clone the KubeAid and KubeAid config repositories.
+#   (2) Create and push commits to a branch in the KubeAid config repository.
+#
+# So, make sure the Git password (token) you're using has permissions associated to do the above.
+#
+# Currently, we only support HTTPS authentication.
 git:
   username: xxxxxxxxxx
   password: xxxxxxxxxx
 
+forks:
+  # KubeAid repository URL (in HTTPs syntax).
+  # Defaults to Obmondo's KubeAid repository.
+  # kubeaid: https://github.com/Obmondo/KubeAid
+
+  # Your KubeAid config repository URL (in HTTPs syntax).
+  kubeaidConfig: https://github.com/xxxxxxxxxx/kubeaid-config
+
+# Kubernetes cluster and control-plane specific configurations.
 cluster:
+
+  # Kubernetes cluster name.
   name: kubeaid-demo-aws
+
+  # Kubernetes version to use.
+  # NOTE : Make sure that the AMI you're using, is targetted towards this Kubernetes version.
   k8sVersion: v1.31.0
 
+  # Kubernetes API server specific configurations.
+  # REFER : https://github.com/kubernetes-sigs/cluster-api/blob/main/controlplane/kubeadm/config/crd/bases/controlplane.cluster.x-k8s.io_kubeadmcontrolplanes.yaml.
+  #  
+  # NOTE : Generally, refer to the KubeadmControlPlane CRD instead of the corresponding GoLang
+  #        source types linked below.
+  #        There are some configuration options which appear in the corresponding GoLang source type,
+  #        but not in the CRD. If you set those fields, then they get removed by the Kubeadm
+  #        control-plane provider. This causes the capi-cluster ArgoCD App to always be in an
+  #        OutOfSync state, resulting to the KubeAid Bootstrap Script not making any progress!
+  # apiServer:
+  #
+  #   extraArgs: {}
+  #
+  #   # REFER : "sigs.k8s.io/cluster-api/bootstrap/kubeadm/api/v1beta1".HostPathMount
+  #   #
+  #   # NOTE : If you want a mount to be read-only, then set extraVolume.readOnly to true.
+  #   #        Otherwise, omit setting that field. It gets removed by the Kubeadm control-plane
+  #   #        provider component, which results to the capi-cluster ArgoCD App always being in
+  #   #        OutOfSync state.
+  #   extraVolumes: []
+  #
+  #   # REFER : "sigs.k8s.io/cluster-api/bootstrap/kubeadm/api/v1beta1".File
+  #   files: []
+
+  # Uncomment, if you just want audit-logging to be setup for you! KubeAid Bootstrap Script will set
+  # necessary configuration options in cluster.apiServer.
+  # enableAuditLogging: True
+
 cloud:
+  # AWS specific configurations.
   aws:
-		region: us-east-1
+    region: us-east-1
 
+    # AWS SSH Keypair name, which ClusterAPI components (Kubeadm bootstrap and control-plane
+    # providers specifically) will use to SSH into the main cluster's master nodes.
     sshKeyName: kubeaid-demo
 
-		bastionEnabled: False
+    # bastionEnabled: True
 
     controlPlane:
-			instanceType: t4g.medium
-    	ami:
-				id: ami-xxxxxxxxxxxxxxxxx
-    	replicas: 1
+      ami:
+        id: ami-xxxxxxxxxxxxxxxxx
+      instanceType: t4g.medium
+      replicas: 1
 
     nodeGroups:
       - name: primary
         ami:
-					id: ami-xxxxxxxxxxxxxxxxx
+          id: ami-xxxxxxxxxxxxxxxxx
         instanceType: t4g.medium
+
+        minSize: 0
         replicas: 1
+        maxSize: 3
+
         rootVolumeSize: 35
+
+        # AWS SSH Keypair name, which ClusterAPI components (Kubeadm bootstrap provider
+        # specifically) will use to SSH into each node belonging to this node-group.
         sshKeyName: kubeaid-demo
 
-				# Label should meet one of the following criterias to propagate to Node :
-				#
-				# (1) Has node-role.kubernetes.io as prefix.
-				# (2) Belongs to node-restriction.kubernetes.io domain.
-				# (3) Belongs to node.cluster.x-k8s.io domain.
-				#
-				# REFER : https://cluster-api.sigs.k8s.io/developer/architecture/controllers/metadata-propagation#machine
-				labels:
-					node.cluster.x-k8s.io/nodegroup: primary
+        # A label should meet one of the following criterias to propagate to each of the nodes :
+        #
+        # (1) Has node-role.kubernetes.io as prefix.
+        # (2) Belongs to node-restriction.kubernetes.io domain.
+        # (3) Belongs to node.cluster.x-k8s.io domain.
+        #
+        # REFER : https://cluster-api.sigs.k8s.io/developer/architecture/controllers/metadata-propagation#machine
+        labels:
+          node.cluster.x-k8s.io/nodegroup: primary
           node-role.kubernetes.io/bootstrapper: ""
 
-        taints: []
+        # taints: []
 
-		disasterRecovery:
-			veleroBackupsS3BucketName: kubeaid-demo-kubernetes-objects
+    disasterRecovery:
+      veleroBackupsS3BucketName: kubeaid-demo-kubernetes-objects
       sealedSecretsBackupS3BucketName: kubeaid-demo-sealed-secrets
+
+# monitoring:
+#   kubePrometheusVersion: v0.14.0