Skip to content

Commit

Permalink
docs: update documentation for Talos 1.3
Browse files Browse the repository at this point in the history 
This provides What's New, updates documentation with new features,
clarifications and fixes.

I added also simple bare-metal stubs for ISO and PXE methods.

Signed-off-by: Andrey Smirnov <andrey.smirnov@talos-systems.com>
  • Loading branch information
@smira
smira committed Dec 14, 2022
1 parent faf4921 commit 474604c
Show file tree
Hide file tree
Showing 22 changed files with 676 additions and 225 deletions.
5 changes: 0 additions & 5 deletions hack/start-registry-proxies.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,6 @@ docker run -d -p 5001:5000 \
--restart always \
--name registry-registry.k8s.io registry:2

docker run -d -p 5002:5000 \
-e REGISTRY_PROXY_REMOTEURL=https://quay.io \
--restart always \
--name registry-quay.io registry:2.5

docker run -d -p 5003:5000 \
-e REGISTRY_PROXY_REMOTEURL=https://gcr.io \
--restart always \
Expand Down
7 changes: 2 additions & 5 deletions website/content/v1.3/advanced/air-gapped.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,6 @@ Identify all registry prefixes from `talosctl images`, for example:
- `gcr.io`
- `ghcr.io`
- `registry.k8s.io`
- `quay.io`

The `talosctl cluster create` command provides conveniences for common configuration options.
The only required flag for this guide is `--registry-mirror <endpoint>=http://10.5.0.1:6000` which redirects every pull request to the internal registry, this flag
Expand All @@ -117,7 +116,6 @@ $ sudo --preserve-env=HOME talosctl cluster create --provisioner=qemu --install-
--registry-mirror gcr.io=http://10.5.0.1:6000 \
--registry-mirror ghcr.io=http://10.5.0.1:6000 \
--registry-mirror registry.k8s.io=http://10.5.0.1:6000 \
--registry-mirror quay.io=http://10.5.0.1:6000
validating CIDR and reserving IPs
generating PKI and tokens
creating state directory in "/home/user/.talos/clusters/talos-default"
Expand Down Expand Up @@ -157,11 +155,10 @@ machine:
registry.k8s.io:
endpoints:
- http://10.5.0.1:6000/
quay.io:
endpoints:
- http://10.5.0.1:6000/
...
```

Other implementations of Docker registry can be used in place of the Docker `registry` image used above to run the registry.
If required, auth can be configured for the internal registry (and custom TLS certificates if needed).

Please see [pull-through cache guide]({{< relref "../talos-guides/configuration/pull-through-cache" >}}) for an example using Harbor container registry with Talos.
1 change: 0 additions & 1 deletion website/content/v1.3/advanced/developing-talos.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,6 @@ sudo --preserve-env=HOME _out/talosctl-linux-amd64 cluster create \
--cidr=172.20.0.0/24 \
--registry-mirror docker.io=http://172.20.0.1:5000 \
--registry-mirror kregistry.k8s.io=http://172.20.0.1:5001 \
--registry-mirror quay.io=http://172.20.0.1:5002 \
--registry-mirror gcr.io=http://172.20.0.1:5003 \
--registry-mirror ghcr.io=http://172.20.0.1:5004 \
--registry-mirror 127.0.0.1:5005=http://172.20.0.1:5005 \
Expand Down
74 changes: 57 additions & 17 deletions website/content/v1.3/introduction/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -167,10 +167,18 @@ kernel commandline parameters.
See [required kernel parameters]({{< relref "../reference/kernel" >}}).
If creating [EC2 kubernetes clusters]({{< relref "../talos-guides/install/cloud-platforms/aws/" >}}), the configuration file can be passed in as `--user-data` to the `aws ec2 run-instances` command.

In any case, we need to generate the configuration which is to be provided:
In any case, we need to generate the configuration which is to be provided.
We start with generating a secrets bundle which should be saved in a secure location and used
to generate machine or client configuration at any time:

```sh
talosctl gen config cluster-name cluster-endpoint
talosctl gen secrets -o secrets.yaml
```

Now, we can generate the machine configuration for each node:

```sh
talosctl gen config --with-secrets secrets.yaml <cluster-name> <cluster-endpoint>
```

Here, `cluster-name` is an arbitrary name for the cluster, used
Expand All @@ -185,7 +193,7 @@ and port.
For example:

```sh
talosctl gen config my-cluster https://192.168.64.15:6443
$ talosctl gen config --with-secrets secrets.yaml my-cluster https://192.168.64.15:6443
generating PKI and tokens
created /Users/taloswork/controlplane.yaml
created /Users/taloswork/worker.yaml
Expand Down Expand Up @@ -225,7 +233,7 @@ A common example is needing to change the default installation disk.
If you try to to apply the machine config to a node, and get an error like the below, you need to specify a different installation disk:

```sh
talosctl apply-config --insecure -n 192.168.64.8 --file controlplane.yaml
$ talosctl apply-config --insecure -n 192.168.64.8 --file controlplane.yaml
error applying new configuration: rpc error: code = InvalidArgument desc = configuration validation failed: 1 error occurred:
* specified install disk does not exist: "/dev/sda"
```
Expand All @@ -237,7 +245,7 @@ You can verify which disks your nodes have by using the `talosctl disks --insecu
For example:

```sh
talosctl -n 192.168.64.8 disks --insecure
$ talosctl -n 192.168.64.8 disks --insecure
DEV MODEL SERIAL TYPE UUID WWID MODALIAS NAME SIZE BUS_PATH
/dev/vda - - HDD - - virtio:d00000002v00001AF4 - 69 GB /pci0000:00/0000:00:06.0/virtio2/
```
Expand All @@ -251,28 +259,60 @@ install:

to reflect `vda` instead of `sda`.

### Customizing Machine Configuration

The generated machine configuration provides sane defaults for most cases, but machine configuration
can be modified to fit specific needs.

Some machine configuration options are available as flags for the `talosctl gen config` command,
for example setting a specific Kubernetes version:

```sh
talosctl gen config --with-secrets secrets.yaml --kubernetes-version 1.25.4 my-cluster https://192.168.64.15:6443
```

Other modifications are done with [machine configuration patches]({{< relref "../talos-guides/configuration/patching" >}}).
Machine configuration patches can be applied with `talosctl gen config` command:

```sh
talosctl gen config --with-secrets secrets.yaml --config-patch-control-plane @cni.patch my-cluster https://192.168.64.15:6443
```

> Note: `@cni.patch` means that the patch is read from a file named `cni.patch`.
#### Machine Configs as Templates

Individual machines may need different settings: for instance, each may have a
different [static IP address]({{< relref "../advanced/advanced-networking/#static-addressing" >}}).

When different files are needed for machines of the same type, simply
copy the source template (`controlplane.yaml` or `worker.yaml`) and make whatever
modifications are needed.
When different files are needed for machines of the same type, there are two supported flows:

1. Use the `talosctl gen config` command to generate a template, and then patch
the template for each machine with `talosctl machineconfig patch`.
2. Generate each machine configuration file separately with `talosctl gen config` while applying patches.

For example, given a machine configuration patch which sets the static machine hostname:

```yaml
# worker1.patch
machine:
network:
hostname: worker1
```

For instance, if you had three control plane nodes and three worker nodes, you
may do something like this:
Either of the following commands will generate a worker machine configuration file with the hostname set to `worker1`:

```bash
for i in $(seq 0 2); do
cp controlplane.yaml cp$i.yaml
end
for i in $(seq 0 2); do
cp worker.yaml w$i.yaml
end
$ talosctl gen config --with-secrets secrets.yaml my-cluster https://192.168.64.15:6443
created /Users/taloswork/controlplane.yaml
created /Users/taloswork/worker.yaml
created /Users/taloswork/talosconfig
$ talosctl machineconfig patch worker.yaml --patch @worker1.patch --output worker1.yaml
```

Then modify each file as needed.
```sh
talosctl gen config --with-secrets secrets.yaml --config-patch-worker @worker1.patch --output-types worker -o worker1.yaml my-cluster https://192.168.64.15:6443
```

### Apply Configuration

Expand Down
13 changes: 6 additions & 7 deletions website/content/v1.3/introduction/support-matrix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,20 @@ description: "Table of supported Talos Linux versions and respective platforms."
| Talos Version | 1.3 | 1.2 |
|----------------------------------------------------------------------------------------------------------------|------------------------------------|------------------------------------|
| Release Date | 2022-12-01 | 2022-09-01 (1.2.0) |
| End of Community Support | 1.4.0 release (2023-03-01, TBD) | 1.3.0 release (2022-12-01, TBD) |
| End of Community Support | 1.4.0 release (2023-03-15, TBD) | 1.3.0 release (2022-12-15, TBD) |
| Enterprise Support | [offered by Sidero Labs Inc.](https://www.siderolabs.com/support/) | [offered by Sidero Labs Inc.](https://www.siderolabs.com/support/) |
| Kubernetes | 1.26, 1.25, 1.24 | 1.25, 1.24, 1.23 |
| Architecture | amd64, arm64 | amd64, arm64 |
| **Platforms** | | |
| - cloud | AWS, GCP, Azure, Digital Ocean, Exoscale, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud |
| - cloud | AWS, GCP, Azure, Digital Ocean, Exoscale, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud |
| - bare metal | x86: BIOS, UEFI; arm64: UEFI; boot: ISO, PXE, disk image | x86: BIOS, UEFI; arm64: UEFI; boot: ISO, PXE, disk image |
| - virtualized | VMware, Hyper-V, KVM, Proxmox, Xen | VMware, Hyper-V, KVM, Proxmox, Xen |
| - SBCs | Banana Pi M64, Jetson Nano, Libre Computer Board ALL-H3-CC, Nano Pi R4S, Pine64, Pine64 Rock64, Radxa ROCK Pi 4c, Raspberry Pi 4B, Raspberry Pi Compute Module 4 | Banana Pi M64, Jetson Nano, Libre Computer Board ALL-H3-CC, Pine64, Pine64 Rock64, Radxa ROCK Pi 4c, Raspberry Pi 4B, Raspberry Pi Compute Module 4 |
| - local | Docker, QEMU | Docker, QEMU |
| **Cluster API** | | |
| [CAPI Bootstrap Provider Talos](https://github.com/siderolabs/cluster-api-bootstrap-provider-talos) | >= 0.5.5 | >= 0.5.5 |
| [CAPI Control Plane Provider Talos](https://github.com/siderolabs/cluster-api-control-plane-provider-talos) | >= 0.4.9 | >= 0.4.9 |
| [Sidero](https://www.sidero.dev/) | >= 0.5.5 | >= 0.5.5 |
| **UI** | | |
| [Theila](https://github.com/siderolabs/theila) | ✓ | ✓ |
| [CAPI Bootstrap Provider Talos](https://github.com/siderolabs/cluster-api-bootstrap-provider-talos) | >= 0.5.6 | >= 0.5.5 |
| [CAPI Control Plane Provider Talos](https://github.com/siderolabs/cluster-api-control-plane-provider-talos) | >= 0.4.10 | >= 0.4.9 |
| [Sidero](https://www.sidero.dev/) | >= 0.5.7 | >= 0.5.5 |

## Platform Tiers

Expand All @@ -45,6 +43,7 @@ description: "Table of supported Talos Linux versions and respective platforms."

### Tier 3

* Exoscale
* Hetzner
* nocloud
* Oracle Cloud
Expand Down
14 changes: 10 additions & 4 deletions website/content/v1.3/introduction/system-requirements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,21 @@ description: "Hardware requirements for running Talos Linux."
<th class="px-4 py-2">Role</th>
<th class="px-4 py-2">Memory</th>
<th class="px-4 py-2">Cores</th>
<th class="px-4 py-2">System Disk</th>
</tr>
</thead>
<tbody>
<tr>
<td class="border px-4 py-2">Control Plane</td>
<td class="border px-4 py-2">2GB</td>
<td class="border px-4 py-2">2 GiB</td>
<td class="border px-4 py-2">2</td>
<td class="border px-4 py-2">10 GiB</td>
</tr>
<tr class="bg-gray-100">
<td class="border px-4 py-2">Worker</td>
<td class="border px-4 py-2">1GB</td>
<td class="border px-4 py-2">1 GiB</td>
<td class="border px-4 py-2">1</td>
<td class="border px-4 py-2">10 GiB</td>
</tr>
</tbody>
</table>
Expand All @@ -36,18 +39,21 @@ description: "Hardware requirements for running Talos Linux."
<th class="px-4 py-2">Role</th>
<th class="px-4 py-2">Memory</th>
<th class="px-4 py-2">Cores</th>
<th class="px-4 py-2">System Disk</th>
</tr>
</thead>
<tbody>
<tr>
<td class="border px-4 py-2">Control Plane</td>
<td class="border px-4 py-2">4GB</td>
<td class="border px-4 py-2">4 GiB</td>
<td class="border px-4 py-2">4</td>
<td class="border px-4 py-2">100 GiB</td>
</tr>
<tr class="bg-gray-100">
<td class="border px-4 py-2">Worker</td>
<td class="border px-4 py-2">2GB</td>
<td class="border px-4 py-2">2 GiB</td>
<td class="border px-4 py-2">2</td>
<td class="border px-4 py-2">100 GiB</td>
</tr>
</tbody>
</table>
Expand Down
75 changes: 0 additions & 75 deletions website/content/v1.3/introduction/theila.md
View file

This file was deleted.

0 comments on commit 474604c

Please sign in to comment.