diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index b73859b1c..b8674bfd1 100644 --- a/docs/book/src/SUMMARY.md +++ b/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) diff --git a/docs/book/src/developer/index.md b/docs/book/src/developer/index.md index 2b3f364a4..5a29d7847 100644 --- a/docs/book/src/developer/index.md +++ b/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) \ No newline at end of file +- [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) \ No newline at end of file diff --git a/docs/book/src/developer/tilt-with-podman.md b/docs/book/src/developer/tilt-with-podman.md deleted file mode 100644 index 91b723d27..000000000 --- a/docs/book/src/developer/tilt-with-podman.md +++ /dev/null @@ -1,41 +0,0 @@ -# Podman setup to use tilt - - -## Prerequisites - -1. Install Podman: Instruction can be found [here](https://podman.io/docs/installation) -2. Emulate docker cli with Podman: Instructions can be found [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman) -3. On `macOS` migrate from Docker to Podman: Instruction 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 -``` -Restart Podman machine - -```shell -podman machine stop -podman machine start -``` - -## 3. Create a kind cluster - -```shell -$ make kind-cluster -``` diff --git a/docs/book/src/developer/tilt.md b/docs/book/src/developer/tilt.md index 0e6455e9c..bf0a411d3 100644 --- a/docs/book/src/developer/tilt.md +++ b/docs/book/src/developer/tilt.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,15 +19,51 @@ 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 @@ -33,7 +71,7 @@ Next, create a `tilt-settings.yaml` file and place it in your local copy of `clu **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 diff --git a/docs/book/src/getting-started.md b/docs/book/src/getting-started.md index 64ac3c40e..9f562a658 100644 --- a/docs/book/src/getting-started.md +++ b/docs/book/src/getting-started.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 diff --git a/docs/book/src/machine-images/index.md b/docs/book/src/machine-images/index.md index 87e11c080..977a48bd7 100644 --- a/docs/book/src/machine-images/index.md +++ b/docs/book/src/machine-images/index.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 \ No newline at end of file +>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) \ No newline at end of file diff --git a/docs/book/src/reference/reference.md b/docs/book/src/reference/reference.md index cf5aa0741..913a3aae0 100644 --- a/docs/book/src/reference/reference.md +++ b/docs/book/src/reference/reference.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) \ No newline at end of file diff --git a/docs/book/src/topics/index.md b/docs/book/src/topics/index.md index 09fd3c7b7..239d3b58b 100644 --- a/docs/book/src/topics/index.md +++ b/docs/book/src/topics/index.md @@ -1,3 +1,6 @@ # Topics -This section contains information about using IBM Cloud features with Cluster API Provider IBM Cloud. \ No newline at end of file +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) \ No newline at end of file diff --git a/docs/book/src/topics/vpc/index.md b/docs/book/src/topics/vpc/index.md index fa5e65cd6..1609fd3ab 100644 --- a/docs/book/src/topics/vpc/index.md +++ b/docs/book/src/topics/vpc/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) \ No newline at end of file