Skip to content

Commit 4e194f6

Browse files
Tomy2eTomy2e
authored
Add getting started doc (#11)
1 parent 9793381 commit 4e194f6

File tree

1 file changed

+209
-1
lines changed

1 file changed

+209
-1
lines changed

‎docs/getting-started.md

Lines changed: 209 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,211 @@
11
# Getting started
22

3-
WIP
3+
This document will help you provision a management cluster and a workload cluster.
4+
5+
## Setup a management cluster
6+
7+
### Provision the cluster
8+
9+
You can use any existing Kubernetes cluster as a management cluster. If you don't
10+
have one, you can use one of the following methods to provision a cluster. At the
11+
end of this section, you must have the kubeconfig of your future management cluster.
12+
13+
#### Method 1: Create a Scaleway Kapsule cluster
14+
15+
Follow this documentation to create a Scaleway Kapsule cluster: [Kubernetes - Quickstart](https://www.scaleway.com/en/docs/kubernetes/quickstart/)
16+
17+
Make sure the `KUBECONFIG` environment variable points to the cluster's kubeconfig:
18+
19+
```console
20+
export KUBECONFIG=/path/to/your/kubeconfig
21+
```
22+
23+
#### Method 2: Create a cluster in Docker with kind
24+
25+
1. Follow this documentation to install Docker: [Install Docker Engine](https://docs.docker.com/engine/install/)
26+
2. Follow this documentation to install kind: [Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start/)
27+
3. Create a kind cluster:
28+
29+
```console
30+
$ kind create cluster
31+
Creating cluster "kind" ...
32+
✓ Ensuring node image (kindest/node:v1.31.2) 🖼
33+
✓ Preparing nodes 📦
34+
✓ Writing configuration 📜
35+
✓ Starting control-plane 🕹️
36+
✓ Installing CNI 🔌
37+
✓ Installing StorageClass 💾
38+
Set kubectl context to "kind-kind"
39+
You can now use your cluster with:
40+
41+
kubectl cluster-info --context kind-kind
42+
43+
Have a question, bug, or feature request? Let us know! https://kind.sigs.k8s.io/#community 🙂
44+
```
45+
46+
4. Get the kubeconfig:
47+
48+
```console
49+
kind get kubeconfig > mgmt.yaml
50+
export KUBECONFIG=mgmt.yaml
51+
```
52+
53+
### Install cluster API and the Scaleway provider
54+
55+
1. Follow these instructions to install the `clusterctl` command-line tool: [Install clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start#install-clusterctl)
56+
2. Add `scaleway` to the provider repositories by following this [documentation](https://cluster-api.sigs.k8s.io/clusterctl/configuration#provider-repositories).
57+
You should have the following config:
58+
59+
```bash
60+
$ cat $HOME/.config/cluster-api/clusterctl.yaml
61+
providers:
62+
- name: "scaleway"
63+
url: "https://github.com/scaleway/cluster-api-provider-scaleway/releases/latest/infrastructure-components.yaml"
64+
type: "InfrastructureProvider"
65+
```
66+
67+
3. Initialize the management cluster:
68+
69+
```console
70+
$ clusterctl init --infrastructure scaleway
71+
Fetching providers
72+
Installing cert-manager version="v1.17.2"
73+
Waiting for cert-manager to be available...
74+
Installing provider="cluster-api" version="v1.10.2" targetNamespace="capi-system"
75+
Installing provider="bootstrap-kubeadm" version="v1.10.2" targetNamespace="capi-kubeadm-bootstrap-system"
76+
Installing provider="control-plane-kubeadm" version="v1.10.2" targetNamespace="capi-kubeadm-control-plane-system"
77+
Installing provider="infrastructure-scaleway" version="v0.1.0" targetNamespace="caps-system"
78+
79+
Your management cluster has been initialized successfully!
80+
81+
You can now create your first workload cluster by running the following:
82+
83+
clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f -
84+
```
85+
86+
## Prepare the OS image
87+
88+
In order to provision a workload cluster, you will need to create an OS image
89+
with all the necessary dependencies pre-installed (kubeadm, containerd, etc.).
90+
This OS image will be used to provision the nodes of your workload cluster. At the
91+
end of this section, you must have the name of the Instance image that will be used to provision
92+
the machines.
93+
94+
### Method 1: Reuse an existing image
95+
96+
Set the following environment variable:
97+
98+
```bash
99+
export SCW_PROJECT_ID="<PROJECT_ID>"
100+
```
101+
102+
Use the following command to import the `cluster-api-ubuntu-2404-v1.32.4` image provided by Scaleway:
103+
104+
> [!WARNING]
105+
> This image is provided only for testing and should not be used in production.
106+
107+
```bash
108+
export SNAPSHOT_ID=$(scw block snapshot import-from-object-storage \
109+
name=cluster-api-ubuntu-2404-v1.32.4 \
110+
bucket=scwcaps \
111+
key=images/cluster-api-ubuntu-2404-v1.32.4.qcow2 \
112+
project-id=${SCW_PROJECT_ID} \
113+
-o json | jq -r .id)
114+
```
115+
116+
Wait for the snapshot to have the `available` status:
117+
118+
```bash
119+
watch scw block snapshot get ${SNAPSHOT_ID}
120+
```
121+
122+
Finally, create an Instance image with the name `cluster-api-ubuntu-2404-v1.32.4` from the previously imported snapshot:
123+
124+
```bash
125+
scw instance image create \
126+
name=cluster-api-ubuntu-2404-v1.32.4 \
127+
arch=x86_64 \
128+
snapshot-id=${SNAPSHOT_ID} \
129+
project-id=${SCW_PROJECT_ID}
130+
```
131+
132+
### Method 2: Build an OS image with `image-builder`
133+
134+
The [image-builder](https://github.com/kubernetes-sigs/image-builder) project allows
135+
you to build a CAPI-ready OS image using Packer and Ansible.
136+
137+
To begin, please clone the `scaleway` branch of this repository: <https://github.com/Tomy2e/image-builder>.
138+
139+
Then, please follow this documentation to build your image: <https://github.com/Tomy2e/image-builder/blob/scaleway/docs/book/src/capi/providers/scaleway.md>.
140+
141+
## Create a basic workload cluster
142+
143+
1. Replace the placeholder values and set the following environment variables:
144+
145+
```bash
146+
export CLUSTER_NAME="my-cluster"
147+
148+
# Scaleway credentials, project ID and region.
149+
export SCW_ACCESS_KEY="<ACCESS_KEY>"
150+
export SCW_SECRET_KEY="<SECRET_KEY>"
151+
export SCW_PROJECT_ID="<PROJECT_ID>"
152+
export SCW_REGION="fr-par"
153+
154+
# Scaleway Instance image names that will be used to provision servers.
155+
export CONTROL_PLANE_MACHINE_IMAGE="<IMAGE_NAME>"
156+
export WORKER_MACHINE_IMAGE="<IMAGE_NAME>"
157+
```
158+
159+
2. Generate the cluster manifests (update the flags if needed):
160+
161+
```bash
162+
clusterctl generate cluster ${CLUSTER_NAME} \
163+
--kubernetes-version v1.32.4 \
164+
--control-plane-machine-count 1 \
165+
--worker-machine-count 1 > my-cluster.yaml
166+
```
167+
168+
3. Review and edit the `my-cluster.yaml` file as needed.
169+
4. Apply the `my-cluster.yaml` file to create the workload cluster.
170+
5. Wait for the cluster and machines to be ready.
171+
172+
```bash
173+
$ clusterctl describe cluster ${CLUSTER_NAME}
174+
NAME READY SEVERITY REASON SINCE MESSAGE
175+
Cluster/my-cluster True 2m19s
176+
├─ClusterInfrastructure - ScalewayCluster/my-cluster
177+
├─ControlPlane - KubeadmControlPlane/my-cluster-control-plane True 2m19s
178+
│ └─Machine/my-cluster-control-plane-pxpdl True 3m19s
179+
│ └─MachineInfrastructure - ScalewayMachine/my-cluster-control-plane-pxpdl
180+
└─Workers
181+
└─MachineDeployment/my-cluster-md-0 False Warning WaitingForAvailableMachines 3m31s Minimum availability requires 1 replicas, current 0 available
182+
└─Machine/my-cluster-md-0-bgzv8-5k96v True 2m15s
183+
└─MachineInfrastructure - ScalewayMachine/my-cluster-md-0-bgzv8-5k96v
184+
```
185+
186+
6. Fetch the kubeconfig of the cluster.
187+
188+
```bash
189+
clusterctl get kubeconfig ${CLUSTER_NAME} > kubeconfig.yaml
190+
export KUBECONFIG=kubeconfig.yaml
191+
```
192+
193+
7. List nodes.
194+
195+
```bash
196+
$ kubectl get nodes
197+
NAME STATUS ROLES AGE VERSION
198+
my-cluster-control-plane-pxpdl NotReady control-plane 3m46s v1.32.4
199+
my-cluster-md-0-bgzv8-5k96v NotReady <none> 2m57s v1.32.4
200+
```
201+
202+
> [!NOTE]
203+
> Nodes will have the `NotReady` status until a CNI is installed in the cluster.
204+
205+
### Setup the workload cluster
206+
207+
The workload cluster is ready to use. You should now:
208+
209+
- Install a CNI plugin
210+
- (Optional) Install the [Scaleway CCM](https://github.com/scaleway/scaleway-cloud-controller-manager) to manage Nodes and LoadBalancers
211+
- (Optional) Install the [Scaleway CSI](https://github.com/scaleway/scaleway-csi) driver to manage block volumes and snapshots

0 commit comments

Comments
 (0)