Streamline documentation for CAPIBM (#1508)

Author: kishen-v

docs/book/src/SUMMARY.md

@@ -28,7 +28,6 @@
     - [Image Commands](./topics/capibmadm/vpc/image.md)
     - [Key Commands](./topics/capibmadm/vpc/key.md)
 - [Developer Guide](./developer/index.md)
-  - [Podman setup for tilt](./developer/tilt-with-podman.md)
   - [Rapid iterative development with Tilt](./developer/tilt.md)
   - [Guide for API conversions](./developer/conversion.md)
   - [Release Process](./developer/release.md)

docs/book/src/developer/index.md

@@ -2,5 +2,7 @@
 
 - [Rapid iterative development with Tilt](/developer/tilt.html)
 - [Guide for API conversions](/developer/conversion.html)
-- [Release process](/developer/release.html)
-- [How to build machine boot images](/developer/build-images.html)
+- [Release Process](/developer/release.html)
+- [How to build the machine boot images](/developer/build-images.html)
+- [Modules and tools dependencies](/developer/dependencies.html)
+- [E2E testing](/developer/e2e.html)

docs/book/src/developer/tilt-with-podman.md

@@ -6,7 +6,9 @@ This document describes how to use [kind](https://kind.sigs.k8s.io) and [Tilt](h
 
 ## Prerequisites
 
-1. [Docker](https://docs.docker.com/install/) v19.03 or newer
+1. Container Runtime Interface
+    * [Docker](https://docs.docker.com/install/)    - v19.03 or newer
+    * [Podman](https://podman.io/docs/installation) - v3.0 or newer
 2. [kind](https://kind.sigs.k8s.io) v0.9 or newer (other clusters can be
    used if `preload_images_for_kind` is set to false)
 3. [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/)
@@ -17,23 +19,59 @@ This document describes how to use [kind](https://kind.sigs.k8s.io) and [Tilt](h
    locally
 7. Clone the [cluster-api-provider-ibmcloud](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud) repository you want to deploy locally as well
 
+---
+If the user prefers to have Podman as the CRI, then follow the steps listed below:
+
+1. Emulate Docker CLI with Podman: Instructions can be found [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman)
+2. On `Mac OS` migrate from Docker to Podman: Instructions can be found
+ [here](https://podman-desktop.io/docs/migrating-from-docker/using-podman-mac-helper).
+
+### 1. Create Podman machine
+
+```shell
+$ podman machine init
+$ podman machine start
+```
+
+### 2. Configure podman to use local registry
+
+```shell
+$ podman machine ssh
+$ sudo vi /etc/containers/registries.conf
+
+## at the end of the file add below content
+
+[[registry]]
+location = "localhost:5001"
+insecure = true
+```
+### 3. Restart Podman machine
+
+```shell
+podman machine stop
+podman machine start
+```
+---
+
 ## Create a kind cluster
 
 First, make sure you have a kind cluster and that your `KUBECONFIG` is set up correctly:
 
 ``` bash
-kind create cluster
+make kind-cluster
 ```
 
-This local cluster will be running all the cluster api controllers and become the management cluster which then can be used to spin up workload clusters on IBM Cloud.
+This local cluster will host the cluster-api controllers, which makes it the management cluster. The management cluster can be used to create and manage workload clusters on IBM Cloud.
+
+---
 
 ## Create a tilt-settings.yaml file
 
 Next, create a `tilt-settings.yaml` file and place it in your local copy of `cluster-api`. Here is an example:
 
 **Example `tilt-settings.yaml` for CAPI-IBM clusters:**
 
-Make sure to replace the parameter `IBMCLOUD_API_KEY` with a valid API key.
+Make sure to set a valid API key for the field `IBMCLOUD_API_KEY`.
 
 ```yaml
 default_registry: "gcr.io/you-project-name-here"
@@ -54,30 +92,16 @@ extra_args:
   ibmcloud:
     - '-v=5'
 ```
+---
+## Different flavors of deploying workload clusters using CAPIBM.
 
-### 1.  Configuration to deploy PowerVS workload cluster with external cloud controller manager
-
-To deploy workload cluster with [PowerVS cloud controller manager](/topics/powervs/external-cloud-provider.html) which is currently in experimental stage, Set `PROVIDER_ID_FORMAT` to `v2` and enable cluster resourceset feature gate under kustomize_substitutions.
-Currently, [ClusterResourceset](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-resource-set.html) is experimental feature so we need to enable the feature gate by setting `EXP_CLUSTER_RESOURCE_SET` variable under kustomize_substitutions.
+> **Note:** Currently, both [ClusterClass](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/index.html) and [ClusterResourceset](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-resource-set.html) are experimental features.
 
-```yaml
-default_registry: "gcr.io/you-project-name-here"
-provider_repos:
-- ../cluster-api-provider-ibmcloud
-enable_providers:
-- ibmcloud
-- kubeadm-bootstrap
-- kubeadm-control-plane
-kustomize_substitutions:
-  IBMCLOUD_API_KEY: "XXXXXXXXXXXXXXXXXX"
-  PROVIDER_ID_FORMAT: "v2"
-  EXP_CLUSTER_RESOURCE_SET: "true"
-```
+### 1.  Configuration to deploy PowerVS workload cluster with external cloud controller manager
 
-### 2.  Configuration to deploy VPC workload cluster with external cloud controller manager
+To deploy workload cluster with [PowerVS cloud controller manager](/topics/powervs/external-cloud-provider.html)(experimental) or to deploy workload cluster with [cloud controller manager](/topics/vpc/load-balancer.html)(experimental), set `PROVIDER_ID_FORMAT` to `v2` and enable cluster resourceset feature gate under kustomize_substitutions.
 
-To deploy workload cluster with [cloud controller manager](/topics/vpc/load-balancer.html) which is currently in experimental stage, Set `PROVIDER_ID_FORMAT` to `v2` and enable cluster resourceset feature gate under kustomize_substitutions.
-Currently, [ClusterResourceset](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-resource-set.html) is experimental feature so we need to enable the feature gate by setting `EXP_CLUSTER_RESOURCE_SET` variable under kustomize_substitutions.
+This requires setting the feature gate `EXP_CLUSTER_RESOURCE_SET` to `true` under kustomize_substitutions.
 
 ```yaml
 default_registry: "gcr.io/you-project-name-here"
@@ -93,10 +117,11 @@ kustomize_substitutions:
   EXP_CLUSTER_RESOURCE_SET: "true"
 ```
 
-### 3.  Configuration to deploy workload cluster from ClusterClass template
+### 2.  Configuration to deploy workload cluster from ClusterClass template
+
+To deploy workload cluster with [clusterclass-template](/topics/powervs/clusterclass-cluster.html), set the `PROVIDER_ID_FORMAT` to `v2` under kustomize_substitutions.
 
-To deploy workload cluster with [clusterclass-template](/topics/powervs/clusterclass-cluster.html) under kustomize_substitutions set `PROVIDER_ID_FORMAT` to `v2`.
-Currently, both [ClusterClass](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/index.html) and [ClusterResourceset](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-resource-set.html) are experimental feature so we need to enable the feature gate by setting `EXP_CLUSTER_RESOURCE_SET`, `CLUSTER_TOPOLOGY` variable under kustomize_substitutions.
+This requires setting the feature gates `EXP_CLUSTER_RESOURCE_SET` and `CLUSTER_TOPOLOGY` to `true` under kustomize_substitutions.
 
 ```yaml
 default_registry: "gcr.io/you-project-name-here"
@@ -113,7 +138,7 @@ kustomize_substitutions:
   CLUSTER_TOPOLOGY: "true"
 ```
 
-### 4.  Configuration to deploy workload cluster with Custom Service Endpoint
+### 3.  Configuration to deploy workload cluster with Custom Service Endpoint
 
 To deploy workload cluster with Custom Service Endpoint, Set `SERVICE_ENDPOINT` environmental variable in semi-colon separated format: `${ServiceRegion}:${ServiceID1}=${URL1},${ServiceID2}=${URL2...}`
 ```yaml

docs/book/src/developer/tilt.md

@@ -88,22 +88,18 @@ it into a management cluster using `clusterctl`.
 
 6. Once the management cluster is ready with the required providers up and running, proceed to provisioning the workload cluster. Check the respective sections for [VPC](/topics/vpc/creating-a-cluster.html) and [PowerVS](/topics/powervs/creating-a-cluster.html) to deploy the cluster. 
 
-7. For deploying with your workload cluster with Cloud Controller manager or Cluster Class template, refer to [deploy with cloud controller manager](#deploy-with-cloud-contoller-manager) and [deploy PowerVS cluster with cluster class template](#deploy-powervs-cluster-with-clusterclass-template) sections respectively.
+7. For deploying with your workload cluster with Cloud Controller manager or Cluster Class template, refer to [deploy with cloud controller manager](#deploy-with-cloud-controller-manager) and [deploy PowerVS cluster with cluster class template](#deploy-powervs-cluster-with-clusterclass-template) sections respectively.
 
 
-### Deploy with Cloud Contoller manager
+### Deploy with Cloud Controller manager
 
-   1. To deploy VPC workload cluster with [IBM cloud controller manager](/topics/vpc/load-balancer.html), set the `PROVIDER_ID_FORMAT` environmental variable.
-      ```console
-      export PROVIDER_ID_FORMAT=v2
-      export EXP_CLUSTER_RESOURCE_SET=true
-      ```
+   To deploy VPC workload cluster with [IBM cloud controller manager](/topics/vpc/load-balancer.html), or with [PowerVS cloud controller manager](/topics/powervs/external-cloud-provider.html), set the `PROVIDER_ID_FORMAT` environmental variable to `v2`.
 
-   2. To deploy workload cluster with [PowerVS cloud controller manager](/topics/powervs/external-cloud-provider.html), set the `PROVIDER_ID_FORMAT` environmental variable.
-      ```console
+   ```console
       export PROVIDER_ID_FORMAT=v2
       export EXP_CLUSTER_RESOURCE_SET=true
-      ```
+   ```
+
    > Note: `EXP_CLUSTER_RESOURCE_SET` should be set for deploying workload cluster with Cloud Controller manager.
 
 ### Deploy PowerVS cluster or VPC cluster with ClusterClass template

docs/book/src/getting-started.md

@@ -4,4 +4,7 @@ CAPIBM requires a “machine image” containing pre-installed, matching version
 
 Pre-built public Images are published by the maintainers regularly for each new Kubernetes version.
 
->Note: These images are only for the test purpose
+>Note: These images are only for the test purpose
+
+- [IBM Cloud VPC Images](/machine-images/vpc.html)
+- [IBM Cloud PowerVS Images](/machine-images/powervs.html)

docs/book/src/machine-images/index.md

@@ -1 +1,6 @@
 # Reference
+
+Further references to the Cluster API Provider IBM Cloud - CAPIBM project.
+
+- [API reference](/reference/api-references.html)
+- [Regions-Zones Mapping](/reference/regions-zones-mapping.html)

docs/book/src/reference/reference.md

@@ -1,3 +1,6 @@
 # Topics
 
-This section contains information about using IBM Cloud features with Cluster API Provider IBM Cloud.
+This section contains information about using IBM Cloud features with Cluster API Provider IBM Cloud.
+
+- [IBM Cloud VPC Cluster](/topics/vpc/index.html)
+- [IBM Cloud PowerVS Cluster](/topics/powervs/index.html)   

docs/book/src/topics/index.md

@@ -4,4 +4,5 @@
 - [Prerequisites](/topics/vpc/prerequisites.html)
 - [Uploading an image](/topics/vpc/uploading-an-image.html)
 - [Creating a cluster](/topics/vpc/creating-a-cluster.html)
-- [Creating a cluster from ClusterClass](/topics/vpc/clusterclass-cluster.md)
+- [Creating a cluster with Load Balancer and external cloud provider](/topics/vpc/load-balancer.md)
+- [Creating a cluster from ClusterClass](/topics/vpc/clusterclass-cluster.md)