Skip to content

Commit 072cba5

Browse files
Tomy2eTomy2e
authored
Document provider custom resources (#12)
1 parent 859bb8a commit 072cba5

File tree

5 files changed

+498
-3
lines changed

5 files changed

+498
-3
lines changed

‎docs/getting-started.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -134,9 +134,13 @@ scw instance image create \
134134
The [image-builder](https://github.com/kubernetes-sigs/image-builder) project allows
135135
you to build a CAPI-ready OS image using Packer and Ansible.
136136

137-
To begin, please clone the `scaleway` branch of this repository: <https://github.com/Tomy2e/image-builder>.
137+
To begin, please clone the `image-builder` repository:
138138

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>.
139+
```bash
140+
git clone https://github.com/kubernetes-sigs/image-builder.git
141+
```
142+
143+
Then, please follow the [Building Images for Scaleway documentation](https://image-builder.sigs.k8s.io/capi/providers/scaleway).
140144

141145
## Create a basic workload cluster
142146

@@ -166,6 +170,8 @@ Then, please follow this documentation to build your image: <https://github.com/
166170
```
167171

168172
3. Review and edit the `my-cluster.yaml` file as needed.
173+
For configuring the CAPS CRDs, refer to the [ScalewayCluster](scalewaycluster.md)
174+
and [ScalewayMachine](scalewaymachine.md) documentations.
169175
4. Apply the `my-cluster.yaml` file to create the workload cluster.
170176
5. Wait for the cluster and machines to be ready.
171177

‎docs/scalewaycluster.md

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# ScalewayCluster
2+
3+
The `ScalewayCluster` resource provisions the necessary Scaleway infrastructure
4+
to make the Kubernetes workload cluster work. This may include [Load Balancers](https://www.scaleway.com/en/load-balancer/),
5+
[Private Networks](https://www.scaleway.com/en/vpc/), [Public Gateways](https://www.scaleway.com/en/public-gateway/),
6+
and more, depending on the configuration of the `ScalewayCluster`.
7+
8+
This document describes the various configuration options you can set to enable or disable
9+
important features on a `ScalewayCluster`.
10+
11+
## Minimal ScalewayCluster
12+
13+
The `ScalewayCluster` with the minimum options looks like this:
14+
15+
```yaml
16+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
17+
kind: ScalewayCluster
18+
metadata:
19+
name: my-cluster
20+
namespace: default
21+
spec:
22+
projectID: 11111111-1111-1111-1111-111111111111
23+
region: fr-par
24+
scalewaySecretName: my-scaleway-secret
25+
```
26+
27+
The `projectID`, `region` and `scalewaySecretName` fields are **required**.
28+
29+
The `projectID` and `region` fields are **immutable**, they cannot be updated after creation.
30+
31+
The `scalewaySecretName` field must contain the name of an existing `Secret` inside the
32+
namespace of the `ScalewayCluster`. For more information about this secret, please refer
33+
to the [Scaleway Secret documentation](secret.md).
34+
35+
## Failure domains
36+
37+
The `failureDomains` field allows to set the Scaleway availability zones where the
38+
control-plane nodes will be deployed. The specified availability zones must be in
39+
the same region as the region specified in the `region` field. When omitted, all
40+
availability zones in the specified region are automatically eligible for hosting
41+
control-plane nodes.
42+
43+
> [!WARNING]
44+
> Pricing of Scaleway products may differ between availability zones. For better
45+
> cost predictability, it is recommended to always set your desired `failureDomains`.
46+
47+
You can find the current failure domains of a `ScalewayCluster` by running this command:
48+
49+
```bash
50+
$ kubectl get scalewaycluster my-cluster --template='{{.status.failureDomains}}'
51+
map[fr-par-1:map[controlPlane:true] fr-par-2:map[controlPlane:true] fr-par-3:map[controlPlane:true]]
52+
```
53+
54+
Here is an example of `ScalewayCluster` with the failure domains set to `fr-par-1` and `fr-par-2`:
55+
56+
```yaml
57+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
58+
kind: ScalewayCluster
59+
metadata:
60+
name: my-cluster
61+
namespace: default
62+
spec:
63+
region: fr-par
64+
failureDomains:
65+
- fr-par-1
66+
- fr-par-2
67+
# some fields were omitted...
68+
```
69+
70+
## Other features
71+
72+
### DNS
73+
74+
Set the `network.controlPlaneDNS` field to automatically configure DNS records that
75+
will point to the Load Balancer address(es) of your workload cluster.
76+
77+
In this example, the FQDN `my-cluster.subdomain.your-domain.com` will have `A` record(s)
78+
configured to point to the Load Balancer IP address(es).
79+
80+
```yaml
81+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
82+
kind: ScalewayCluster
83+
metadata:
84+
name: my-cluster
85+
namespace: default
86+
spec:
87+
network:
88+
controlPlaneDNS:
89+
domain: subdomain.your-domain.com
90+
name: my-cluster
91+
# some fields were omitted...
92+
```
93+
94+
The `domain` must be an existing Scaleway DNS Zone. Please refer to the
95+
[Scaleway Domains and DNS documentation](https://www.scaleway.com/en/docs/domains-and-dns/)
96+
for more information. You may register an external domain by following
97+
[this documentation](https://www.scaleway.com/en/docs/domains-and-dns/how-to/add-external-domain/).
98+
99+
The `network.controlPlaneDNS` field is **immutable**, it cannot be updated after creation.
100+
101+
### Load Balancer
102+
103+
When creating a `ScalewayCluster`, a "main" Load Balancer is always created.
104+
It is also possible to specify "extra" Load Balancers to achieve regional redundancy.
105+
106+
#### Main Load Balancer
107+
108+
The main Load Balancer is always created by default, it is not possible to disable it.
109+
110+
Here is an example of main Load Balancer configuration:
111+
112+
```yaml
113+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
114+
kind: ScalewayCluster
115+
metadata:
116+
name: my-cluster
117+
namespace: default
118+
spec:
119+
region: fr-par
120+
network:
121+
controlPlaneLoadBalancer:
122+
type: LB-S
123+
port: 443
124+
zone: fr-par-1
125+
ip: 42.42.42.42 # optional
126+
# some fields were omitted...
127+
```
128+
129+
- The `type` field can be updated to migrate the Load Balancer to another type.
130+
- The `port` field specifies the port of the Load Balancer frontend that exposes the kube-apiserver(s).
131+
This field is immutable.
132+
- The `zone` field specifies where the Load Balancer will be created. Must be in the same region
133+
as the `ScalewayCluster` region. This defaults to the first availability zone of the region.
134+
This field is immutable.
135+
- The `ip` field specifies an existing Load Balancer Flexible IP to use when creating
136+
the Load Balancer. If not set, a new IP will be created. This field is immutable.
137+
138+
#### Extra Load Balancers
139+
140+
To specify extra Load Balancers, it is required to also set the `network.controlPlaneDNS` field.
141+
142+
Here is an example that configures two extra Load Balancers in `nl-ams-2` and `nl-ams-3`.
143+
144+
```yaml
145+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
146+
kind: ScalewayCluster
147+
metadata:
148+
name: my-cluster
149+
spec:
150+
region: nl-ams
151+
network:
152+
controlPlaneLoadBalancer:
153+
type: LB-S
154+
zone: nl-ams-1
155+
controlPlaneExtraLoadBalancers:
156+
- type: LB-S
157+
zone: nl-ams-2
158+
- type: LB-S
159+
zone: nl-ams-3
160+
controlPlaneDNS:
161+
domain: subdomain.your-domain.com
162+
name: my-cluster
163+
# some fields were omitted...
164+
```
165+
166+
> [!WARNING]
167+
> You can freely add and remove extra Load Balancers, however, some requests to
168+
> the workload cluster's API server may fail as the Load Balancers are reconfigured.
169+
170+
#### Allowed ranges (ACLs)
171+
172+
The workload cluster's API server is always exposed publicly though the Load Balancer(s).
173+
To prevent unauthorized access to the API server, you may configure some allowed network ranges
174+
in CIDR format. By default, when the `allowedRanges` is unset or set to an empty list (`[]`),
175+
all network ranges are allowed.
176+
177+
```yaml
178+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
179+
kind: ScalewayCluster
180+
metadata:
181+
name: my-cluster
182+
namespace: default
183+
spec:
184+
network:
185+
controlPlaneLoadBalancer:
186+
allowedRanges:
187+
- 42.42.0.0/16
188+
- 1.1.1.1/32
189+
# some fields were omitted...
190+
```
191+
192+
> [!NOTE]
193+
> The public IPs of the nodes and Public Gateways will automatically be allowed.
194+
> No additional configuration is required.
195+
196+
### VPC
197+
198+
#### Private Network
199+
200+
To automatically attach the resources of the cluster to a Private Network, simply
201+
set the `network.privateNetwork.enabled` field to true:
202+
203+
```yaml
204+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
205+
kind: ScalewayCluster
206+
metadata:
207+
name: my-cluster
208+
namespace: default
209+
spec:
210+
network:
211+
privateNetwork:
212+
enabled: true
213+
# id: 11111111-1111-1111-1111-111111111111
214+
# vpcID: 11111111-1111-1111-1111-111111111111
215+
# subnet: 192.168.0.0/22
216+
# some fields were omitted...
217+
```
218+
219+
- The `id` field can be set to use an existing Private Network. If not set, the provider
220+
will create a new Private Network and manage it.
221+
- The `vpcID` field can be set to tell the provider to create a new Private Network inside a
222+
specific VPC. If not set, Private Networks are created in the default VPC.
223+
- The `subnet` field can be set to use a specific subnet. Make sure the subnet does not
224+
overlap with the subnet of another Private Network in the VPC.
225+
226+
#### Public Gateways
227+
228+
To create `ScalewayMachines` without a Public IP, your Private Network must contain
229+
at least one Public Gateway that advertises its default route. You can configure one
230+
manually or let the provider configure that for you:
231+
232+
```yaml
233+
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
234+
kind: ScalewayCluster
235+
metadata:
236+
name: my-cluster
237+
namespace: default
238+
spec:
239+
region: fr-par
240+
network:
241+
privateNetwork:
242+
enabled: true
243+
publicGateways:
244+
- type: VPC-GW-S
245+
zone: fr-par-1
246+
- type: VPC-GW-S
247+
zone: fr-par-2
248+
# ip: 42.42.42.42
249+
# Note: the Public Gateway product is currently not available in fr-par-3.
250+
# some fields were omitted...
251+
```
252+
253+
The `ip` field can be set on the spec of a Public Gateway to use an existing Public IP.
254+
If not set, a new IP will be created.
255+
256+
> [!CAUTION]
257+
> The `publicGateways` field is fully mutable, but changes should be avoided as much as possible.
258+
>
259+
> 🚫📶 Updating existing Public Gateways can lead to a loss of network on the nodes, be
260+
> very careful when updating this field.
261+
>
262+
> 🚮 Updating a Public Gateway will lead to its recreation, which will make its private IP change.
263+
>
264+
> ⏳ Because the default routes are advertised via DHCP, the DHCP leases of the nodes must
265+
> be renewed for changes to be propagated (~24 hours). You can reboot the nodes or
266+
> trigger a rollout restart of the `kubeadmcontrolplanes`/`machinedeployments` to force the propagation.

0 commit comments

Comments
 (0)