docs: add documentation for Talos 0.10

Move default docs generation to 0.10 folder. Signed-off-by: Andrey Smirnov <smirnov.andrey@gmail.com>
siderolabs · Mar 22, 2021 · a5b62f4 · a5b62f4
1 parent ce795f1
commit a5b62f4
Show file tree

Hide file tree

Showing 66 changed files with 17,117 additions and 3 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -665,9 +665,9 @@ RUN protoc \
     /protos/time/*.proto
 
 FROM scratch AS docs
-COPY --from=docs-build /tmp/configuration.md /website/content/docs/v0.9/Reference/
-COPY --from=docs-build /tmp/cli.md /website/content/docs/v0.9/Reference/
-COPY --from=proto-docs-build /tmp/api.md /website/content/docs/v0.9/Reference/
+COPY --from=docs-build /tmp/configuration.md /website/content/docs/v0.10/Reference/
+COPY --from=docs-build /tmp/cli.md /website/content/docs/v0.10/Reference/
+COPY --from=proto-docs-build /tmp/api.md /website/content/docs/v0.10/Reference/
 
 # The talosctl-cni-bundle builds the CNI bundle for talosctl.
 

diff --git a/website/content/docs/v0.10/Bare Metal Platforms/digital-rebar.md b/website/content/docs/v0.10/Bare Metal Platforms/digital-rebar.md
@@ -0,0 +1,160 @@
+---
+title: "Digital Rebar"
+description: "In this guide we will create an Kubernetes cluster with 1 worker node, and 2 controlplane nodes using an existing digital rebar deployment."
+---
+
+## Prerequisites
+
+- 3 nodes (please see [hardware requirements](../../guides/getting-started#system-requirements))
+- Loadbalancer
+- Digital Rebar Server
+- Talosctl access (see [talosctl setup](../../guides/getting-started/talosctl))
+
+## Creating a Cluster
+
+In this guide we will create an Kubernetes cluster with 1 worker node, and 2 controlplane nodes.
+We assume an existing digital rebar 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
+$ talosctl gen config talos-k8s-metal-tutorial https://<load balancer IP or DNS>:<port>
+created init.yaml
+created controlplane.yaml
+created join.yaml
+created talosconfig
+```
+
+> The loadbalancer is used to distribute the load across multiple controlplane nodes.
+> This isn't covered in detail, because we asume some loadbalancing knowledge before hand.
+> If you think this should be added to the docs, please [create a issue](https://github.com/talos-systems/talos/issues).
+
+At this point, you can modify the generated configs to your liking.
+
+#### Validate the Configuration Files
+
+```bash
+$ talosctl validate --config init.yaml --mode metal
+init.yaml is valid for metal mode
+$ talosctl validate --config controlplane.yaml --mode metal
+controlplane.yaml is valid for metal mode
+$ talosctl validate --config join.yaml --mode metal
+join.yaml is valid for metal mode
+```
+
+#### Publishing the Machine Configuration Files
+
+Digital Rebar has a build-in fileserver, which means we can use this feature to expose the talos configuration files.
+We will place `init.yaml`, `controlplane.yaml`, and `worker.yaml` into Digital Rebar file server by using the `drpcli` tools.
+
+Copy the generated files from the step above into your Digital Rebar installation.
+
+```bash
+drpcli file upload <file>.yaml as <file>.yaml
+```
+
+Replacing `<file>` with init, controlplane or worker.
+
+### Download the boot files
+
+Download a recent version of `boot.tar.gz` from [github.](https://github.com/talos-systems/talos/releases/)
+
+Upload to DRB:
+
+```bash
+$ drpcli isos upload boot.tar.gz as talos.tar.gz
+{
+  "Path": "talos.tar.gz",
+  "Size": 96470072
+}
+```
+
+We have some Digital Rebar [example files](https://github.com/talos-systems/talos/tree/master/hack/test/digitalrebar/) in the Git repo you can use to provision Digital Rebar with drpcli.
+
+To apply these configs you need to create them, and then apply them as follow:
+
+```bash
+$ drpcli bootenvs create talos
+{
+  "Available": true,
+  "BootParams": "",
+  "Bundle": "",
+  "Description": "",
+  "Documentation": "",
+  "Endpoint": "",
+  "Errors": [],
+  "Initrds": [],
+  "Kernel": "",
+  "Meta": {},
+  "Name": "talos",
+  "OS": {
+    "Codename": "",
+    "Family": "",
+    "IsoFile": "",
+    "IsoSha256": "",
+    "IsoUrl": "",
+    "Name": "",
+    "SupportedArchitectures": {},
+    "Version": ""
+  },
+  "OnlyUnknown": false,
+  "OptionalParams": [],
+  "ReadOnly": false,
+  "RequiredParams": [],
+  "Templates": [],
+  "Validated": true
+}
+```
+
+```bash
+drpcli bootenvs update talos - < bootenv.yaml
+```
+
+> You need to do this for all files in the example directory.
+> If you don't have access to the `drpcli` tools you can also use the webinterface.
+
+It's important to have a corresponding SHA256 hash matching the boot.tar.gz
+
+#### Bootenv BootParams
+
+We're using some of Digital Rebar build in templating to make sure the machine gets the correct role assigned.
+
+`talos.platform=metal talos.config={{ .ProvisionerURL }}/files/{{.Param \"talos/role\"}}.yaml"`
+
+This is why we also include a `params.yaml` in the example directory to make sure the role is set to one of the following:
+
+- controlplane
+- init
+- worker
+
+The `{{.Param \"talos/role\"}}` then gets populated with one of the above roles.
+
+### Boot the Machines
+
+In the UI of Digital Rebar you need to select the machines you want te provision.
+Once selected, you need to assign to following:
+
+- Profile
+- Workflow
+
+This will provision the Stage and Bootenv with the talos values.
+Once this is done, you can boot the machine.
+
+To understand the boot process, we have a higher level overview located at [metal overview.](/v0.10/en/guides/metal/overview)
+
+### Retrieve the `kubeconfig`
+
+Once everything is running we can retrieve the admin `kubeconfig` by running:
+
+```bash
+talosctl --talosconfig talosconfig config endpoint <control plane 1 IP>
+talosctl --talosconfig talosconfig config node <control plane 1 IP>
+talosctl --talosconfig talosconfig kubeconfig .
+```
diff --git a/website/content/docs/v0.10/Bare Metal Platforms/equinix-metal.md b/website/content/docs/v0.10/Bare Metal Platforms/equinix-metal.md
@@ -0,0 +1,122 @@
+---
+title: "Equinix Metal"
+description: "Creating Talos cluster using Enquinix Metal."
+---
+
+## Prerequisites
+
+This guide assumes the user has a working API token, the Equinix Metal CLI installed, and some familiarity with the CLI.
+
+## Network Booting
+
+To install Talos to a server a working TFTP and iPXE server are needed.
+How this is done varies and is left as an exercise for the user.
+In general this requires a Talos kernel vmlinuz and initramfs.
+These assets can be downloaded from a given [release](https://github.com/talos-systems/talos/releases).
+
+## Special Considerations
+
+### PXE Boot Kernel Parameters
+
+The following is a list of kernel parameters required by Talos:
+
+- `talos.platform`: set this to `packet`
+- `init_on_alloc=1`: required by KSPP
+- `slab_nomerge`: required by KSPP
+- `pti=on`: required by KSPP
+
+### User Data
+
+To configure a Talos you can use the metadata service provide by Equinix Metal.
+It is required to add a shebang to the top of the configuration file.
+The shebang is arbitrary in the case of Talos, and the convention we use is `#!talos`.
+
+## Creating a Cluster via the Equinix Metal CLI
+
+### Control Plane Endpoint
+
+The strategy used for an HA cluster varies and is left as an exercise for the user.
+Some of the known ways are:
+
+- DNS
+- Load Balancer
+- BPG
+
+### Create the Machine Configuration Files
+
+#### Generating Base Configurations
+
+Using the DNS name of the loadbalancer created earlier, generate the base configuration files for the Talos machines:
+
+```bash
+$ talosctl gen config talos-k8s-aws-tutorial https://<load balancer IP or DNS>:<port>
+created init.yaml
+created controlplane.yaml
+created join.yaml
+created talosconfig
+```
+
+Now add the required shebang (e.g. `#!talos`) at the top of `init.yaml`, `controlplane.yaml`, and `join.yaml`
+At this point, you can modify the generated configs to your liking.
+
+#### Validate the Configuration Files
+
+```bash
+talosctl validate --config init.yaml --mode metal
+talosctl validate --config controlplane.yaml --mode metal
+talosctl validate --config join.yaml --mode metal
+```
+
+> Note: Validation of the install disk could potentially fail as the validation
+> is performed on you local machine and the specified disk may not exist.
+
+#### Create the Bootstrap Node
+
+```bash
+packet device create \
+  --project-id $PROJECT_ID \
+  --facility $FACILITY \
+  --ipxe-script-url $PXE_SERVER \
+  --operating-system "custom_ipxe" \
+  --plan $PLAN\
+  --hostname $HOSTNAME\
+  --userdata-file init.yaml
+```
+
+#### Create the Remaining Control Plane Nodes
+
+```bash
+packet device create \
+  --project-id $PROJECT_ID \
+  --facility $FACILITY \
+  --ipxe-script-url $PXE_SERVER \
+  --operating-system "custom_ipxe" \
+  --plan $PLAN\
+  --hostname $HOSTNAME\
+  --userdata-file controlplane.yaml
+```
+
+> Note: The above should be invoked at least twice in order for `etcd` to form quorum.
+
+#### Create the Worker Nodes
+
+```bash
+packet device create \
+  --project-id $PROJECT_ID \
+  --facility $FACILITY \
+  --ipxe-script-url $PXE_SERVER \
+  --operating-system "custom_ipxe" \
+  --plan $PLAN\
+  --hostname $HOSTNAME\
+  --userdata-file join.yaml
+```
+
+### Retrieve the `kubeconfig`
+
+At this point we can retrieve the admin `kubeconfig` by running:
+
+```bash
+talosctl --talosconfig talosconfig config endpoint <control plane 1 IP>
+talosctl --talosconfig talosconfig config node <control plane 1 IP>
+talosctl --talosconfig talosconfig kubeconfig .
+```