Skip to content

Commit d124c07

Browse files
smirasmira
committed
docs: update README with usage and compatibility matrix
Just updating the docs to be up date. Signed-off-by: Andrey Smirnov <[email protected]>
1 parent 20792f3 commit d124c07

File tree

1 file changed

+172
-37
lines changed

1 file changed

+172
-37
lines changed

‎README.md‎

Lines changed: 172 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,210 @@
1-
# cluster-api-bootstrap-provider-talos
1+
# Cluster API Bootstrap Provider Talos (CABPT)
22

33
## Intro
44

5-
The Cluster API Bootstrap Provider Talos (CABPT) is a project by [Sidero Labs](https://www.siderolabs.com/) that provides a [Cluster API](https://github.com/kubernetes-sigs/cluster-api)(CAPI) bootstrap provider for use in deploying Talos-based Kubernetes nodes across any environment.
5+
The Cluster API Bootstrap Provider Talos (CABPT) is a project by [Sidero Labs](https://siderolabs.com/) that provides a [Cluster API](https://github.com/kubernetes-sigs/cluster-api) (CAPI) bootstrap provider for use in deploying Talos-based Kubernetes nodes across any environment.
66
Given some basic info, this provider will generate bootstrap configurations for a given machine and reconcile the necessary custom resources for CAPI to pick up the generated data.
77

88
## Corequisites
99

1010
There are a few corequisites and assumptions that go into using this project:
1111

1212
- [Cluster API](https://github.com/kubernetes-sigs/cluster-api)
13+
- [Talos](https://talos.dev/)
1314

14-
## Building and Installing
15+
## Installing
1516

16-
This project can be built simply by running `make release` from the root directory.
17-
Doing so will create a file called `_out/bootstrap-components.yaml`.
18-
If you wish, you can tweak settings by editing the release yaml.
19-
This file can then be installed into your management cluster with `kubectl apply -f _out/bootstrap-components.yaml`.
17+
CABPT provider should be installed alongside with [CACPPT](https://github.com/talos-systems/cluster-api-control-plane-provider-talos) provider.
18+
19+
```shell
20+
clusterctl init --bootstrap talos --control-plane talos --infrastructure <infrastructure provider>
21+
```
22+
23+
## Compatibility
24+
25+
This provider's versions are compatible with the following versions of Cluster API:
26+
27+
| | v1alpha3 (v0.3) | v1alpha4 (v0.4) | v1beta1 (v1.0) |
28+
| -------------- | --------------- | --------------- | -------------- |
29+
| CABPT (v0.3.x) | ✓ | | |
30+
| CABPT (v0.4.x) | | ✓ | |
31+
| CABPT (v0.5.x) | | | ✓ |
32+
33+
This provider's versions are able to install and manage the following versions of Kubernetes:
34+
35+
| | v1.16 | v 1.17 | v1.18 | v1.19 | v1.20 | v1.21 | v1.22 |
36+
| -------------- | ----- | ------ | ----- | ----- | ----- | ----- | ----- |
37+
| CABPT (v0.3.x) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
38+
| CABPT (v0.4.x) | | | | ✓ | ✓ | ✓ | ✓ |
39+
| CABPT (v0.5.x) | | | | ✓ | ✓ | ✓ | ✓ |
40+
41+
This provider's versions are compatible with the following versions of Talos:
42+
43+
| | v0.11 | v0.12 | v0.13 |
44+
| ---------------- | ----- | ----- | ----- |
45+
| CABPT (v0.3.x) | ✓ | ✓ | ✓ |
46+
| CABPT (v0.4.x) | ✓ | ✓ | ✓ |
47+
| CABPT (v0.5.x) | ✓ | ✓ | ✓ |
2048

21-
Note that CABPT should be deployed as part of a set of controllers for Cluster API.
22-
You will need at least the upstream CAPI components and an infrastructure provider for v1alpha2 CAPI capabilities.
49+
CABPT generates machine configuration compatible with Talos version specified in the `talosVersion:` field (see below).
2350

2451
## Usage
2552

26-
CABPT supports a single API type, a TalosConfig.
27-
You can create YAML definitions of a TalosConfig and `kubectl apply` them as part of a larger CAPI cluster deployment.
28-
Below is a bare-minimum example.
53+
CABPT is not used directly, but rather via CACPPT (`TalosControlPlane`) for control plane nodes or via `MachineDeployment` (`MachinePool`) for worker nodes.
54+
In either case, CABPT settings are passed via `TalosConfigTemplate` resource:
2955

30-
A basic config:
56+
```yaml
57+
apiVersion: controlplane.cluster.x-k8s.io/v1alpha3
58+
kind: TalosControlPlane
59+
metadata:
60+
name: mycluster-cp
61+
spec:
62+
controlPlaneConfig:
63+
controlplane:
64+
generateType: controlplane
65+
talosVersion: v0.13
66+
...
67+
```
3168

3269
```yaml
3370
apiVersion: bootstrap.cluster.x-k8s.io/v1alpha3
34-
kind: TalosConfig
71+
kind: TalosConfigTemplate
3572
metadata:
36-
name: talos-0
37-
labels:
38-
cluster.x-k8s.io/cluster-name: talos
73+
name: mycluster-workers
3974
spec:
40-
generateType: init
75+
template:
76+
spec:
77+
generateType: worker
78+
talosVersion: v0.13
4179
```
4280
43-
Note the generateType mentioned above.
44-
This is a required value in the spec for a TalosConfig.
45-
For a no-frills bootstrap config, you can simply specify `init`, `controlplane`, or `worker` depending on what type of Talos node this is.
46-
When creating a TalosConfig this way, you can then retrieve the talosconfig file that allows for osctl interaction with your nodes by doing something like `kubectl get talosconfig -o yaml talos-0 -o jsonpath='{.status.talosConfig}'` after creation.
81+
Fields available in the `TalosConfigTemplate` (and `TalosConfig`) resources:
82+
83+
- `generateType`: Talos machine configuration type to generate (`controlplane`, `init` (deprecated), `worker`) or `none` for user-supplied configuration (see below)
84+
- `talosVersion`: version of Talos to generate machine configuration for (e.g. `v0.13`, patch version might be omitted).
85+
CABPT defaults to the latest supported Talos version, but it can generate configuration compatible with previous versions of Talos.
86+
It is recommended to always set this field explicitly to avoid issues when CABPT is upgraded to the version which supports new Talos version.
87+
- `configPatches` (optional): set of machine configuration patches to apply to the generated configuration.
88+
- `data` (only for `generateType: none`): user-supplied machine configuration.
4789

48-
If you wish to do something more complex, we allow for the ability to supply an entire Talos config file to the resource.
49-
This can be done by setting the generateType to `none` and specifying a `data` field.
50-
This config file can be generated with `talosctl config generate` and the edited to supply the various options you may desire.
51-
This full config is blindly copied from the `data` section of the spec and presented under `.status.bootstrapData` so that the upstream CAPI controllers can see it and make use.
90+
### Generated Machine Configuration
5291

53-
An example of a more complex config:
92+
When `generateType` is set to the machine type of the Talos nodes (`controlplane` for control plane nodes and `worker` for worker nodes), CABPT generates a set of cluster-wide
93+
secrets which are used to provision machine configuration for each node.
94+
Machine configuration generated is compatible with the Talos version set in the `talosVersion` field.
95+
96+
```yaml
97+
spec:
98+
generateType: controlplane
99+
talosVersion: v0.13
100+
```
101+
102+
### User-supplied Machine Configuration
103+
104+
In this mode CABPT passes through machine configuration set in `data` field as bootstrap data to the `Machine`.
105+
Machine configuration can be generated with `talosctl gen config`.
54106

55107
```yaml
56-
apiVersion: bootstrap.cluster.x-k8s.io/v1alpha3
57-
kind: TalosConfig
58-
metadata:
59-
name: talos-0
60-
labels:
61-
cluster.x-k8s.io/cluster-name: talos
62108
spec:
63109
generateType: none
64110
data: |
65111
version: v1alpha1
66112
machine:
67-
type: init
68-
token: xxxxxx
113+
type: controlplane
69114
...
70115
...
71116
...
72117
```
73118

74-
Note that specifying the full config above removes the ability for our bootstrap provider to generate a machine configuration for use.
75-
As such, you should keep track of the machine configuration that's generated when running `talosctl config generate`.
119+
### Configuration Patches
120+
121+
Machine configuration can be customized by applying configuration patches.
122+
Any field of the [Talos machine configuration](https://www.talos.dev/docs/latest/reference/configuration/)
123+
can be overridden on a per-machine basis using this method.
124+
The format of these patches is based on [JSON 6902](http://jsonpatch.com/) that you may be used to in tools like `kustomize`.
125+
126+
```yaml
127+
spec:
128+
generateType: controlplane
129+
talosVersion: v0.13
130+
configPatches:
131+
- op: replace
132+
path: /machine/install
133+
value:
134+
disk: /dev/sda
135+
- op: add
136+
path: /cluster/network/cni
137+
value:
138+
name: custom
139+
urls:
140+
- https://docs.projectcalico.org/v3.18/manifests/calico.yaml
141+
```
142+
143+
### Retrieving `talosconfig`
144+
145+
Client-side `talosconfig` is required to access the cluster using Talos API.
146+
CABPT generates `talosconfig` for generated machine configuration and stores it as `<cluster>-talosconfig` secret in cluster's namespace.
147+
148+
`talosconfig` can be retrieved with:
149+
150+
```shell
151+
kubectl get secret --namespace <cluster-namespace> <cluster-name>-talosconfig -o jsonpath='{.data.talosconfig}' | base64 -d > cluster-talosconfig
152+
talosctl config merge cluster-talosconfig
153+
talosctl -n <IP> version
154+
```
155+
156+
CABPT updates endpoints in the `talosconfig` based on control plane `Machine` addresses.
157+
158+
### Operation
159+
160+
CABPT reconciles `TalosConfig` resources.
161+
Once `TalosConfig` and its associated `Machine` are ready, CABPT generates machine configuration and stores it in the `<machine>-bootstrap-data` Secret.
162+
Kubernetes cluster CA is stored in the `<cluster>-ca` Secret.
163+
Cluster-wide shared secrets are stored in the `<cluster>-talos` Secret.
164+
Client-side Talos API configuration is stored in the `<cluster>-talosconfig` Secret.
165+
166+
As part of its operation, CABPT sets a number of Conditions on the `TalosConfig/Status` resource:
167+
168+
- `DataSecretAvailable`: CABPT generated machine configuration in `<machine>-bootstrap-data` Secret, CABPT unblocks infrastructure provider to boot the `Machine`.
169+
- `ClientConfigAvailableCondition`: CABPT generated Talos client configuration in `<cluster>-talosconfig` Secret.
170+
171+
```shell
172+
$ kubectl describe talosconfig talosconfig-cp-0
173+
Status:
174+
Conditions:
175+
Last Transition Time: 2021-10-25T20:54:09Z
176+
Status: True
177+
Type: Ready
178+
Last Transition Time: 2021-10-25T20:54:09Z
179+
Status: True
180+
Type: ClientConfigAvailable
181+
Last Transition Time: 2021-10-25T20:54:09Z
182+
Status: True
183+
Type: DataSecretAvailable
184+
Data Secret Name: cp-0-bootstrap-data
185+
```
186+
187+
If CABPT fails to perform its operations, it stores error message for the respective Condition.
188+
189+
```shell
190+
Status:
191+
Conditions:
192+
Last Transition Time: 2021-10-25T20:54:09Z
193+
Message: failure applying rfc6902 patches to talos machine config: add operation does not apply: doc is missing path: "/machine/time/servers": missing value
194+
Reason: DataSecretGenerationFailed
195+
Severity: Error
196+
Status: False
197+
```
198+
199+
These statuses are also presented in the `clusterctl describe cluster --show-conditions all` output.
200+
201+
## Building
202+
203+
This project can be built simply by running `make release` from the root directory.
204+
Doing so will create a file called `_out/bootstrap-talos/<version>/bootstrap-components.yaml`.
205+
If you wish, you can tweak settings by editing the release yaml.
206+
This file can then be installed into your management cluster with `kubectl apply -f _out/bootstrap-components.yaml`.
207+
208+
## Support
209+
210+
Join our [Slack](https://slack.dev.talos-systems.io)!

0 commit comments

Comments
 (0)