Skip to content
Switch branches/tags

Latest commit

Signed-off-by: Prajyot-Parab <>

Git stats


Failed to load latest commit information.
Latest commit message
Commit time

LICENSE Releases Go Report Card

Table of Contents generated with DocToc

Kubernetes Cluster API Provider IBM Cloud

Powered by 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


  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
       - 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: created created 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


    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=
    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: created created created created created created created
  4. Deploy Container Network Interface (CNI)

    Example: calico

    kubectl apply -f
  5. Check the state of the provisioned cluster and machine objects within the local management cluster


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

    Kubeadm Control Plane

    ~ kubectl get kubeadmcontrolplane
    ibm-vpc-0-control-plane    true          true                   v1.19.9   1          1       1


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