README.md

Table of Contents generated with DocToc

• Kubernetes Cluster API Provider IBM Cloud
  • What is the Cluster API Provider IBM Cloud
  • Getting Started
    • Prerequisites
  • How to provision a simple workload cluster in IBM Cloud VPC Gen2 from local bootstrap cluster
    • Build workload cluster image:
    • Provision local boostrap management cluster:
    • Provision Workload Cluster in IBM Cloud VPC
  • Community, discussion, contribution, and support
    • Code of conduct

Kubernetes Cluster API Provider IBM Cloud

---

This repository hosts a concrete implementation of an IBM Cloud provider for the cluster-api project.

What is the Cluster API Provider IBM Cloud

The 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.

Getting Started

Prerequisites

1. Install kubectl (see here). 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 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. This is preferred.
   • If you want to use VM, install minikube, version 0.30.0 or greater.
   • If you want to use existing Kubernetes cluster, prepare your kubeconfig.
3. Install a driver if you are using minikube. For Linux, we recommend kvm2. For MacOS, we recommend VirtualBox.
4. An appropriately configured Go development environment
5. Install clusterctl tool (see here)

How to provision a simple workload cluster in IBM Cloud VPC Gen2 from local bootstrap cluster

Build workload cluster image:

1. Build a qcow2 image suitable for use as a Kubernetes cluster machine as detailed in the image builder book.

   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.

Provision local boostrap management cluster:

1. Create simple, local bootstrap cluster with a control-plane and worker node

   Using kind:

   ~ kind create cluster --name my-bootstrap --config bootstrap.yaml

   Example bootstrap.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.

   ~ kubectl get nodes
   NAME                         STATUS   ROLES                  AGE   VERSION
   my-bootstrap-control-plane   Ready    control-plane,master   46h   v1.20.2
   my-bootstrap-worker          Ready    <none>                 46h   v1.20.2

2. Apply IBM VPC CAPI CRDs

   ~ kubectl apply -f config/crd/bases

   Output:

   customresourcedefinition.apiextensions.k8s.io/ibmvpcclusters.infrastructure.cluster.x-k8s.io created
   customresourcedefinition.apiextensions.k8s.io/ibmvpcmachines.infrastructure.cluster.x-k8s.io created
   customresourcedefinition.apiextensions.k8s.io/ibmvpcmachinetemplates.infrastructure.cluster.x-k8s.io created

3. Initialize local bootstrap cluter as a management cluster

   This cluster will be used to provision a workload cluster in IBM Cloud.

   ~ clusterctl init

   Output:

   Fetching providers
   Installing cert-manager Version="v1.1.0"
   Waiting for cert-manager to be available...
   Installing Provider="cluster-api" Version="v0.3.16" TargetNamespace="capi-system"
   Installing Provider="bootstrap-kubeadm" Version="v0.3.16" TargetNamespace="capi-kubeadm-bootstrap-system"
   Installing Provider="control-plane-kubeadm" Version="v0.3.16" TargetNamespace="capi-kubeadm-control-plane-system"
   
   Your management cluster has been initialized successfully!
   
   You can now create your first workload cluster by running the following:
   
     clusterctl config cluster [name] --kubernetes-version [version] | kubectl apply -f -

Provision Workload Cluster in IBM Cloud VPC

1. Set workload cluster environment variables

   The sample IAM_ENDPOINT below points to Production and the SERVICE_ENDPOINT points to the us-east VPC region. Make sure these values reflect your target VPC environment in IBM Cloud.

   export IAM_ENDPOINT=https://iam.cloud.ibm.com/identity/token
   export SERVICE_ENDPOINT=https://us-south.iaas.cloud.ibm.com/v1
   export API_KEY=<YOUR_API_KEY>

2. Run IBM provider controllers

   The controllers will run against your local management bootstrap cluster.

   ~ make run

3. Provision workload cluster in IBM Cloud

   You can use clusterctl to render the yaml through templates.

   Note: the IBMVPC_IMAGE_ID value below should reflect the ID of the custom qcow2 image

   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:

   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

4. Deploy Container Network Interface (CNI)

   Example: calico

   kubectl apply -f https://docs.projectcalico.org/v3.15/manifests/calico.yaml

5. Check the state of the provisioned cluster and machine objects within the local management cluster

   Clusters

   ~ kubectl get clusters
   NAME         PHASE
   ibm-vpc-0    Provisioned

   Kubeadm Control Plane

   ~ 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

   ~ 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

6. Check the state of the newly provisioned cluster within IBM Cloud

   ~ 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    <none>   41h   v1.18.15
   ibm-vpc-0-md-0-dbxb7             Ready    <none>   20h   v1.18.15

7. Experiment with machinedeployment alterations in your management cluster

   With your management (local) and workload (IBM Cloud) clusters successfully provisioned, you can now experiment with altering the number of machine deployment replicas in your management cluster and see the replica counts reconciled in your workload cluster.

   ~ kubectl get machinedeployments
   NAME              PHASE       REPLICAS   READY   UPDATED   UNAVAILABLE
   ibm-vpc-0-md-0    Running     2          2       2
   
   ~ kubectl scale machinedeployment ibm-vpc-0-md-0 --replicas 3

   Increase / decrease the replicas: 2 count in the spec section to see the machine replicas reconciled within the workload cluster.

Community, discussion, contribution, and support

If you have questions or want to get the latest project news, you can connect with us in the following ways:

• Chat with us on the Kubernetes Slack in the #cluster-api-ibmcloud channel
• Subscribe to the SIG Cluster Lifecycle Google Group for access to documents and calendars
• Join our Weekly meeting sessions where we share the latest project news, demos, answer questions, and triage issues
  • Weekly on Friday @ 09:00 IST on Zoom
  • Previous meetings: [ notes ]

Pull Requests and feedback on issues are very welcome! See the issue tracker if you're unsure where to start, especially the Good first issue and Help wanted tags, and also feel free to reach out to discuss.

See also our contributor guide and the Kubernetes community page for more details on how to get involved.

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.