diff --git a/docs/book/src/developer/index.md b/docs/book/src/developer/index.md index 2b0b7f6c2..e259c656c 100644 --- a/docs/book/src/developer/index.md +++ b/docs/book/src/developer/index.md @@ -1 +1,4 @@ # Developer Guide + +- [Rapid iterative development with Tilt](/developer/tilt.html) +- [Release process](/developer/release.html) \ No newline at end of file diff --git a/docs/book/src/getting-started.md b/docs/book/src/getting-started.md index bad55622f..d3492ae94 100644 --- a/docs/book/src/getting-started.md +++ b/docs/book/src/getting-started.md @@ -1 +1,78 @@ # Getting Started + +For prerequisites, check the respective sections for [VPC](topics/vpc/prerequisites.md) and [PowerVS](topics/powervs/prerequisites.md) + +Now that we’ve got all the prerequisites in place, let’s create a Kubernetes cluster and transform +it into a management cluster using `clusterctl`. + +### Provision local boostrap management cluster: + +1. Create simple, local bootstrap cluster with a control-plane and worker node + + Using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/): + + ```console + ~ kind create cluster --name my-bootstrap --config bootstrap.yaml + ``` + + Example bootstrap.yaml: + ```yaml + kind: Cluster + apiVersion: kind.x-k8s.io/v1alpha4 + nodes: + - role: control-plane + - role: worker + ``` + + Make sure the nodes are in `Ready` state before moving on. + + ```console + ~ kubectl get nodes + NAME STATUS ROLES AGE VERSION + my-bootstrap-control-plane Ready control-plane,master 46h v1.20.2 + my-bootstrap-worker Ready 46h v1.20.2 + ``` + +2. Set workload cluster environment variables + + Make sure these value reflects your API Key for your target VPC environment + or PowerVS environment in IBM Cloud. + + ```console + export IBMCLOUD_API_KEY= + ``` + - Additional varibles required for VPC + + The sample `IAM_ENDPOINT` below points to Production and the `SERVICE_ENDPOINT` points to the `us-east` VPC region. + + ```console + export IAM_ENDPOINT=https://iam.cloud.ibm.com/identity/token + export SERVICE_ENDPOINT=https://us-south.iaas.cloud.ibm.com/v1 + ``` + +3. Initialize local bootstrap cluter as a management cluster + + When executed for the first time, the following command accepts the infrasturcture provider as an input to install. `clusterctl init` automatically adds to the list the cluster-api core provider, and if unspecified, it also adds the kubeadm bootstrap and kubeadm control-plane providers, thereby converting it into a management cluster which will be used to provision a workload cluster in IBM Cloud. + + ```console + ~ clusterctl init --infrastructure ibmcloud: + ``` + + Output: + ```console + Fetching providers + Installing cert-manager Version="v1.5.3" + Waiting for cert-manager to be available... + Installing Provider="cluster-api" Version="v0.4.4" TargetNamespace="capi-system" + Installing Provider="bootstrap-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-bootstrap-system" + Installing Provider="control-plane-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-control-plane-system" + Installing Provider="infrastructure-ibmcloud" Version="v0.1.0-alpha.2" TargetNamespace="capi-ibmcloud-system" + + Your management cluster has been initialized successfully! + + You can now create your first workload cluster by running the following: + + clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f - + ``` + +5. 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. \ No newline at end of file diff --git a/docs/book/src/images/ibm-cloud.svg b/docs/book/src/images/ibm-cloud.svg new file mode 100644 index 000000000..5df0216dd --- /dev/null +++ b/docs/book/src/images/ibm-cloud.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md index e10b99d01..7e2e37e99 100644 --- a/docs/book/src/introduction.md +++ b/docs/book/src/introduction.md @@ -1 +1,92 @@ -# Introduction +# Kubernetes Cluster API Provider IBM Cloud + +

+ +IBM Cloud +

+ +------ +

Kubernetes-native declarative infrastructure for IBM Cloud.

+ +## What is the Cluster API Provider IBM Cloud + + +The [Cluster API](https://github.com/kubernetes-sigs/cluster-api) brings declarative, Kubernetes-style APIs to cluster creation, configuration and management. + +The API itself is shared across multiple cloud providers allowing for true IBM Cloud +hybrid deployments of Kubernetes. It is built atop the lessons learned from +previous cluster managers such as [kops](https://github.com/kubernetes/kops) and +[kubicorn](http://kubicorn.io/). + +## Quick Start + +Check out the [getting started](./getting-started.html) section to create your first Kubernetes cluster on IBM Cloud using Cluster API. + +## Tilt-based development environment + +See [developer guide](/developer/tilt.html) section for details. + + +## Documentation + +Please see our [Book](https://cluster-api-ibmcloud.sigs.k8s.io) for in-depth user documentation. + +Additional docs can be found in the `/docs` directory, and the [index is here](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/tree/main/docs). + +## Getting involved and contributing + +Are you interested in contributing to cluster-api-provider-ibmcloud? We, the +maintainers and community, would love your suggestions, contributions, and help! +Also, the maintainers can be contacted at any time to learn more about how to get +involved. + +In the interest of getting more new people involved, we tag issues with +[`good first issue`](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/issues?q=is%3Aissue+label%3A%22good+first+issue%22+is%3Aopen). +These are typically issues that have smaller scope but are good ways to start +to get acquainted with the codebase. + +We also encourage all active community participants to act as if they are +maintainers, even if you don't have "official" write permissions. This is a +community effort, we are here to serve the Kubernetes community. If you have an +active interest and you want to get involved, you have real power! Don't assume +that the only people who can get things done around here are the "maintainers". + +We also would love to add more "official" maintainers, so show us what you can +do! + +This repository uses the Kubernetes bots. See a full list of the commands [here](https://prow.k8s.io/command-help). + +### Join us + +The community holds a weekly meeting every Friday at 09:00 (IST) / 03:30 (UTC) on [Zoom](https://zoom.us/j/9392903494). Subscribe to the [SIG Cluster Lifecycle](https://groups.google.com/g/kubernetes-sig-cluster-lifecycle) Google Group for access to documents and calendars + + +### Other ways to communicate with the contributors + +Please check in with us in the [#cluster-api-ibmcloud](https://kubernetes.slack.com/archives/C02F4CX3ALF) channel on Slack. + +## Github issues + +### Bugs + +If you think you have found a bug please follow the instructions below. + +- Please spend a small amount of time giving due diligence to the issue tracker. Your issue might be a duplicate. +- Get the logs from the cluster controllers. Please paste this into your issue. +- Open a [bug report](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/issues/new?assignees=&labels=&template=bug_report.md). +- Remember users might be searching for your issue in the future, so please give it a meaningful title to helps others. + +### Tracking new features + +We also use the issue tracker to track features. If you have an idea for a feature, or think you can help Cluster API Provider IBMCloud become even more awesome, then follow the steps below. + +- Open a [feature request](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/issues/new?assignees=&labels=&template=feature_request.md). +- Remember users might be searching for your issue in the future, so please + give it a meaningful title to helps others. +- Clearly define the use case, using concrete examples. EG: I type `this` and + cluster-api-provider-ibmcloud does `that`. +- Some of our larger features will require some design. If you would like to + include a technical design for your feature please include it in the issue. +- After the new feature is well understood, and the design agreed upon we can + start coding the feature. We would love for you to code it. So please open + up a **WIP** *(work in progress)* pull request, and happy coding. \ No newline at end of file diff --git a/docs/book/src/topics/index.md b/docs/book/src/topics/index.md index 06310b3b7..09fd3c7b7 100644 --- a/docs/book/src/topics/index.md +++ b/docs/book/src/topics/index.md @@ -1 +1,3 @@ # Topics + +This section contains information about using IBM Cloud features with Cluster API Provider IBM Cloud. \ No newline at end of file diff --git a/docs/book/src/topics/powervs/creating-a-cluster.md b/docs/book/src/topics/powervs/creating-a-cluster.md index 6495e9247..a4d1d4d53 100644 --- a/docs/book/src/topics/powervs/creating-a-cluster.md +++ b/docs/book/src/topics/powervs/creating-a-cluster.md @@ -1,67 +1,9 @@ -# Creating a cluster +### Provision workload cluster in IBM Cloud PowerVS -### Provision local boostrap management cluster: +Now that we have a management cluster ready, you can create your workload cluster by +following the steps below. -1. Create simple, local bootstrap cluster with a control-plane and worker node - - Using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/): - - ```console - ~ kind create cluster --name my-bootstrap --config bootstrap.yaml - ``` - - Example bootstrap.yaml: - ```yaml - kind: Cluster - apiVersion: kind.x-k8s.io/v1alpha4 - nodes: - - role: control-plane - - role: worker - ``` - - Make sure the nodes are in `Ready` state before moving on. - - ```console - ~ kubectl get nodes - NAME STATUS ROLES AGE VERSION - my-bootstrap-control-plane Ready control-plane,master 46h v1.20.2 - my-bootstrap-worker Ready 46h v1.20.2 - ``` - -2. Set workload cluster environment variables - - Make sure these value reflects your API Key for PowerVS environment in IBM Cloud. - - ```console - export IBMCLOUD_API_KEY= - ``` - -3. Initialize local bootstrap cluter as a management cluster - - This cluster will be used to provision a workload cluster in IBM Cloud. - - ```console - ~ clusterctl init --infrastructure ibmcloud: - ``` - - Output: - ```console - Fetching providers - Installing cert-manager Version="v1.5.3" - Waiting for cert-manager to be available... - Installing Provider="cluster-api" Version="v0.4.4" TargetNamespace="capi-system" - Installing Provider="bootstrap-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-bootstrap-system" - Installing Provider="control-plane-kubeadm" Version="v0.4.4" TargetNamespace="capi-kubeadm-control-plane-system" - Installing Provider="infrastructure-ibmcloud" Version="v0.1.0-alpha.2" TargetNamespace="capi-ibmcloud-system" - - Your management cluster has been initialized successfully! - - You can now create your first workload cluster by running the following: - - clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f - - ``` - -4. Create PowerVS network port +1. Create PowerVS network port ```console ~ pvsadm create port --description "capi-port" --network --instance-id @@ -90,9 +32,7 @@ +-------------------+-----------------+-----------------+-------------------+--------------------------------------+--------+ ``` -4. Provision workload cluster in IBM Cloud PowerVS - - You can use clusterctl to render the yaml through templates. +2. Use clusterctl to render the yaml through templates and deploy the cluster **Note:** the `IBMPOWERVS_IMAGE_ID` value below should reflect the ID of the custom qcow2 image, the `kubernetes-version` value below should reflect the kubernetes version of the custom qcow2 image. @@ -122,7 +62,7 @@ kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/ibm-powervs-1-md-0 created ``` -5. Deploy Container Network Interface (CNI) +3. Deploy Container Network Interface (CNI) Example: calico ```console @@ -130,7 +70,7 @@ ``` -6. Check the state of the provisioned cluster and machine objects within the local management cluster +4. Check the state of the provisioned cluster and machine objects within the local management cluster Clusters ```console @@ -154,7 +94,7 @@ ibm-powervs-1-md-0-5444cfcbcd-7kr9x ibmpowervs://ibm-powervs-1/ibm-powervs-1-md-0-k7blr Running v1.22.4 ``` -7. Check the state of the newly provisioned cluster within IBM Cloud +5. Check the state of the newly provisioned cluster within IBM Cloud ```console ~ clusterctl get kubeconfig ibm-powervs-1 > ~/.kube/ibm-powervs-1 diff --git a/docs/book/src/topics/powervs/index.md b/docs/book/src/topics/powervs/index.md index 59f18605d..a58384a81 100644 --- a/docs/book/src/topics/powervs/index.md +++ b/docs/book/src/topics/powervs/index.md @@ -1 +1,5 @@ # Power VS Cluster + +## Contents +- [Prerequisites](/topics/powervs/prerequisites.html) +- [Creating a cluster](/topics/powervs/creating-a-cluster.html) \ No newline at end of file diff --git a/docs/book/src/topics/vpc/creating-a-cluster.md b/docs/book/src/topics/vpc/creating-a-cluster.md index ee56a9c72..0e8742759 100644 --- a/docs/book/src/topics/vpc/creating-a-cluster.md +++ b/docs/book/src/topics/vpc/creating-a-cluster.md @@ -1 +1,79 @@ -# Creating a cluster +### Provision workload Cluster in IBM Cloud VPC + +Now that we have a management cluster ready, you can create your workload cluster by +following the steps below. + +1. Using clusterctl, render the yaml through templates and deploy the cluster + + **Note:** the `IBMVPC_IMAGE_ID` value below should reflect the ID of the custom qcow2 image + + ```console + IBMVPC_REGION=us-south \ + IBMVPC_ZONE=us-south-1 \ + IBMVPC_RESOURCEGROUP=4f15679623607b855b1a27a67f20e1c7 \ + IBMVPC_NAME=ibm-vpc-0 \ + IBMVPC_IMAGE_ID=r134-ea84bbec-7986-4ff5-8489-d9ec34611dd4 \ + IBMVPC_PROFILE=bx2-4x16 \ + IBMVPC_SSHKEY_ID=r134-2a82b725-e570-43d3-8b23-9539e8641944 \ + clusterctl generate cluster ibm-vpc-0 --kubernetes-version v1.19.9 \ + --target-namespace default \ + --control-plane-machine-count=1 \ + --worker-machine-count=2 \ + --from ./templates/cluster-template.yaml | kubectl apply -f - + ``` + + Output: + ```console + cluster.cluster.x-k8s.io/ibm-vpc-5 created + ibmvpccluster.infrastructure.cluster.x-k8s.io/ibm-vpc-5 created + kubeadmcontrolplane.controlplane.cluster.x-k8s.io/ibm-vpc-5-control-plane created + ibmvpcmachinetemplate.infrastructure.cluster.x-k8s.io/ibm-vpc-5-control-plane created + machinedeployment.cluster.x-k8s.io/ibm-vpc-5-md-0 created + ibmvpcmachinetemplate.infrastructure.cluster.x-k8s.io/ibm-vpc-5-md-0 created + kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/ibm-vpc-5-md-0 created + ``` + +2. Deploy Container Network Interface (CNI) + + Example: calico + ```console + kubectl apply -f https://docs.projectcalico.org/v3.15/manifests/calico.yaml + ``` + + +3. Check the state of the provisioned cluster and machine objects within the local management cluster + + Clusters + ```console + ~ kubectl get clusters + NAME PHASE + ibm-vpc-0 Provisioned + ``` + + Kubeadm Control Plane + ```console + ~ kubectl get kubeadmcontrolplane + NAME INITIALIZED API SERVER AVAILABLE VERSION REPLICAS READY UPDATED UNAVAILABLE + ibm-vpc-0-control-plane true true v1.19.9 1 1 1 + ``` + + Machines + ```console + ~ kubectl get machines + ibm-vpc-0-control-plane-vzz47 ibmvpc://ibm-vpc-0/ibm-vpc-0-control-plane-rg6xv Running v1.19.9 + ibm-vpc-0-md-0-5444cfcbcd-6gg5z ibmvpc://ibm-vpc-0/ibm-vpc-0-md-0-dbxb7 Running v1.19.9 + ibm-vpc-0-md-0-5444cfcbcd-7kr9x ibmvpc://ibm-vpc-0/ibm-vpc-0-md-0-k7blr Running v1.19.9 + ``` + +4. Check the state of the newly provisioned cluster within IBM Cloud + + ```console + ~ clusterctl get kubeconfig ibm-vpc-0 > ~/.kube/ibm-vpc-0 + ~ export KUBECONFIG=~/.kube/ibm-vpc-0 + ~ kubectl get nodes + NAME STATUS ROLES AGE VERSION + ibm-vpc-0-control-plane-rg6xv Ready master 41h v1.18.15 + ibm-vpc-0-md-0-4dc5c Ready 41h v1.18.15 + ibm-vpc-0-md-0-dbxb7 Ready 20h v1.18.15 + ``` + diff --git a/docs/book/src/topics/vpc/index.md b/docs/book/src/topics/vpc/index.md index 5969bdebc..85ff7af24 100644 --- a/docs/book/src/topics/vpc/index.md +++ b/docs/book/src/topics/vpc/index.md @@ -1 +1,5 @@ # VPC Cluster + +## Contents +- [Prerequisites](/topics/vpc/prerequisites.html) +- [Creating a cluster](/topics/vpc/creating-a-cluster.html) \ No newline at end of file diff --git a/docs/book/src/topics/vpc/prerequisites.md b/docs/book/src/topics/vpc/prerequisites.md index 6059b9179..da3d43512 100644 --- a/docs/book/src/topics/vpc/prerequisites.md +++ b/docs/book/src/topics/vpc/prerequisites.md @@ -1 +1,19 @@ # Prerequisites + +1. Install `kubectl` (see [here](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-with-curl-on-linux)). Because `kustomize` was included into `kubectl` and it's used by `cluster-api-provider-ibmcloud` in generating yaml files, so version `1.14.0+` of `kubectl` is required, see [integrate kustomize into kubectl](https://github.com/kubernetes/enhancements/issues/633) for more info. +2. You can use either VM, container or existing Kubernetes cluster act as the bootstrap cluster. + - If you want to use container, install [kind](https://github.com/kubernetes-sigs/kind#installation-and-usage). This is preferred. + - If you want to use VM, install [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/), version 0.30.0 or greater. + - If you want to use existing Kubernetes cluster, prepare your kubeconfig. +3. Install a [driver](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md) **if you are using minikube**. For Linux, we recommend kvm2. For MacOS, we recommend VirtualBox. +4. An appropriately configured [Go development environment](https://golang.org/doc/install) +5. Install `clusterctl` tool (see [here](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl)) + +### Build workload cluster image: + +1. Build a qcow2 image suitable for use as a Kubernetes cluster machine as detailed in the image builder [book](https://image-builder.sigs.k8s.io/capi/providers/raw.html). + + **Note:** Rename the output image to add the `.qcow2` extension. This is required by the next step. + + +2. Create a VPC Gen2 custom image based on the qcow2 image built in the previous step as detailed in the VPC [documentation](https://cloud.ibm.com/docs/vpc?topic=vpc-planning-custom-images).