Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/siderolabs/cluster-api-bootstrap-provider-talos
A cluster-api bootstrap provider for deploying Talos clusters.
https://github.com/siderolabs/cluster-api-bootstrap-provider-talos
Last synced: about 1 month ago
JSON representation
A cluster-api bootstrap provider for deploying Talos clusters.
- Host: GitHub
- URL: https://github.com/siderolabs/cluster-api-bootstrap-provider-talos
- Owner: siderolabs
- License: mpl-2.0
- Created: 2019-10-11T20:41:54.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-23T15:48:44.000Z (3 months ago)
- Last Synced: 2024-10-21T02:58:14.182Z (about 2 months ago)
- Language: Go
- Homepage: https://www.talos-systems.com
- Size: 558 KB
- Stars: 109
- Watchers: 7
- Forks: 28
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-repositories - siderolabs/cluster-api-bootstrap-provider-talos - A cluster-api bootstrap provider for deploying Talos clusters. (Go)
README
# Cluster API Bootstrap Provider Talos (CABPT)
## Intro
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.
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.
## Corequisites
There are a few corequisites and assumptions that go into using this project:
- [Cluster API](https://github.com/kubernetes-sigs/cluster-api)
- [Talos](https://talos.dev/)
## Installing
CABPT provider should be installed alongside with [CACPPT](https://github.com/siderolabs/cluster-api-control-plane-provider-talos) provider.
```shell
clusterctl init --bootstrap talos --control-plane talos --infrastructure
```
If you encounter the following error, this is caused by a rename of our GitHub org from `talos-systems` to `siderolabs`.
```bash
$ clusterctl init -b talos -c talos -i sidero
Fetching providers
Error: failed to get provider components for the "talos" provider: target namespace can't be defaulted. Please specify a target namespace
```
This can be worked around by adding the following to `~/.cluster-api/clusterctl.yaml` and rerunning the init command:
```yaml
providers:
- name: "talos"
url: "https://github.com/siderolabs/cluster-api-bootstrap-provider-talos/releases/latest/bootstrap-components.yaml"
type: "BootstrapProvider"
- name: "talos"
url: "https://github.com/siderolabs/cluster-api-control-plane-provider-talos/releases/latest/control-plane-components.yaml"
type: "ControlPlaneProvider"
- name: "sidero"
url: "https://github.com/siderolabs/sidero/releases/latest/infrastructure-components.yaml"
type: "InfrastructureProvider"
```
## Compatibility
This provider's versions are compatible with the following versions of Cluster API:
| | v1alpha3 (v0.3) | v1alpha4 (v0.4) | v1beta1 (v1.x) |
| -------------- | --------------- | --------------- | -------------- |
| CABPT (v0.5.x) | | | ✓ |
| CABPT (v0.6.x) | | | ✓ |
This provider's versions are able to install and manage the following versions of Kubernetes:
| | v1.19 | v1.20 | v1.21 | v1.22 | v1.23 | v1.24 | v1.25 | v1.26 | v1.27 | v1.28 | v1.29 | v1.30 | v1.31 |
| -------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |
| CABPT (v0.5.x) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | | |
| CABPT (v0.6.x) | | | | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
This provider's versions are compatible with the following versions of Talos:
| | v1.0 | v1.1 | v1.2 | v1.3 | v1.4 | v1.5 | v1.6 | v1.7 | v1.8 |
| ---------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |
| CABPT (v0.5.x) | ✓ | ✓ | ✓ | ✓ | | | | | |
| CABPT (v0.6.x) | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
> Note: CABPT is not compatible with multi-document Talos Linux machine configuration, as it relies on JSON patch to apply configuration patches.
CABPT generates machine configuration compatible with Talos Linux version specified in the `talosVersion:` field (see below).
## Usage
CABPT is not used directly, but rather via CACPPT (`TalosControlPlane`) for control plane nodes or via `MachineDeployment` (`MachinePool`) for worker nodes.
In either case, CABPT settings are passed via `TalosConfigTemplate` resource:
```yaml
apiVersion: controlplane.cluster.x-k8s.io/v1alpha3
kind: TalosControlPlane
metadata:
name: mycluster-cp
spec:
controlPlaneConfig:
controlplane:
generateType: controlplane
talosVersion: v1.6
...
```
```yaml
apiVersion: bootstrap.cluster.x-k8s.io/v1alpha3
kind: TalosConfigTemplate
metadata:
name: mycluster-workers
spec:
template:
spec:
generateType: worker
talosVersion: v1.6
```
Fields available in the `TalosConfigTemplate` (and `TalosConfig`) resources:
- `generateType`: Talos machine configuration type to generate (`controlplane`, `init` (deprecated), `worker`) or `none` for user-supplied configuration (see below)
- `talosVersion`: version of Talos to generate machine configuration for (e.g. `v1.0`, patch version might be omitted).
CABPT defaults to the latest supported Talos version, but it can generate configuration compatible with previous versions of Talos.
It is recommended to always set this field explicitly to avoid issues when CABPT is upgraded to the version which supports new Talos version.
- `configPatches` (optional): set of machine configuration patches to apply to the generated configuration.
- `data` (only for `generateType: none`): user-supplied machine configuration.
- `hostname` (optional): configure hostname in the generate machine configuration:
- `source` (`MachineName`): set the hostname in the generated machine configuration to the `Machine` name (not supported with `MachinePool` deployments)
### Generated Machine Configuration
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
secrets which are used to provision machine configuration for each node.
Machine configuration generated is compatible with the Talos version set in the `talosVersion` field.
```yaml
spec:
generateType: controlplane
talosVersion: v1.5
```
### User-supplied Machine Configuration
In this mode CABPT passes through machine configuration set in `data` field as bootstrap data to the `Machine`.
Machine configuration can be generated with `talosctl gen config`.
```yaml
spec:
generateType: none
data: |
version: v1alpha1
machine:
type: controlplane
...
...
...
```
### Configuration Patches
Machine configuration can be customized by applying configuration patches.
Any field of the [Talos machine configuration](https://www.talos.dev/docs/latest/reference/configuration/)
can be overridden on a per-machine basis using this method.
There are two [patch formats](https://www.talos.dev/latest/talos-guides/configuration/patching/) supported by CABPT:
- the [JSON 6902](http://jsonpatch.com/) format that you may be used to in tools like `kustomize`;
- strategic merge patches which look like incomplete machine configuration documents.
See Talos Linux documentation for more information on patching.
JSON 6902 patch:
```yaml
spec:
generateType: controlplane
talosVersion: v1.6
configPatches:
- op: replace
path: /machine/install
value:
disk: /dev/sda
- op: add
path: /cluster/network/cni
value:
name: custom
urls:
- https://docs.projectcalico.org/v3.18/manifests/calico.yaml
```
Strategic merge patch:
```yaml
spec:
generateType: controlplane
talosVersion: v1.6
strategicPatches:
- |
machine:
install:
disk: /dev/sda
- |
cluster:
network:
cni:
name: custom
urls:
- https://docs.projectcalico.org/v3.18/manifests/calico.yaml
```
### Retrieving `talosconfig`
Client-side `talosconfig` is required to access the cluster using Talos API.
CABPT generates `talosconfig` for generated machine configuration and stores it as `-talosconfig` secret in cluster's namespace.
`talosconfig` can be retrieved with:
```shell
kubectl get secret --namespace -talosconfig -o jsonpath='{.data.talosconfig}' | base64 -d > cluster-talosconfig
talosctl config merge cluster-talosconfig
talosctl -n version
```
CABPT updates endpoints in the `talosconfig` based on control plane `Machine` addresses.
### Operation
CABPT reconciles `TalosConfig` resources.
Once `TalosConfig` and its associated `Machine` are ready, CABPT generates machine configuration and stores it in the `-bootstrap-data` Secret.
Kubernetes cluster CA is stored in the `-ca` Secret.
Cluster-wide shared secrets are stored in the `-talos` Secret.
Client-side Talos API configuration is stored in the `-talosconfig` Secret.
As part of its operation, CABPT sets a number of Conditions on the `TalosConfig/Status` resource:
- `DataSecretAvailable`: CABPT generated machine configuration in `-bootstrap-data` Secret, CABPT unblocks infrastructure provider to boot the `Machine`.
- `ClientConfigAvailableCondition`: CABPT generated Talos client configuration in `-talosconfig` Secret.
```shell
$ kubectl describe talosconfig talosconfig-cp-0
Status:
Conditions:
Last Transition Time: 2021-10-25T20:54:09Z
Status: True
Type: Ready
Last Transition Time: 2021-10-25T20:54:09Z
Status: True
Type: ClientConfigAvailable
Last Transition Time: 2021-10-25T20:54:09Z
Status: True
Type: DataSecretAvailable
Data Secret Name: cp-0-bootstrap-data
```
If CABPT fails to perform its operations, it stores error message for the respective Condition.
```shell
Status:
Conditions:
Last Transition Time: 2021-10-25T20:54:09Z
Message: failure applying rfc6902 patches to talos machine config: add operation does not apply: doc is missing path: "/machine/time/servers": missing value
Reason: DataSecretGenerationFailed
Severity: Error
Status: False
```
These statuses are also presented in the `clusterctl describe cluster --show-conditions all` output.
## Building
This project can be built simply by running `make release` from the root directory.
Doing so will create a file called `_out/bootstrap-talos//bootstrap-components.yaml`.
If you wish, you can tweak settings by editing the release yaml.
This file can then be installed into your management cluster with `kubectl apply -f _out/bootstrap-components.yaml`.
## Support
Join our [Slack](https://slack.dev.talos-systems.io)!