docs: reorganize documentation

Make improvements to help documentation discoverability and categorization. Ensure all content pages have a description. Ensure all link are replaced with Hugo shortcode. Ensure all moved pages have an alias so redirects work. Signed-off-by: Tim Jones <[email protected]>
siderolabs · Apr 13, 2022 · fa57b5d · fa57b5d
1 parent a91eb93
commit fa57b5d
Show file tree

Hide file tree

Showing 227 changed files with 675 additions and 266 deletions.
diff --git a/website/content/v1.0/_index.md b/website/content/v1.0/_index.md
@@ -16,9 +16,9 @@ menu: main
 Welcome to the Talos documentation.
 If you are just getting familiar with Talos, we recommend starting here:
 
-- [What is Talos](introduction/what-is-talos/): a quick description of Talos
-- [Quickstart](introduction/quickstart/): the fastest way to get a Talos cluster up and running
-- [Getting Started](introduction/getting-started/): a long-form, guided tour of getting a full Talos cluster deployed
+- [What is Talos]({{< relref "introduction/what-is-talos" >}}): a quick description of Talos
+- [Quickstart]({{< relref "introduction/quickstart" >}}): the fastest way to get a Talos cluster up and running
+- [Getting Started]({{< relref "introduction/getting-started" >}}): a long-form, guided tour of getting a full Talos cluster deployed
 
 ## Open Source
 

diff --git a/website/content/v1.0/advanced/_index.md b/website/content/v1.0/advanced/_index.md
@@ -0,0 +1,4 @@
+---
+title: "Advanced Guides"
+weight: 60
+---
diff --git a/...ontent/v1.1/guides/advanced-networking.md → ...tent/v1.0/advanced/advanced-networking.md b/...ontent/v1.1/guides/advanced-networking.md → ...tent/v1.0/advanced/advanced-networking.md
@@ -1,5 +1,8 @@
 ---
 title: "Advanced Networking"
+description: "How to configure advanced networking options on Talos Linux."
+aliases:
+  - ../guides/advanced-networking
 ---
 
 ## Static Addressing

diff --git a/website/content/v1.0/guides/air-gapped.md → website/content/v1.0/advanced/air-gapped.md b/website/content/v1.0/guides/air-gapped.md → website/content/v1.0/advanced/air-gapped.md
@@ -1,16 +1,19 @@
 ---
-title: Air-gapped Environments
+title: "Air-gapped Environments"
+description: "Setting up Talos Linux to work in environments with no internet access."
+aliases:
+  - ../guides/air-gapped
 ---
 
 In this guide we will create a Talos cluster running in an air-gapped environment with all the required images being pulled from an internal registry.
-We will use the [QEMU](../../local-platforms/qemu/) provisioner available in `talosctl` to create a local cluster, but the same approach could be used to deploy Talos in bigger air-gapped networks.
+We will use the [QEMU]({{< relref "../talos-guides/install/local-platforms/qemu" >}}) provisioner available in `talosctl` to create a local cluster, but the same approach could be used to deploy Talos in bigger air-gapped networks.
 
 ## Requirements
 
 The follow are requirements for this guide:
 
 - Docker 18.03 or greater
-- Requirements for the Talos [QEMU](../../local-platforms/qemu/) cluster
+- Requirements for the Talos [QEMU]({{< relref "../talos-guides/install/local-platforms/qemu" >}}) cluster
 
 ## Identifying Images
 

diff --git a/...ent/v1.0/guides/customizing-the-kernel.md → ...t/v1.0/advanced/customizing-the-kernel.md b/...ent/v1.0/guides/customizing-the-kernel.md → ...t/v1.0/advanced/customizing-the-kernel.md
@@ -1,6 +1,8 @@
 ---
 title: "Customizing the Kernel"
-description: ""
+description: "Guide on how to customize the kernel used by Talos Linux."
+aliases:
+  - ../guides/customizing-the-kernel
 ---
 
 The installer image contains [`ONBUILD`](https://docs.docker.com/engine/reference/builder/#onbuild) instructions that handle the following:

diff --git a/...guides/customizing-the-root-filesystem.md → ...vanced/customizing-the-root-filesystem.md b/...guides/customizing-the-root-filesystem.md → ...vanced/customizing-the-root-filesystem.md
@@ -1,6 +1,8 @@
 ---
 title: "Customizing the Root Filesystem"
-description: ""
+description: "How to add your own content to the immutable root file system of Talos Linux."
+aliases:
+  - ../guides/customizing-the-root-filesystem
 ---
 
 The installer image contains [`ONBUILD`](https://docs.docker.com/engine/reference/builder/#onbuild) instructions that handle the following:

diff --git a/...ntent/v1.1/learn-more/developing-talos.md → ...content/v1.0/advanced/developing-talos.md b/...ntent/v1.1/learn-more/developing-talos.md → ...content/v1.0/advanced/developing-talos.md
@@ -1,6 +1,8 @@
 ---
 title: "Developing Talos"
-weight: 130
+description: "Learn how to set up a development environment for local testing and hacking on Talos itself!"
+aliases:
+  - ../learn-more/developing-talos
 ---
 
 This guide outlines steps and tricks to develop Talos operating systems and related components.

diff --git a/.../content/v1.0/guides/disaster-recovery.md → ...ontent/v1.0/advanced/disaster-recovery.md b/.../content/v1.0/guides/disaster-recovery.md → ...ontent/v1.0/advanced/disaster-recovery.md
@@ -1,6 +1,8 @@
 ---
 title: "Disaster Recovery"
 description: "Procedure for snapshotting etcd database and recovering from catastrophic control plane failure."
+aliases:
+  - ../guides/disaster-recovery
 ---
 
 `etcd` database backs Kubernetes control plane state, so if the `etcd` service is unavailable

diff --git a/...ent/v1.0/learn-more/extension-services.md → ...ntent/v1.0/advanced/extension-services.md b/...ent/v1.0/learn-more/extension-services.md → ...ntent/v1.0/advanced/extension-services.md
@@ -1,13 +1,15 @@
 ---
 title: "Extension Services"
-weight: 105
+description: "Use extension services in Talos Linux."
+aliases:
+  - ../learn-more/extention-services
 ---
 
 Talos provides a way to run additional system services early in the Talos boot process.
-Extension services should be included into the Talos root filesystem (e.g. using [system extensions](../../guides/system-extensions/)).
+Extension services should be included into the Talos root filesystem (e.g. using [system extensions]({{< relref "../talos-guides/configuration/system-extensions" >}})).
 Extension services run as privileged containers with ephemeral root filesystem located in the Talos root filesystem.
 
-Extension services can be used to use extend core features of Talos in a way that is not possible via [static pods](../../guides/static-pods) or
+Extension services can be used to use extend core features of Talos in a way that is not possible via [static pods]({{< relref "../advanced/static-pods" >}}) or
 Kubernetes DaemonSets.
 
 Potential extension services use-cases:

diff --git a/...des/adding-a-proprietary-kernel-module.md → ....0/advanced/proprietary-kernel-modules.md b/...des/adding-a-proprietary-kernel-module.md → ....0/advanced/proprietary-kernel-modules.md
@@ -1,6 +1,8 @@
 ---
-title: "Adding a proprietary kernel module to Talos Linux"
-description: ""
+title: "Proprietary Kernel Modules"
+description: "Adding a proprietary kernel module to Talos Linux"
+aliases:
+  - ../guides/adding-a-proprietary-kernel-module
 ---
 
 1. Patching and building the kernel image

diff --git a/website/content/v1.1/guides/static-pods.md → website/content/v1.0/advanced/static-pods.md b/website/content/v1.1/guides/static-pods.md → website/content/v1.0/advanced/static-pods.md
@@ -1,5 +1,8 @@
 ---
 title: "Static Pods"
+description: "Using Talos Linux to set up static pods in Kubernetes."
+aliases:
+  - ../guides/static-pods
 ---
 
 ## Static Pods

diff --git a/...1/guides/troubleshooting-control-plane.md → ...advanced/troubleshooting-control-plane.md b/...1/guides/troubleshooting-control-plane.md → ...advanced/troubleshooting-control-plane.md
@@ -1,6 +1,8 @@
 ---
 title: "Troubleshooting Control Plane"
 description: "Troubleshoot control plane failures for running cluster and bootstrap process."
+aliases:
+  - ../guides/troubleshooting-control-plane
 ---
 
 <!-- markdownlint-disable MD026 -->
@@ -48,7 +50,7 @@ Therefore, the number of control plane nodes should almost always be 3.
 In some particularly large or distributed clusters, the count may be 5, but this
 is very rare.
 
-See [this document](../../learn-more/concepts/#control-planes-are-not-linear-replicas) on the topic for more information.
+See [this document]({{< relref "../learn-more/concepts#control-planes-are-not-linear-replicas" >}}) on the topic for more information.
 
 ### What is the control plane endpoint?
 
@@ -77,7 +79,7 @@ As mentioned above, this can be achieved by a number of strategies, including:
 
 - an external load balancer
 - DNS records
-- Talos-builtin shared IP ([VIP](../vip/)
+- Talos-builtin shared IP ([VIP]({{< relref "../talos-guides/network/vip" >}}))
 - BGP peering of a shared IP (such as with [kube-vip](https://kube-vip.io))
 
 Using a DNS name here is usually a good idea, it being the most flexible

diff --git a/website/content/v1.0/bare-metal-platforms/_index.md b/website/content/v1.0/bare-metal-platforms/_index.md
diff --git a/website/content/v1.0/cloud-platforms/_index.md b/website/content/v1.0/cloud-platforms/_index.md
diff --git a/website/content/v1.0/guides/_index.md b/website/content/v1.0/guides/_index.md
diff --git a/website/content/v1.0/introduction/_index.md b/website/content/v1.0/introduction/_index.md
@@ -1,4 +1,4 @@
 ---
 title: "Introduction"
-weight: 1
+weight: 10
 ---
diff --git a/website/content/v1.0/introduction/getting-started.md b/website/content/v1.0/introduction/getting-started.md
@@ -1,10 +1,11 @@
 ---
 title: Getting Started
-weight: 3
+weight: 30
+description: "A guide to setting up a Talos Linux cluster on multiple machines."
 ---
 
 This document will walk you through installing a full Talos Cluster.
-You may wish to try the [Quickstart](../quickstart/) first, to quickly create a local virtual cluster on your workstation.
+You may wish to try the [Quickstart]({{< relref "quickstart" >}}) first, to quickly create a local virtual cluster on your workstation.
 
 Regardless of where you run Talos, there is a pattern to deploying it.
 In general you need to:
@@ -63,7 +64,7 @@ For network booting and self-built media, you can use the published kernel and i
 - ARM64: [vmlinuz-arm64](https://github.com/siderolabs/talos/releases/download/{{< release >}}/vmlinuz-arm64) [initramfs-arm64.xz](https://github.com/siderolabs/talos/releases/download/{{< release >}}/initramfs-arm64.xz)
 
 Note that to use alternate booting, there are a number of required kernel parameters.
-Please see the [kernel](../../reference/kernel/) docs for more information.
+Please see the [kernel]({{< relref "../reference/kernel" >}}) docs for more information.
 
 ## Decide the Kubernetes Endpoint
 
@@ -118,7 +119,7 @@ https://192.168.0.15:6443
 You are free to set a DNS record to this IP address to identify the endpoint, but you will need to use the IP address itself, not the DNS name, to configure the shared IP (`machine.network.interfaces[].vip.ip`) in the Talos configuration.
 
 For more information about using a shared IP, see the related
-[Guide](../../guides/vip/)
+[Guide]({{< relref "../talos-guides/network/vip" >}})
 
 ### DNS records
 
@@ -176,7 +177,7 @@ In cases where a PXE server can be available, this is much more efficient than
 manually configuring each node.
 If you do use this method, just note that Talos does require a number of other
 kernel commandline parameters.
-See the [required kernel parameters](../../reference/kernel/) for more information.
+See the [required kernel parameters]({{< relref "../reference/kernel" >}}) for more information.
 
 In either case, we need to generate the configuration which is to be provided.
 Luckily, the `talosctl` tool comes with a configuration generator for exactly
@@ -385,7 +386,7 @@ Server:
 ```
 
 For a more in-depth discussion of Endpoints and Nodes, please see
-[talosctl](../../learn-more/talosctl/).
+[talosctl]({{< relref "../learn-more/talosctl" >}}).
 
 ### Default configuration file
 

diff --git a/website/content/v1.0/introduction/quickstart.md b/website/content/v1.0/introduction/quickstart.md
@@ -1,6 +1,7 @@
 ---
 title: Quickstart
-weight: 2
+weight: 20
+description: "A short guide on setting up a simple Talos Linux cluster locally with Docker."
 ---
 
 There are two easy ways to try out Talos Linux.

diff --git a/website/content/v1.0/introduction/support-matrix.md b/website/content/v1.0/introduction/support-matrix.md
@@ -1,21 +1,22 @@
 ---
 title: Support Matrix
-weight: 6
+weight: 60
+description: "Table of supported Talos Linux versions and respective platforms."
 ---
 
 | Talos Version                                                                                                  | 1.0                                | 0.14                               |
 |----------------------------------------------------------------------------------------------------------------|------------------------------------|------------------------------------|
 | Release Date                                                                                                   | 2022-03-29                         | 2021-12-21 (0.14.0)                |
 | End of Community Support                                                                                       | 1.1.0 release (2022-06-01, TBD)    | 1.0.0 release (2022-03-27, TBD)    |
-| Enterprise Support                                                                                             | [offered by Sidero Labs Inc.](https://www.siderolabs.com/support/)      |
+| Enterprise Support                                                                                             | [offered by Sidero Labs Inc.](https://www.siderolabs.com/support/) | [offered by Sidero Labs Inc.](https://www.siderolabs.com/support/) |
 | Kubernetes                                                                                                     | 1.23, 1.22, 1.21                   | 1.23, 1.22, 1.21                   |
-| Architecture                                                                                                   | amd64, arm64                                                            |
+| Architecture                                                                                                   | amd64, arm64                       | amd64, arm64                       |
 | **Platforms**                                                                                                  |                                    |                                    |
-| - cloud                                                                                                        | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Scaleway, Vultr, Upcloud  |
-| - bare metal                                                                                                   | x86: BIOS, UEFI; arm64: UEFI; boot: ISO, PXE, disk image                |
-| - virtualized                                                                                                  | VMware, Hyper-V, KVM, Proxmox, Xen                                      |
-| - SBCs                                                                                                         | Banana Pi M64, Jetson Nano, Libre Computer Board ALL-H3-CC, Pine64, Pine64 Rock64, Radxa ROCK Pi 4c, Raspberry Pi 4B                         |
-| - local                                                                                                        | Docker, QEMU                                                            |
+| - cloud                                                                                                        | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, Oracle Cloud, Scaleway, Vultr, Upcloud | AWS, GCP, Azure, Digital Ocean, Hetzner, OpenStack, 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, Pine64, Pine64 Rock64, Radxa ROCK Pi 4c, Raspberry Pi 4B | Raspberry Pi4, Banana Pi M64, Pine64, and other |
+| - local                                                                                                        | Docker, QEMU                       | Docker, QEMU                       |
 | **Cluster API**                                                                                                |                                    |                                    |
 | [CAPI Bootstrap Provider Talos](https://github.com/siderolabs/cluster-api-bootstrap-provider-talos)            | >= 0.5.3                           | >= 0.4.3                           |
 | [CAPI Control Plane Provider Talos](https://github.com/siderolabs/cluster-api-control-plane-provider-talos)    | >= 0.4.5                           | >= 0.4.1                           |

diff --git a/website/content/v1.0/introduction/system-requirements.md b/website/content/v1.0/introduction/system-requirements.md
@@ -1,6 +1,7 @@
 ---
 title: System Requirements
-weight: 4
+weight: 40
+description: "Hardware requirements for running Talos Linux."
 ---
 
 ## Minimum Requirements

diff --git a/website/content/v1.0/introduction/what-is-new.md b/website/content/v1.0/introduction/what-is-new.md
@@ -1,6 +1,7 @@
 ---
 title: What's New in Talos 1.0
-weight: 5
+weight: 50
+description: "List of new and shiny features in Talos Linux."
 ---
 
 ## Announcements
@@ -29,16 +30,16 @@ container runtimes, additional firmware, among others.
 System extensions are only activated during Talos installation (or upgrade).
 Even with system extensions installed, the Talos root filesystem is still immutable and read-only.
 
-Please see [extensions repository](https://github.com/talos-systems/extensions) and [documentation]({{< relref "../guides/system-extensions/" >}}) for more information.
+Please see [extensions repository](https://github.com/talos-systems/extensions) and [documentation]({{< relref "../talos-guides/configuration/system-extensions/" >}}) for more information.
 
 ### Extension Services
 
-Talos now provides a way to extend the system services that Talos runs with [extension services]({{< relref "../learn-more/extension-services" >}}).
+Talos now provides a way to extend the system services that Talos runs with [extension services]({{< relref "../advanced/extension-services" >}}).
 Extension services should be included in the Talos root filesystem (i.e. via system extensions).
 
 ### Static Pods in the Machine Configuration
 
-Talos now accepts [static pod definitions]({{< relref "../guides/static-pods" >}}) in the `.machine.pods` key of the machine configuration.
+Talos now accepts [static pod definitions]({{< relref "../advanced/static-pods" >}}) in the `.machine.pods` key of the machine configuration.
 Please note that static pod definitions are not validated by Talos, and can be updated without a node reboot.
 
 ## Kubernetes
@@ -117,11 +118,11 @@ Talos now supports setting a bond interface from the kernel cmdline using the [`
 
 ### Equinix Metal
 
-`talos.platform` for [Equinix Metal]({{< relref "../bare-metal-platforms/equinix-metal" >}}) is renamed from `packet` to `equinixMetal`, the older name is still supported for backwards compatibility.
+`talos.platform` for [Equinix Metal]({{< relref "../talos-guides/install/bare-metal-platforms/equinix-metal" >}}) is renamed from `packet` to `equinixMetal`, the older name is still supported for backwards compatibility.
 
 ### Oracle Cloud
 
-Talos now supports [Oracle Cloud]({{< relref "../cloud-platforms/oracle" >}}).
+Talos now supports [Oracle Cloud]({{< relref "../talos-guides/install/cloud-platforms/oracle" >}}).
 
 ### Network Configuration
 
@@ -131,7 +132,7 @@ even if Talos is booted into maintenance mode, and without machine configuration
 
 ### SBCs
 
-Talos has added support for the [Jetson Nano SBC]({{< relref "../single-board-computers/jetson_nano" >}}).
+Talos now supports [Jetson Nano SBC]({{< relref "../talos-guides/install/single-board-computers/jetson_nano" >}}).
 
 ## Component Updates
 
@@ -149,7 +150,7 @@ Talos is built with Go 1.17.8
 ### NVIDIA GPU alpha Support
 
 Talos now has alpha support for NVIDIA GPU based workloads.
-Check the [NVIDA GPU support guide]({{< relref "../guides/nvidia-gpu" >}}) for details.
+Check the [NVIDA GPU support guide]({{< relref "../talos-guides/configuration/nvidia-gpu" >}}) for details.
 
 ## Miscellaneous
 
@@ -162,4 +163,4 @@ Use machine configuration field `.machine.sysfs` to set `sysfs` kernel parameter
 
 Talos added a new kernel parameter `talos.experimental.wipe=system` which can help resetting the system disk of the machine
 and start over with a fresh installation.
-See [Resetting a Machine]({{< relref "../guides/resetting-a-machine#kernel-parameter" >}}) on how to use it.
+See [Resetting a Machine]({{< relref "../talos-guides/resetting-a-machine#kernel-parameter" >}}) on how to use it.
diff --git a/website/content/v1.0/introduction/what-is-talos.md b/website/content/v1.0/introduction/what-is-talos.md
@@ -1,6 +1,7 @@
 ---
 title: What is Talos?
-weight: 1
+weight: 10
+description: "A quick introduction in to what Talos is and why it should be used."
 ---
 
 Talos is a container optimized Linux distro; a reimagining of Linux for distributed systems such as Kubernetes.

diff --git a/website/content/v1.0/kubernetes-guides/_index.md b/website/content/v1.0/kubernetes-guides/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Kubernetes Guides"
+weight: 30
+description: "Management of a Kubernetes Cluster hosted by Talos Linux"
+---
diff --git a/website/content/v1.0/kubernetes-guides/configuration/_index.md b/website/content/v1.0/kubernetes-guides/configuration/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Configuration"
+weight: 10
+description: "How to configure components of the Kubernetes cluster itself."
+---
diff --git a/...v1.0/guides/configuring-ceph-with-rook.md → ...es-guides/configuration/ceph-with-rook.md b/...v1.0/guides/configuring-ceph-with-rook.md → ...es-guides/configuration/ceph-with-rook.md
@@ -1,6 +1,8 @@
 ---
-title: "Configuring Ceph with Rook"
-description: ""
+title: "Ceph Storage cluster with Rook"
+description: "Guide on how to create a simple Ceph storage cluster with Rook for Kubernetes"
+aliases:
+  - ../../guides/configuring-ceph-with-rook
 ---
 
 ## Preparation

diff --git a/...uides/configuring-the-cluster-endpoint.md → ...-guides/configuration/cluster-endpoint.md b/...uides/configuring-the-cluster-endpoint.md → ...-guides/configuration/cluster-endpoint.md
@@ -1,6 +1,8 @@
 ---
-title: "Configuring the Cluster Endpoint"
-description: ""
+title: "Cluster Endpoint"
+description: "How to explicitly set up an endpoint for the cluster API"
+alises:
+  - ../../guides/configuring-the-cluster-endpoint
 ---
 
 In this section, we will step through the configuration of a Talos based Kubernetes cluster.
@@ -31,7 +33,7 @@ The configuration can either be done on a Loadbalancer, or simply trough DNS.
 For example:
 
 > This is in the config file for the cluster e.g. controlplane.yaml and worker.yaml.
-> for more details, please see: [v1alpha1 endpoint configuration](../../reference/configuration/#controlplaneconfig)
+> for more details, please see: [v1alpha1 endpoint configuration]({{< relref "../../reference/configuration#controlplaneconfig" >}})
 
 ```yaml
 .....