diff --git a/docs/website/content/v0.3/en/guides/metal/matchbox.md b/docs/website/content/v0.3/en/guides/metal/matchbox.md index bbcbf3b08..652bdd2c4 100644 --- a/docs/website/content/v0.3/en/guides/metal/matchbox.md +++ b/docs/website/content/v0.3/en/guides/metal/matchbox.md @@ -1,3 +1,191 @@ --- title: Matchbox --- + +## Creating a Cluster + +In this guide we will create an HA Kubernetes cluster with 3 worker nodes. +We assume an existing load balancer, matchbox deployment, and some familiarity with iPXE. + +We leave it up to the user to decide if they would like to use static networking, or DHCP. +The setup and configuration of DHCP will not be covered. + +### Create the Machine Configuration Files + +#### Generating Base Configurations + +Using the DNS name of the load balancer, generate the base configuration files for the Talos machines: + +```bash +$ osctl config generate talos-k8s-metal-tutorial https:// +created init.yaml +created controlplane.yaml +created join.yaml +created talosconfig +``` + +At this point, you can modify the generated configs to your liking. + +#### Validate the Configuration Files + +```bash +$ osctl validate --config init.yaml --mode metal +init.yaml is valid for metal mode +$ osctl validate --config controlplane.yaml --mode metal +controlplane.yaml is valid for metal mode +$ osctl validate --config join.yaml --mode metal +join.yaml is valid for metal mode +``` + +#### Publishing the Machine Configuration Files + +In bare-metal setups it is up to the user to provide the configuration files over HTTP(S). +A special kernel parameter (`talos.config`) must be used to inform Talos about _where_ it should retreive its' configuration file. +To keep things simple we will place `init.yaml`, `controlplane.yaml`, and `join.yaml` into Matchbox's `assets` directory. +This directory is automatically served by Matchbox. + +### Create the Matchbox Configuration Files + +The profiles we will create will reference `vmlinuz`, and `initramfs.xz`. +Download these files from the [release](https://github.com/talos-systems/talos/releases) of your choice, and place them in `/var/lib/matchbox/assets`. + +#### Profiles + +##### The Bootstrap Node + +```json +{ + "id": "init", + "name": "init", + "boot": { + "kernel": "/assets/vmlinuz", + "initrd": ["/assets/initramfs.xz"], + "args": [ + "initrd=initramfs.xz", + "page_poison=1", + "slab_nomerge", + "slub_debug=P", + "pti=on", + "random.trust_cpu=on", + "console=tty0", + "console=ttyS0", + "printk.devkmsg=on", + "talos.platform=metal", + "talos.config=http://matchbox.talos.dev/assets/init.yaml" + ] + } +} +``` + +> Note: Be sure to change `http://matchbox.talos.dev` to the endpoint of your matchbox server. + +##### Additional Control Plane Nodes + +```json +{ + "id": "control-plane", + "name": "control-plane", + "boot": { + "kernel": "/assets/vmlinuz", + "initrd": ["/assets/initramfs.xz"], + "args": [ + "initrd=initramfs.xz", + "page_poison=1", + "slab_nomerge", + "slub_debug=P", + "pti=on", + "random.trust_cpu=on", + "console=tty0", + "console=ttyS0", + "printk.devkmsg=on", + "talos.platform=metal", + "talos.config=http://matchbox.talos.dev/assets/controlplane.yaml" + ] + } +} +``` + +##### Worker Nodes + +```json +{ + "id": "default", + "name": "default", + "boot": { + "kernel": "/assets/vmlinuz", + "initrd": ["/assets/initramfs.xz"], + "args": [ + "initrd=initramfs.xz", + "page_poison=1", + "slab_nomerge", + "slub_debug=P", + "pti=on", + "random.trust_cpu=on", + "console=tty0", + "console=ttyS0", + "printk.devkmsg=on", + "talos.platform=metal", + "talos.config=http://matchbox.talos.dev/assets/join.yaml" + ] + } +} +``` + +#### Groups + +Now, create the following groups, and ensure that the `selector`s are accurate for your specific setup. + +```json +{ + "id": "control-plane-1", + "name": "control-plane-1", + "profile": "init", + "selector": { + ... + } +} +``` + +```json +{ + "id": "control-plane-2", + "name": "control-plane-2", + "profile": "control-plane", + "selector": { + ... + } +} +``` + +```json +{ + "id": "control-plane-3", + "name": "control-plane-3", + "profile": "control-plane", + "selector": { + ... + } +} +``` + +```json +{ + "id": "default", + "name": "default", + "profile": "default" +} +``` + +### Boot the Machines + +Now that we have our configuraton files in place, boot all the machines. +Talos will come up on each machine, grab its' configuration file, and bootstrap itself. + +### Retrieve the `kubeconfig` + +At this point we can retrieve the admin `kubeconfig` by running: + +```bash +osctl --talosconfig talosconfig config target +osctl --talosconfig talosconfig kubeconfig > kubeconfig +```