From d46cff76356136219a424478281b9a1229f3d0bb Mon Sep 17 00:00:00 2001 From: Prajyot Parab Date: Tue, 30 Nov 2021 15:02:56 +0530 Subject: [PATCH] Update Readme docs (#435) Signed-off-by: Prajyot-Parab --- README.md | 2 +- .../src/topics/powervs/creating-a-cluster.md | 166 ++++++++++++++++++ docs/book/src/topics/powervs/prerequisites.md | 59 +++++++ templates/README.md | 4 +- 4 files changed, 228 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8cee7c910..ea4920edf 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ The [Cluster API](https://github.com/kubernetes-sigs/cluster-api) brings declara IBMVPC_IMAGE_ID=r134-ea84bbec-7986-4ff5-8489-d9ec34611dd4 \ IBMVPC_PROFILE=bx2-4x16 \ IBMVPC_SSHKEY_ID=r134-2a82b725-e570-43d3-8b23-9539e8641944 \ - clusterctl config cluster ibm-vpc-0 --kubernetes-version v1.19.9 \ + clusterctl generate cluster ibm-vpc-0 --kubernetes-version v1.19.9 \ --target-namespace default \ --control-plane-machine-count=1 \ --worker-machine-count=2 \ diff --git a/docs/book/src/topics/powervs/creating-a-cluster.md b/docs/book/src/topics/powervs/creating-a-cluster.md index ee56a9c72..0dfe86e38 100644 --- a/docs/book/src/topics/powervs/creating-a-cluster.md +++ b/docs/book/src/topics/powervs/creating-a-cluster.md @@ -1 +1,167 @@ # Creating a cluster + +### 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 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 + + ```console + ~ pvsadm create port --description "capi-port" --network --instance-id + ``` + + Output: + ```console + I1125 15:24:20.581757 1548881 port.go:89] Successfully created a port, id: ac18ef17-8517-40e3-889d-4f246e9bd17e + +---------------------+------------+------+-----------------+-------------------+--------------------------------------+-------------+--------+ + | DESCRIPTION | EXTERNALIP | HREF | IPADDRESS | MACADDRESS | PORTID | PVMINSTANCE | STATUS | + +---------------------+------------+------+-----------------+-------------------+--------------------------------------+-------------+--------+ + | capi-port | | | 192.168.151.125 | fa:16:3e:34:2c:ef | 7eff02b5-040c-4934-957a-18209e65eca4 | | DOWN | + +---------------------+------------+------+-----------------+-------------------+--------------------------------------+-------------+--------+ + ``` + + ```console + ~ pvsadm get ports --instance-id --network + ``` + + Output: + ```console + +-------------------+-----------------+-----------------+-------------------+--------------------------------------+--------+ + | DESCRIPTION | EXTERNALIP | IPADDRESS | MACADDRESS | PORTID | STATUS | + +-------------------+-----------------+-----------------+-------------------+--------------------------------------+--------+ + | capi-port | 158.175.162.125 | 192.168.151.125 | fa:16:3e:34:2c:ef | 7eff02b5-040c-4934-957a-18209e65eca4 | DOWN | + +-------------------+-----------------+-----------------+-------------------+--------------------------------------+--------+ + ``` + +4. Provision workload cluster in IBM Cloud PowerVS + + You can use clusterctl to render the yaml through templates. + + **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. + + ```console + IBMPOWERVS_SSHKEY_NAME="my-pub-key" \ + IBMPOWERVS_VIP="192.168.151.22" \ + IBMPOWERVS_VIP_EXTERNAL="158.175.162.22" \ + IBMPOWERVS_VIP_CIDR="29" \ + IBMPOWERVS_IMAGE_ID="505f57d8-1143-4a99-b67f-7e82d73342bf" \ + IBMPOWERVS_SERVICE_INSTANCE_ID="7845d372-d4e1-46b8-91fc-41051c984601" \ + IBMPOWERVS_NETWORK_ID="0ad342f5-f461-414a-a870-e2f2a2b7fa0c" \ + clusterctl generate cluster ibm-powervs-1 --kubernetes-version v1.22.4 \ + --target-namespace default \ + --control-plane-machine-count=3 \ + --worker-machine-count=1 \ + --from ./cluster-template-powervs.yaml | kubectl apply -f - + ``` + + Output: + ```console + cluster.cluster.x-k8s.io/ibm-powervs-1 created + ibmpowervscluster.infrastructure.cluster.x-k8s.io/ibm-powervs-1 created + kubeadmcontrolplane.controlplane.cluster.x-k8s.io/ibm-powervs-1-control-plane created + ibmpowervsmachinetemplate.infrastructure.cluster.x-k8s.io/ibm-powervs-1-control-plane created + machinedeployment.cluster.x-k8s.io/ibm-powervs-1-md-0 created + ibmpowervsmachinetemplate.infrastructure.cluster.x-k8s.io/ibm-powervs-1-md-0 created + kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/ibm-powervs-1-md-0 created + ``` + +5. Deploy Container Network Interface (CNI) + + Example: calico + ```console + kubectl apply -f https://docs.projectcalico.org/v3.15/manifests/calico.yaml + ``` + + +6. Check the state of the provisioned cluster and machine objects within the local management cluster + + Clusters + ```console + ~ kubectl get clusters + NAME PHASE + ibm-powervs-1 Provisioned + ``` + + Kubeadm Control Plane + ```console + ~ kubectl get kubeadmcontrolplane + NAME INITIALIZED API SERVER AVAILABLE VERSION REPLICAS READY UPDATED UNAVAILABLE + ibm-powervs-1-control-plane true true v1.22.4 1 1 1 + ``` + + Machines + ```console + ~ kubectl get machines + ibm-powervs-1-control-plane-vzz47 ibmpowervs://ibm-powervs-1/ibm-powervs-1-control-plane-rg6xv Running v1.22.4 + ibm-powervs-1-md-0-5444cfcbcd-6gg5z ibmpowervs://ibm-powervs-1/ibm-powervs-1-md-0-dbxb7 Running v1.22.4 + 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 + + ```console + ~ clusterctl get kubeconfig ibm-powervs-1 > ~/.kube/ibm-powervs-1 + ~ export KUBECONFIG=~/.kube/ibm-powervs-1 + ~ kubectl get nodes + NAME STATUS ROLES AGE VERSION + ibm-powervs-1-control-plane-rg6xv Ready master 41h v1.22.4 + ibm-powervs-1-md-0-4dc5c Ready 41h v1.22.4 + ibm-powervs-1-md-0-dbxb7 Ready 20h v1.22.4 + ``` diff --git a/docs/book/src/topics/powervs/prerequisites.md b/docs/book/src/topics/powervs/prerequisites.md index 6059b9179..a93be1b41 100644 --- a/docs/book/src/topics/powervs/prerequisites.md +++ b/docs/book/src/topics/powervs/prerequisites.md @@ -1 +1,60 @@ # 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)) +6. Install `pvsadm` tool (see [here](https://github.com/ppc64le-cloud/pvsadm#installation)) +6. Install `ibmcloud` tool (see [here](https://github.com/IBM-Cloud/ibm-cloud-cli-release#downloads)) + + +## **PowerVS Prerequisites** + +### Create an IBM Cloud account. + +If you don’t already have one, you need a paid IBM Cloud account to create your Power Systems Virtual Server instance. +To create an account, go to: [cloud.ibm.com](https://cloud.ibm.com). + +### Create an IBM Cloud account API key + +Please refer to the following [documentation](https://cloud.ibm.com/docs/account?topic=account-userapikey) to create an API key. + + +### Create Power Systems Virtual Server Service Instance + +After you have an active IBM Cloud account, you can create a Power Systems Virtual Server service. To do so, perform the following steps: + +1. ***TO-DO*** + +## Create Network + +A public network is required for your kubernetes cluster. Perform the following steps to create a public network for the Power Systems Virtual Server service instance created in the previous step. + +1. Create Public Network + + ```console + ~ ibmcloud pi network-create-public capi-test --dns-servers "8.8.8.8 9.9.9.9" + ``` + + Output: + ```console + Network capi-test created. + + ID fea9ac26-693d-402b-b22f-aa3d90ed0a31 + Name capi-test + Type pub-vlan + VLAN 2008 + CIDR Block 192.168.150.96/29 + IP Range [192.168.150.98 192.168.150.102] + Public IP Range [158.175.161.98 158.175.161.102] + Gateway 192.168.150.97 + DNS 8.8.8.8, 9.9.9.9 + ``` + +## Build workload cluster image: + +1. ***TO-DO*** diff --git a/templates/README.md b/templates/README.md index 9cf9f7ea1..cdca05d64 100644 --- a/templates/README.md +++ b/templates/README.md @@ -11,7 +11,7 @@ IBMVPC_NAME=ibm-vpc-1 \ IBMVPC_IMAGE_ID=r134-ea84bbec-7986-4ff5-8489-d9ec34611dd4 \ IBMVPC_PROFILE=bx2-4x16 \ IBMVPC_SSHKEY_ID=r134-2a82b725-e570-43d3-8b23-9539e8641944 \ -clusterctl config cluster ibm-vpc-1 --kubernetes-version v1.14.3 \ +clusterctl generate cluster ibm-vpc-1 --kubernetes-version v1.14.3 \ --target-namespace default \ --control-plane-machine-count=1 \ --worker-machine-count=2 \ @@ -28,7 +28,7 @@ IBMPOWERVS_VIP_CIDR="29" \ IBMPOWERVS_IMAGE_ID="fb2f75d1-1157-40b9-af2f-5459685ca089" \ IBMPOWERVS_SERVICE_INSTANCE_ID="e449d86e-c3a0-4c07-959e-8557fdf55482" \ IBMPOWERVS_NETWORK_ID="07ba61c2-64a4-42ce-911e-a3b3656eab7c" \ -clusterctl config cluster ibm-powervs-1 --kubernetes-version v1.21.2 \ +clusterctl generate cluster ibm-powervs-1 --kubernetes-version v1.21.2 \ --target-namespace default \ --control-plane-machine-count=3 \ --worker-machine-count=1 \