-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: first pass moving clusterctl to book
- Loading branch information
1 parent
7d6959b
commit 5906be9
Showing
2 changed files
with
96 additions
and
95 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,96 @@ | ||
# Clusterctl | ||
# Clusterctl | ||
|
||
# Using `clusterctl` to create a cluster from scratch | ||
<!-- START doctoc generated TOC please keep comment here to allow auto update --> | ||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> | ||
|
||
|
||
- [What is `clusterctl`?](#what-is-clusterctl) | ||
- [Creating a cluster](#creating-a-cluster) | ||
- [Creating a workload cluster using the management cluster](#creating-a-workload-cluster-using-the-management-cluster) | ||
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update --> | ||
|
||
This document provides an overview of how `clusterctl` works and explains how one can use `clusterctl` | ||
to create a Kubernetes cluster from scratch. | ||
|
||
## What is `clusterctl`? | ||
|
||
`clusterctl` is a CLI tool to create a Kubernetes cluster. `clusterctl` is provided by the [provider implementations](https://github.com/Kubernetes-sigs/cluster-api#provider-implementations). | ||
It uses Cluster API provider implementations to provision resources needed by the Kubernetes cluster. | ||
|
||
## Creating a cluster | ||
|
||
`clusterctl` needs 4 YAML files to start with: `provider-components.yaml`, `cluster.yaml`, `machines.yaml` , | ||
`addons.yaml`. | ||
|
||
* `provider-components.yaml` contains the *Custom Resource Definitions ([CRDs](https://Kubernetes.io/docs/concepts/extend-Kubernetes/api-extension/custom-resources/))* | ||
of all the resources that are managed by Cluster API. Some examples of these resources | ||
are: `Cluster`, `Machine`, `MachineSet`, etc. For more details about Cluster API resources | ||
click [here](https://cluster-api.sigs.k8s.io/common_code/architecture.html#cluster-api-resources). | ||
* `cluster.yaml` defines an object of the resource type `Cluster`. | ||
* `machines.yaml` defines an object of the resource type `Machine`. Generally creates the machine | ||
that becomes the control-plane. | ||
* `addons.yaml` contains the addons for the provider. | ||
|
||
Many providers implementations come with helpful scripts to generate these YAMLS. Provider implementation | ||
can be found [here](https://github.com/Kubernetes-sigs/cluster-api#provider-implementations). | ||
|
||
`clusterctl` also comes with additional features. For example, `clusterctl` can also take in an optional | ||
`bootstrap-only-components.yaml` to provide resources to the bootstrap cluster without also providing them | ||
to the target cluster post-pivot. | ||
|
||
For more details about all the supported options run: | ||
|
||
``` | ||
clusterctl create cluster --help | ||
``` | ||
|
||
After generating the YAML files run the following command: | ||
|
||
``` | ||
clusterctl create cluster --provider <PROVIDER> --bootstrap-type <BOOTSTRAP CLUSTER TYPE> -c cluster.yaml -m machines.yaml -p provider-components.yaml --addon-components addons.yaml | ||
``` | ||
|
||
Example usage: | ||
|
||
``` | ||
# VMware vSphere | ||
clusterctl create cluster --provider vsphere --bootstrap-type kind -c cluster.yaml -m machines.yaml -p provider-components.yaml --addon-components addons.yaml | ||
# Amazon AWS | ||
clusterctl create cluster --provider aws --bootstrap-type kind -c cluster.yaml -m machines.yaml -p provider-components.yaml --addon-components addons.yaml | ||
``` | ||
|
||
**What happens when we run the command?** | ||
After running the command first it creates a local cluster. If `kind` was passed as the `--bootstrap-type` | ||
it creates a local [kind](https://kind.sigs.k8s.io/) cluster. This cluster is generally referred to as the *bootstrap cluster*. | ||
On this kind Kubernetes cluster the `provider-components.yaml` file is applied. This step loads the CRDs into | ||
the cluster. It also creates 2 [StatefulSet](https://Kubernetes.io/docs/concepts/workloads/controllers/statefulset/) | ||
pods that run the cluster api controller and the provider specific controller. These pods register the custom | ||
controllers that manage the newly defined resources (`Cluster`, `Machine`, `MachineSet`, etc). | ||
|
||
Next, `clusterctl` applies the `cluster.yaml` and `machines.yaml` to the local kind Kubernetes cluster. This | ||
step creates a Kubernetes cluster with only a control-plane(as defined in `machines.yaml`) on the specified | ||
provider. This newly created cluster is generally referred to as the *management cluster* or *pivot cluster* | ||
or *initial target cluster*. The management cluster is responsible for creating and maintaining the work-load cluster. | ||
|
||
Lastly, `clusterctl` moves all the CRDs and the custom controllers from the bootstrap cluster to the | ||
management cluster and deletes the locally created bootstrap cluster. This step is referred to as the *pivot*. | ||
|
||
### Creating a workload cluster using the management cluster | ||
|
||
The *workload cluster* also sometimes referred to as the *target cluster* is the Kubernetes cluster on to which | ||
the final application is deployed. The target cluster is responsible for handling the workload of the application, | ||
not the management cluster. | ||
|
||
As the management cluster is up we can create a workload cluster by simply applying the appropriate | ||
`cluster.yaml`, `machines.yaml` and `machineset.yaml` on the management cluster. This will create the VMs(Nodes) | ||
as defined in these YAMLs. Following this, a bootstrap mechanism is used to create a Kubernetes cluster on these VMs. | ||
While any of the several bootstrapping mechanisms can be used `kubeadm` is the popular option. | ||
|
||
**NOTE:** Workload clusters do not have any addons applied. Nodes in your workload clusters will be in the `NotReady` | ||
state until you apply addons for CNI plugin. | ||
|
||
Once the target cluster is up the user can create the `Deployments`, `Services`, etc that handle the workload | ||
of the application. |
This file was deleted.
Oops, something went wrong.