Skip to content

Commit

Permalink
docs: make Talos 0.13 docs latest, update documentation
Browse files Browse the repository at this point in the history 
Update What's New, add videos, some details.

Signed-off-by: Andrey Smirnov <andrey.smirnov@talos-systems.com>
  • Loading branch information
@smira
smira committed Oct 12, 2021
1 parent 31b6e39 commit 2412930
Show file tree
Hide file tree
Showing 8 changed files with 227 additions and 42 deletions.
2 changes: 1 addition & 1 deletion website/content/docs/v0.12/Introduction/support-matrix.md
View file
Expand Up @@ -6,7 +6,7 @@ weight: 6
| Talos Version | 0.12 | 0.11 |
|----------------------------------------------------------------------------------------------------------------|------------------------------------|------------------------------------|
| Release Date | 2021-08-30 | 2021-07-08 (0.11.0) |
| End of Community Support | 0.13.0 release (2021-10-15, TBD) | 2021-09-15 |
| End of Community Support | 2021-10-12 | 2021-09-15 |
| Enterprise Support | [offered by Talos Systems Inc.](https://www.talos-systems.com/support/) |
| Kubernetes | 1.22, 1.21, 1.20 | 1.21, 1.20, 1.19 |
| Architecture | amd64, arm64 |
Expand Down
86 changes: 72 additions & 14 deletions website/content/docs/v0.13/Guides/discovery.md
View file
Expand Up @@ -2,56 +2,114 @@
title: "Discovery"
---

## Video Walkthrough

To see a live demo of Cluster Discovery, see the video below:

<iframe width="560" height="315" src="https://www.youtube.com/embed/GCBTrHhjawY" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Registries

Peers are aggregated from a number of optional registries.
By default, Talos will use the `kubernetes` and `discovery` registries.
By default, Talos will use the `kubernetes` and `service` registries.
Either one can be disabled.
To disable a registry, set `disabled` to `true` (this options is the same for all registries):
For example, to disable the `discovery` registry:
To disable a registry, set `disabled` to `true` (this option is the same for all registries):
For example, to disable the `service` registry:

```yaml
cluster:
discovery:
enabled: true
registries:
discovery:
service:
disabled: true
```

Disabling all registries effectively disables member discovery altogether.

> As of v0.13, Talos supports the `kubernetes` and `discovery` registries.
> As of v0.13, Talos supports the `kubernetes` and `service` registries.
`Kubernetes` registry uses Kubernetes `Node` resource data and additional Talos annotations:

```sh
$ kubectl describe node <nodename>
Annotations: cluster.talos.dev/node-id: Utoh3O0ZneV0kT2IUBrh7TgdouRcUW2yzaaMl4VXnCd
networking.talos.dev/assigned-prefixes: 10.244.0.0/32,10.244.0.1/24
networking.talos.dev/self-ips: 172.20.0.2,fd83:b1f7:fcb5:2802:8c13:71ff:feaf:7c94
...
```

`Service` registry uses external [Discovery Service](../../learn-more/discovery/) to exchange encrypted information about cluster members.

## Resource Definitions

Talos v0.13 introduces seven new resources that can be used to introspect the new discovery and KubeSpan features.

### Discovery

#### Identities

The node's unique identity (base62 encoded random 32 bytes) can be obtained with:

> Note: Using base62 allows the ID to be URL encoded without having to use the ambiguous URL-encoding version of base64.
```sh
$ talosctl get identities -o yaml
...
spec:
nodeId: Utoh3O0ZneV0kT2IUBrh7TgdouRcUW2yzaaMl4VXnCd
```

Node identity is used as the unique `Affiliate` identifier.

Node identity resource is preserved in the `STATE` partition in `node-identity.yaml` file.
Node identity is preserved across reboots and upgrades, but it is regenerated if the node is reset (wiped).

#### Affiliates

An affiliate is a proposed member attributed to the fact that the node has the same cluster ID and secret.

```sh
talosctl get affiliates
$ talosctl get affiliates
ID VERSION HOSTNAME MACHINE TYPE ADDRESSES
2VfX3nu67ZtZPl57IdJrU87BMjVWkSBJiL9ulP9TCnF 2 talos-default-master-2 controlplane ["172.20.0.3","fd83:b1f7:fcb5:2802:986b:7eff:fec5:889d"]
6EVq8RHIne03LeZiJ60WsJcoQOtttw1ejvTS6SOBzhUA 2 talos-default-worker-1 worker ["172.20.0.5","fd83:b1f7:fcb5:2802:cc80:3dff:fece:d89d"]
NVtfu1bT1QjhNq5xJFUZl8f8I8LOCnnpGrZfPpdN9WlB 2 talos-default-worker-2 worker ["172.20.0.6","fd83:b1f7:fcb5:2802:2805:fbff:fe80:5ed2"]
Utoh3O0ZneV0kT2IUBrh7TgdouRcUW2yzaaMl4VXnCd 4 talos-default-master-1 controlplane ["172.20.0.2","fd83:b1f7:fcb5:2802:8c13:71ff:feaf:7c94"]
b3DebkPaCRLTLLWaeRF1ejGaR0lK3m79jRJcPn0mfA6C 2 talos-default-master-3 controlplane ["172.20.0.4","fd83:b1f7:fcb5:2802:248f:1fff:fe5c:c3f"]
```

#### Members
One of the `Affiliates` with the `ID` matching node identity is populated from the node data, other `Affiliates` are pulled from the registries.
Enabled discovery registries run in parallel and discovered data is merged to build the list presented above.

A member is an affiliate that has been approved to join the cluster.
The members of the cluster can be obtained with:
Details about data coming from each registry can be queried from the `cluster-raw` namespace:

```sh
talosctl get members
$ talosctl get affiliates --namespace=cluster-raw
ID VERSION HOSTNAME MACHINE TYPE ADDRESSES
k8s/2VfX3nu67ZtZPl57IdJrU87BMjVWkSBJiL9ulP9TCnF 3 talos-default-master-2 controlplane ["172.20.0.3","fd83:b1f7:fcb5:2802:986b:7eff:fec5:889d"]
k8s/6EVq8RHIne03LeZiJ60WsJcoQOtttw1ejvTS6SOBzhUA 2 talos-default-worker-1 worker ["172.20.0.5","fd83:b1f7:fcb5:2802:cc80:3dff:fece:d89d"]
k8s/NVtfu1bT1QjhNq5xJFUZl8f8I8LOCnnpGrZfPpdN9WlB 2 talos-default-worker-2 worker ["172.20.0.6","fd83:b1f7:fcb5:2802:2805:fbff:fe80:5ed2"]
k8s/b3DebkPaCRLTLLWaeRF1ejGaR0lK3m79jRJcPn0mfA6C 3 talos-default-master-3 controlplane ["172.20.0.4","fd83:b1f7:fcb5:2802:248f:1fff:fe5c:c3f"]
service/2VfX3nu67ZtZPl57IdJrU87BMjVWkSBJiL9ulP9TCnF 23 talos-default-master-2 controlplane ["172.20.0.3","fd83:b1f7:fcb5:2802:986b:7eff:fec5:889d"]
service/6EVq8RHIne03LeZiJ60WsJcoQOtttw1ejvTS6SOBzhUA 26 talos-default-worker-1 worker ["172.20.0.5","fd83:b1f7:fcb5:2802:cc80:3dff:fece:d89d"]
service/NVtfu1bT1QjhNq5xJFUZl8f8I8LOCnnpGrZfPpdN9WlB 20 talos-default-worker-2 worker ["172.20.0.6","fd83:b1f7:fcb5:2802:2805:fbff:fe80:5ed2"]
service/b3DebkPaCRLTLLWaeRF1ejGaR0lK3m79jRJcPn0mfA6C 14 talos-default-master-3 controlplane ["172.20.0.4","fd83:b1f7:fcb5:2802:248f:1fff:fe5c:c3f"]
```

#### Identities
Each `Affiliate` ID is prefixed with `k8s/` for data coming from the Kubernetes registry and with `service/` for data coming from the discovery service.

The node's unique identity (base62 encoded random 32 bytes) can be obtained with:
#### Members

> Note: Using base62 allows the ID to be URL encoded without having to use the ambiguous URL-encoding version of base64.
A member is an affiliate that has been approved to join the cluster.
The members of the cluster can be obtained with:

```sh
talosctl get identities
$ talosctl get members
ID VERSION HOSTNAME MACHINE TYPE OS ADDRESSES
talos-default-master-1 2 talos-default-master-1 controlplane Talos (v0.13.0) ["172.20.0.2","fd83:b1f7:fcb5:2802:8c13:71ff:feaf:7c94"]
talos-default-master-2 1 talos-default-master-2 controlplane Talos (v0.13.0) ["172.20.0.3","fd83:b1f7:fcb5:2802:986b:7eff:fec5:889d"]
talos-default-master-3 1 talos-default-master-3 controlplane Talos (v0.13.0) ["172.20.0.4","fd83:b1f7:fcb5:2802:248f:1fff:fe5c:c3f"]
talos-default-worker-1 1 talos-default-worker-1 worker Talos (v0.13.0) ["172.20.0.5","fd83:b1f7:fcb5:2802:cc80:3dff:fece:d89d"]
talos-default-worker-2 1 talos-default-worker-2 worker Talos (v0.13.0) ["172.20.0.6","fd83:b1f7:fcb5:2802:2805:fbff:fe80:5ed2"]
```
83 changes: 70 additions & 13 deletions website/content/docs/v0.13/Guides/kubespan.md
View file
Expand Up @@ -5,6 +5,18 @@ title: "KubeSpan"
KubeSpan is a feature of Talos that automates the setup and maintainance of a full mesh [WireGuard](https://www.wireguard.com) network for your cluster, giving you the ablility to operate hybrid Kuberentes clusters that can span the edge, datacenter, and cloud.
Management of keys and discovery of peers can be completely automated for a zero-touch experience that makes it simple and easy to create hybrid clusters.

## Video Walkthrough

To learn more about KubeSpan, see the video below:

<iframe width="560" height="315" src="https://www.youtube.com/embed/lPl3u9BN7j4" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

To see a live demo of KubeSpan, see one the videos below:

<iframe width="560" height="315" src="https://www.youtube.com/embed/RRk8gYzRHJg" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

<iframe width="560" height="315" src="https://www.youtube.com/embed/sBKIFLhC9MQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Enabling

### Creating a New Cluster
Expand Down Expand Up @@ -92,36 +104,81 @@ cluster:

## Resource Definitions

### KubeSpanPeerSpecs
### KubeSpanIdentities

A node's WireGuard peers can be obtained with:
A node's WireGuard identities can be obtained with:

```sh
talosctl get kubespanpeerspecs
$ talosctl get kubespanidentities -o yaml
...
spec:
address: fd83:b1f7:fcb5:2802:8c13:71ff:feaf:7c94/128
subnet: fd83:b1f7:fcb5:2802::/64
privateKey: gNoasoKOJzl+/B+uXhvsBVxv81OcVLrlcmQ5jQwZO08=
publicKey: NzW8oeIH5rJyY5lefD9WRoHWWRr/Q6DwsDjMX+xKjT4=
```

### KubeSpanEndpoints
Talos automatically configures unique IPv6 address for each node in the cluster-specific IPv6 ULA prefix.

A node's WireGuard endpoints (peer addresses) can be obtained with:
Wireguard private key is generated for the node, private key never leaves the node while public key is published through the cluster discovery.

`KubeSpanIdentity` is persisted across reboots and upgrades in `STATE` partition in the file `kubespan-identity.yaml`.

### KubeSpanPeerSpecs

A node's WireGuard peers can be obtained with:

```sh
talosctl get kubespanendpoints
$ talosctl get kubespanpeerspecs
ID VERSION LABEL ENDPOINTS
06D9QQOydzKrOL7oeLiqHy9OWE8KtmJzZII2A5/FLFI= 2 talos-default-master-2 ["172.20.0.3:51820"]
THtfKtfNnzJs1nMQKs5IXqK0DFXmM//0WMY+NnaZrhU= 2 talos-default-master-3 ["172.20.0.4:51820"]
nVHu7l13uZyk0AaI1WuzL2/48iG8af4WRv+LWmAax1M= 2 talos-default-worker-2 ["172.20.0.6:51820"]
zXP0QeqRo+CBgDH1uOBiQ8tA+AKEQP9hWkqmkE/oDlc= 2 talos-default-worker-1 ["172.20.0.5:51820"]
```

The endpoint ID is the base64 encoded WireGuard public key obtained with `talosctl get kubespanidentities`.
The peer ID is the Wireguard public key.
`KubeSpanPeerSpecs` are built from the cluster discovery data.

### KubeSpanIdentities
### KubeSpanPeerStatuses

A node's WireGuard identities can be obtained with:
The status of a node's WireGuard peers can be obtained with:

```sh
talosctl get kubespanidentities
$ talosctl get kubespanpeerstatuses
ID VERSION LABEL ENDPOINT STATE RX TX
06D9QQOydzKrOL7oeLiqHy9OWE8KtmJzZII2A5/FLFI= 63 talos-default-master-2 172.20.0.3:51820 up 15043220 17869488
THtfKtfNnzJs1nMQKs5IXqK0DFXmM//0WMY+NnaZrhU= 62 talos-default-master-3 172.20.0.4:51820 up 14573208 18157680
nVHu7l13uZyk0AaI1WuzL2/48iG8af4WRv+LWmAax1M= 60 talos-default-worker-2 172.20.0.6:51820 up 130072 46888
zXP0QeqRo+CBgDH1uOBiQ8tA+AKEQP9hWkqmkE/oDlc= 60 talos-default-worker-1 172.20.0.5:51820 up 130044 46556
```

### KubeSpanPeerStatuses
KubeSpan peer status includes following information:

The status of a node's WireGuard peers can be obtained with:
* the actual endpoint used for peer communication
* link state:
* `unknown`: the endpoint was just changed, link state is not known yet
* `up`: there is a recent handshake from the peer
* `down`: there is no handshake from the peer
* number of bytes sent/received over the Wireguard link with the peer

If the connection state goes `down`, Talos will be cycling through the available endpoints until it finds the one which works.

Peer status information is updated every 30 seconds.

### KubeSpanEndpoints

A node's WireGuard endpoints (peer addresses) can be obtained with:

```sh
talosctl get kubespanpeerstatuses
$ talosctl get kubespanendpoints
ID VERSION ENDPOINT AFFILIATE ID
06D9QQOydzKrOL7oeLiqHy9OWE8KtmJzZII2A5/FLFI= 1 172.20.0.3:51820 2VfX3nu67ZtZPl57IdJrU87BMjVWkSBJiL9ulP9TCnF
THtfKtfNnzJs1nMQKs5IXqK0DFXmM//0WMY+NnaZrhU= 1 172.20.0.4:51820 b3DebkPaCRLTLLWaeRF1ejGaR0lK3m79jRJcPn0mfA6C
nVHu7l13uZyk0AaI1WuzL2/48iG8af4WRv+LWmAax1M= 1 172.20.0.6:51820 NVtfu1bT1QjhNq5xJFUZl8f8I8LOCnnpGrZfPpdN9WlB
zXP0QeqRo+CBgDH1uOBiQ8tA+AKEQP9hWkqmkE/oDlc= 1 172.20.0.5:51820 6EVq8RHIne03LeZiJ60WsJcoQOtttw1ejvTS6SOBzhUA
```

The endpoint ID is the base64 encoded WireGuard public key.

The observed endpoints are submitted back to the discovery service (if enabled) so that other peers can try additional endpoints to establish the connection.
11 changes: 9 additions & 2 deletions website/content/docs/v0.13/Guides/upgrading-talos.md
View file
Expand Up @@ -14,7 +14,7 @@ To see a live demo of this writeup, see the video below:

### After Upgrade to 0.13

TBD
No actions required.

## `talosctl` Upgrade

Expand Down Expand Up @@ -56,4 +56,11 @@ future.

## Machine Configuration Changes

TBD
There are no required machine configuration changes when upgrading to Talos 0.13, but there are several new features
which should be enabled explicitly:

* [cluster membership discovery](../../guides/discovery/)
* [KubeSpan](../../guides/kubespan/)

These features require `.cluster.id` and `.cluster.secret` configuration fields to be set (introduced in Talos 0.12),
please see the [v0.12 upgrade docs](../../../v0.12/guides/upgrading-talos/) for details.
10 changes: 5 additions & 5 deletions website/content/docs/v0.13/Introduction/support-matrix.md
View file
Expand Up @@ -5,10 +5,10 @@ weight: 6

| Talos Version | 0.13 | 0.12 |
|----------------------------------------------------------------------------------------------------------------|------------------------------------|------------------------------------|
| Release Date | 2021-10-12 (TBD) | 2021-08-31 (0.12.0) |
| Release Date | 2021-10-12 | 2021-08-31 (0.12.0) |
| End of Community Support | 0.14.0 release (2021-12-15, TBD) | 2021-10-12 |
| Enterprise Support | [offered by Talos Systems Inc.](https://www.talos-systems.com/support/) |
| Kubernetes | 1.22, 1.21, 1.20 | 1.22, 1.21, 1.20 |
| Enterprise Support | [offered by Sidero Labs Inc.](https://www.siderolabs.com/support/) |
| Kubernetes | 1.22, 1.21, 1.20 | 1.22, 1.21, 1.20 |
| Architecture | amd64, arm64 |
| **Platforms** | | |
| - cloud | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Scaleway, Vultr, Upcloud | AWS, GCP, Azure, Digital Ocean, OpenStack |
Expand All @@ -17,8 +17,8 @@ weight: 6
| - SBCs | Raspberry Pi4, Banana Pi M64, Pine64, and other |
| - local | Docker, QEMU |
| **Cluster API** | | |
| [CAPI Bootstrap Provider Talos](https://github.com/talos-systems/cluster-api-bootstrap-provider-talos) | >= 0.3.0 | >= 0.3.0 |
| [CAPI Control Plane Provider Talos](https://github.com/talos-systems/cluster-api-control-plane-provider-talos) | >= 0.1.1 | >= 0.1.1 |
| [CAPI Bootstrap Provider Talos](https://github.com/talos-systems/cluster-api-bootstrap-provider-talos) | >= 0.4.1 | >= 0.3.0 |
| [CAPI Control Plane Provider Talos](https://github.com/talos-systems/cluster-api-control-plane-provider-talos) | >= 0.3.0 | >= 0.1.1 |
| [Sidero](https://www.sidero.dev/) | >= 0.3.0 | >= 0.3.0 |
| **UI** | | |
| [Theila](https://github.com/talos-systems/theila) | ✓ | ✓ |
Expand Down

0 comments on commit 2412930

Please sign in to comment.