Skip to content

Commit 233f070

Browse files
killianmuldoonkillianmuldoon
committed
Add clusterclass quickstart guide
Signed-off-by: killianmuldoon <[email protected]>
1 parent 119feab commit 233f070

File tree

6 files changed

+479
-0
lines changed

6 files changed

+479
-0
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
- [Experimental Features](./tasks/experimental-features/experimental-features.md)
1919
- [MachinePools](./tasks/experimental-features/machine-pools.md)
2020
- [ClusterResourceSet](./tasks/experimental-features/cluster-resource-set.md)
21+
- [ClusterClass](./tasks/experimental-features/cluster-classes.md)
2122
- [clusterctl CLI](./clusterctl/overview.md)
2223
- [clusterctl Commands](clusterctl/commands/commands.md)
2324
- [init](clusterctl/commands/init.md)

‎docs/book/src/tasks/experimental-features/cluster-classes.md

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# ClusterClass
2+
3+
The ClusterClass feature introduces a new way to create clusters which reduces boilerplate and enables flexible and powerful customization of clusters.
4+
ClusterClass is a powerful abstraction implemented on top of existing interfaces and offering a set of tools and operations to streamline cluster lifecycle management while maintaining the same underlying API.
5+
6+
This tutorial covers using Cluster API and ClusterClass to create a Kubernetes cluster and how to perform a one-touch Kubernetes version upgrade.
7+
8+
<aside class="note warning">
9+
10+
<h1>Note</h1>
11+
12+
This guide only covers creating a ClusterClass cluster with the CAPD provider.
13+
</aside>
14+
15+
## Installation
16+
17+
### Prerequisites
18+
19+
#### Install tools
20+
21+
This guide requires the following tools are installed:
22+
- Install and setup [kubectl] and [clusterctl]
23+
- Install [Kind] and [Docker]
24+
25+
#### Enable experimental features
26+
27+
ClusterClass is currently behind a feature gate that needs to be enabled.
28+
This tutorial will also use another experimental gated feature - Cluster Resource Set. This is not required for ClusterClass to work but is used in this tutorial to set up networking.
29+
30+
To enable these features set the respective environment variables by running:
31+
```bash
32+
export EXP_CLUSTER_RESOURCE_SET=true
33+
export CLUSTER_TOPOLOGY=true
34+
```
35+
This ensures that the Cluster Topology and Cluster Resource Set features are enabled when the providers are initialized.
36+
37+
38+
#### Create a CAPI management cluster
39+
40+
A script to set up a Kind cluster pre-configured for CAPD (the docker infrastructure provider) can be found in the [hack folder of the core repo](https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/main/hack/kind-install-for-capd.sh).
41+
42+
To set up the cluster from the root of the repo run:
43+
```bash
44+
./hack/kind-install-for-capd.sh
45+
clusterctl init --infrastructure docker
46+
````
47+
48+
### Create a new Cluster using ClusterClass
49+
50+
#### Create the ClusterClass and templates
51+
52+
With a management Cluster with CAPD initialized and the Cluster Topology feature gate enabled, the next step is to create the ClusterClass and its referenced templates.
53+
The ClusterClass - first in the yaml below - contains references to the templates needed to build a full cluster, defining a shape that can be re-used for any number of clusters.
54+
* ClusterClass
55+
* For the InfrastructureCluster:
56+
* DockerClusterTemplate
57+
* For the ControlPlane:
58+
* KubeadmControlPlaneTemplate
59+
* DockerMachineTemplate
60+
* For the worker nodes:
61+
* DockerMachineTemplate
62+
* KubeadmConfigTemplate
63+
64+
The full ClusterClass definition can also be found in the [CAPI repo](https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/main/docs/book/src/tasks/yamls/clusterclass.yaml).
65+
66+
<details><summary>ClusterClass</summary>
67+
68+
```yaml
69+
{{#include ./yamls/clusterclass.yaml}}
70+
```
71+
72+
</details>
73+
74+
75+
To create the objects on your local cluster run:
76+
77+
```bash
78+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/main/docs/book/src/tasks/yamls/clusterclass.yaml
79+
```
80+
81+
#### Enable networking for workload clusters
82+
83+
To make sure workload clusters come up with a functioning network a Kindnet ConfigMap with a Kindnet ClusterResourceSet is required. Kindnet only offers networking for Clusters built with Kind and CAPD. This can be substituted for any other networking solution for Kubernetes e.g. Calico as used in the Quickstart guide.
84+
85+
The kindnet configuration file can be found in the [CAPI repo](https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/main/docs/book/src/tasks/yamls/clusterclass.yaml).
86+
87+
To create the resources run:
88+
```bash
89+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/main/docs/book/src/tasks/yamls/kindnet-clusterresourceset.yaml
90+
```
91+
92+
#### Create the workload cluster
93+
94+
This is a Cluster definition that leverages the ClusterClass created above to define its shape.
95+
96+
<details><summary>Cluster</summary>
97+
98+
```yaml
99+
{{#include ./yamls/clusterclass-quickstart.yaml}}
100+
```
101+
</details>
102+
103+
Create the Cluster object from the file in [the CAPI repo](https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/main/docs/book/src/tasks/yamls/clusterclass-quickstart.yaml) with:
104+
105+
```bash
106+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/cluster-api/main/docs/book/src/tasks/yamls/clusterclass-quickstart.yaml
107+
```
108+
109+
#### Verify the workload cluster is running
110+
111+
The cluster will now start provisioning. You can check status with:
112+
113+
```bash
114+
kubectl get cluster
115+
```
116+
117+
Get a view of the cluster and its resources as they are created by running:
118+
119+
```bash
120+
clusterctl describe cluster clusterclass-quickstart
121+
```
122+
123+
To verify the control plane is up:
124+
125+
```bash
126+
kubectl get kubeadmcontrolplane
127+
```
128+
129+
The output should be similar to:
130+
131+
```bash
132+
NAME INITIALIZED API SERVER AVAILABLE VERSION REPLICAS READY UPDATED UNAVAILABLE
133+
clusterclass-quickstart true v1.21.2 1 1 1
134+
```
135+
136+
137+
## Upgrade a Cluster using Managed Topology
138+
139+
The `spec.topology` field added to the Cluster object as part of ClusterClass allows changes made on the Cluster to be propagated across all relevant objects. This turns a Kubernetes cluster upgrade into a one-touch operation.
140+
Looking at the newly-created cluster, the version of the control plane and the machine deployments is v1.21.2.
141+
142+
```bash
143+
> kubectl get kubeadmcontrolplane,machinedeployments
144+
145+
NAME CLUSTER INITIALIZED API SERVER AVAILABLE REPLICAS READY UPDATED UNAVAILABLE AGE VERSION
146+
kubeadmcontrolplane.controlplane.cluster.x-k8s.io/clusterclass-quickstart-XXXX clusterclass-quickstart true true 1 1 1 0 2m21s v1.21.2
147+
148+
NAME CLUSTER REPLICAS READY UPDATED UNAVAILABLE PHASE AGE VERSION
149+
machinedeployment.cluster.x-k8s.io/clusterclass-quickstart-linux-workers-XXXX clusterclass-quickstart 1 1 1 0 Running 2m21s v1.21.2
150+
151+
```
152+
153+
To update the Cluster the only change needed is to the `version` field under `spec.topology` in the Cluster object.
154+
155+
156+
Change `1.21.2` to `1.22.0` as below.
157+
```bash
158+
kubectl patch cluster clusterclass-quickstart --type json --patch '[{"op": "replace", "path": "/spec/topology/version", "value": "v1.22.0"}]'
159+
```
160+
161+
The upgrade will take some time to roll out as it will take place machine by machine with older versions of the machines only being removed after healthy newer versions come online.
162+
163+
To watch the update progress run:
164+
```bash
165+
watch kubectl get kubeadmcontrolplane,machinedeployments
166+
```
167+
After a few minutes the upgrade will be complete and the output will be similar to:
168+
```bash
169+
NAME CLUSTER INITIALIZED API SERVER AVAILABLE REPLICAS READY UPDATED UNAVAILABLE AGE VERSION
170+
kubeadmcontrolplane.controlplane.cluster.x-k8s.io/clusterclass-quickstart-XXXX clusterclass-quickstart true true 1 1 1 0 7m29s v1.22.0
171+
172+
NAME CLUSTER REPLICAS READY UPDATED UNAVAILABLE PHASE AGE VERSION
173+
machinedeployment.cluster.x-k8s.io/clusterclass-quickstart-linux-workers-XXXX clusterclass-quickstart 1 1 1 0 Running 7m29s v1.22.0
174+
```
175+
176+
## Clean Up
177+
178+
Delete workload cluster.
179+
```bash
180+
kubectl delete cluster clusterclass-quickstart
181+
```
182+
<aside class="note warning">
183+
184+
IMPORTANT: In order to ensure a proper cleanup of your infrastructure you must always delete the cluster object. Deleting the entire cluster template with `kubectl delete -f clusterclass-quickstart.yaml` might lead to pending resources to be cleaned up manually.
185+
</aside>
186+
187+
Delete management cluster
188+
```bash
189+
kind delete clusters capi-test
190+
```
191+
192+
<!-- links -->
193+
[quick start guide]: ../../user/quick-start.md
194+
[bootstrap cluster]: ../../reference/glossary.md#bootstrap-cluster
195+
[clusterctl]: ../../user/quick-start.md#install-clusterctl
196+
[Docker]: https://www.docker.com/
197+
[infrastructure provider]: ../../reference/glossary.md#infrastructure-provider
198+
[kind]: https://kind.sigs.k8s.io/
199+
[KubeadmControlPlane]: ../../developer/architecture/controllers/control-plane.md
200+
[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
201+
[management cluster]: ../../reference/glossary.md#management-cluster
202+
[provider]:../../reference/providers.md
203+
[provider components]: ../../reference/glossary.md#provider-components
204+
[workload cluster]: ../../reference/glossary.md#workload-cluster

‎docs/book/src/tasks/experimental-features/experimental-features.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ Similarly, to **validate** if a particular feature is enabled, see cluster-api-p
7676
7777
* [MachinePools](./machine-pools.md)
7878
* [ClusterResourceSet](./cluster-resource-set.md)
79+
* [ClusterClass](./cluster-classes.md)
7980
8081
**Warning**: Experimental features are unreliable, i.e., some may one day be promoted to the main repository, or they may be modified arbitrarily or even disappear altogether.
8182
In short, they are not subject to any compatibility or deprecation promise.

‎docs/book/src/tasks/experimental-features/yamls/clusterclass-quickstart.yaml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
apiVersion: cluster.x-k8s.io/v1beta1
2+
kind: Cluster
3+
metadata:
4+
name: "clusterclass-quickstart"
5+
namespace: default
6+
labels:
7+
cni: kindnet
8+
spec:
9+
clusterNetwork:
10+
services:
11+
cidrBlocks: ["10.128.0.0/12"]
12+
pods:
13+
cidrBlocks: ["192.168.0.0/16"]
14+
serviceDomain: "cluster.local"
15+
topology:
16+
class: clusterclass
17+
version: v1.21.2
18+
controlPlane:
19+
replicas: 1
20+
workers:
21+
machineDeployments:
22+
- class: linux-worker
23+
name: linux-workers
24+
replicas: 1

‎docs/book/src/tasks/experimental-features/yamls/clusterclass.yaml

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
apiVersion: cluster.x-k8s.io/v1beta1
2+
kind: ClusterClass
3+
metadata:
4+
name: clusterclass
5+
namespace: default
6+
spec:
7+
controlPlane:
8+
metadata:
9+
ref:
10+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
11+
kind: KubeadmControlPlaneTemplate
12+
name: clusterclass-control-plane
13+
namespace: default
14+
machineInfrastructure:
15+
ref:
16+
kind: DockerMachineTemplate
17+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
18+
name: "clusterclass-control-plane"
19+
namespace: default
20+
infrastructure:
21+
ref:
22+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
23+
kind: DockerClusterTemplate
24+
name: clusterclass-infrastructure
25+
namespace: default
26+
workers:
27+
machineDeployments:
28+
- class: linux-worker
29+
template:
30+
metadata:
31+
bootstrap:
32+
ref:
33+
kind: KubeadmConfigTemplate
34+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
35+
name: "clusterclass-md-1"
36+
infrastructure:
37+
ref:
38+
kind: DockerMachineTemplate
39+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
40+
name: "clusterclass-md-1"
41+
42+
---
43+
44+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
45+
kind: DockerClusterTemplate
46+
metadata:
47+
name: clusterclass-infrastructure
48+
namespace: default
49+
---
50+
kind: KubeadmControlPlaneTemplate
51+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
52+
metadata:
53+
name: "clusterclass-control-plane"
54+
namespace: default
55+
spec:
56+
template:
57+
spec:
58+
replicas: 1
59+
machineTemplate:
60+
infrastructureRef:
61+
kind: DockerMachineTemplate
62+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
63+
name: "clusterclass-control-plane"
64+
namespace: default
65+
kubeadmConfigSpec:
66+
clusterConfiguration:
67+
controllerManager:
68+
extraArgs: { enable-hostpath-provisioner: 'true' }
69+
apiServer:
70+
certSANs: [ localhost, 127.0.0.1 ]
71+
initConfiguration:
72+
nodeRegistration:
73+
criSocket: /var/run/containerd/containerd.sock
74+
kubeletExtraArgs:
75+
cgroup-driver: cgroupfs
76+
eviction-hard: 'nodefs.available<0%,nodefs.inodesFree<0%,imagefs.available<0%'
77+
joinConfiguration:
78+
nodeRegistration:
79+
criSocket: /var/run/containerd/containerd.sock
80+
kubeletExtraArgs:
81+
cgroup-driver: cgroupfs
82+
eviction-hard: 'nodefs.available<0%,nodefs.inodesFree<0%,imagefs.available<0%'
83+
version: v1.21.2
84+
---
85+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
86+
kind: DockerMachineTemplate
87+
metadata:
88+
name: "clusterclass-control-plane"
89+
namespace: default
90+
spec:
91+
template:
92+
spec:
93+
extraMounts:
94+
- containerPath: "/var/run/docker.sock"
95+
hostPath: "/var/run/docker.sock"
96+
---
97+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
98+
kind: DockerMachineTemplate
99+
metadata:
100+
name: "clusterclass-md-1"
101+
namespace: default
102+
spec:
103+
template:
104+
spec: { }
105+
---
106+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
107+
kind: KubeadmConfigTemplate
108+
metadata:
109+
name: "clusterclass-md-1"
110+
namespace: default
111+
spec:
112+
template:
113+
spec:
114+
joinConfiguration:
115+
nodeRegistration:
116+
kubeletExtraArgs:
117+
cgroup-driver: cgroupfs
118+
eviction-hard: 'nodefs.available<0%,nodefs.inodesFree<0%,imagefs.available<0%'

0 commit comments

Comments
 (0)