clusterctl

clusterctl

clusterctl is the SIG-cluster-lifecycle sponsored tool that implements the Cluster API.

Read the experience doc here.

Getting Started

Due to the limitations described below, you must currently compile and run a clusterctl binary from your chosen provider implementation rather than using the binary from this repository.

Prerequisites

1. Install minikube
2. Install a driver for minikube. For Linux, we recommend kvm2. For MacOS, we recommend VirtualBox.
3. Build the clusterctl tool

$ git clone https://github.com/kubernetes-sigs/cluster-api $GOPATH/src/sigs.k8s.io/cluster-api
$ cd $GOPATH/src/sigs.k8s.io/cluster-api/cmd/clusterctl/
$ go build

Limitations

clusterctl can only use a provider that is compiled in. As provider specific code has been moved out of this repository, running the clusterctl binary compiled from this repository isn't particularly useful.

There is current work ongoing to rectify this issue, which centers around removing the ProviderDeployer interface from the clusterdeployer package. The two tracking issues for removing the two functions in the interface are https://github.com/kubernetes-sigs/cluster-api/issues/158 and https://github.com/kubernetes-sigs/cluster-api/issues/160.

Creating a cluster

1. Create the cluster.yaml, machines.yaml, provider-components.yaml, and addons.yaml files configured for your cluster. See the provider specific templates and generation tools for your chosen provider implementation.

2. Create a cluster:

   ./clusterctl create cluster --provider <provider> -c cluster.yaml -m machines.yaml -p provider-components.yaml -a addons.yaml
   

To choose a specific minikube driver, please use the --vm-driver command line parameter. For example to use the kvm2 driver with clusterctl you would add --vm-driver kvm2

Additional advanced flags can be found via help.

./clusterctl create cluster --help

Interacting with your cluster

Once you have created a cluster, you can interact with the cluster and machine resources using kubectl:

$ kubectl --kubeconfig kubeconfig get clusters
$ kubectl --kubeconfig kubeconfig get machines
$ kubectl --kubeconfig kubeconfig get machines -o yaml

Scaling your cluster

You can scale your cluster by adding additional individual Machines, or by adding a MachineSet or MachineDeployment and changing the number of replicas.

Upgrading your cluster

NOT YET SUPPORTED!

Node repair

NOT YET SUPPORTED!

Deleting a cluster

When you are ready to remove your cluster, you can use clusterctl to delete the cluster:

./clusterctl delete cluster --kubeconfig kubeconfig

Please also check the documentation for your provider implementation to determine if any additional steps need to be taken to completely clean up your cluster.

Contributing

If you are interested in adding to this project, see the contributing guide for information on how you can get involved.