docs: fork docs for 1.1

Set up things for future 1.1 release. Signed-off-by: Andrey Smirnov <[email protected]>
siderolabs · Mar 30, 2022 · 6d6eb3f · 6d6eb3f
1 parent 1d55f05
commit 6d6eb3f
Show file tree

Hide file tree

Showing 105 changed files with 23,509 additions and 4 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -738,9 +738,9 @@ RUN protoc \
     /protos/time/*.proto
 
 FROM scratch AS docs
-COPY --from=docs-build /tmp/configuration.md /website/content/v1.0/reference/
-COPY --from=docs-build /tmp/cli.md /website/content/v1.0/reference/
-COPY --from=proto-docs-build /tmp/api.md /website/content/v1.0/reference/
+COPY --from=docs-build /tmp/configuration.md /website/content/v1.1/reference/
+COPY --from=docs-build /tmp/cli.md /website/content/v1.1/reference/
+COPY --from=proto-docs-build /tmp/api.md /website/content/v1.1/reference/
 
 # The talosctl-cni-bundle builds the CNI bundle for talosctl.
 

diff --git a/website/config.toml b/website/config.toml
@@ -124,6 +124,10 @@ offlineSearch = false
 # Enable syntax highlighting and copy buttons on code blocks with Prism
 prism_syntax_highlighting = false
 
+[[params.versions]]
+url = "/v1.1"
+version = "v1.1 (pre-release)"
+
 [[params.versions]]
 url = "/v1.0"
 version = "v1.0 (latest)"

diff --git a/website/content/v1.0/introduction/support-matrix.md b/website/content/v1.0/introduction/support-matrix.md
@@ -17,7 +17,7 @@ weight: 6
 | - 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                                                            |
 | **Cluster API**                                                                                                |                                    |                                    |
-| [CAPI Bootstrap Provider Talos](https://github.com/siderolabs/cluster-api-bootstrap-provider-talos)            | >= 0.5.2                           | >= 0.4.3                           |
+| [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                           |
 | [Sidero](https://www.sidero.dev/)                                                                              | >= 0.5.0                           | >= 0.4.1                           |
 | **UI**                                                                                                         |                                    |                                    |

diff --git a/website/content/v1.1/_index.md b/website/content/v1.1/_index.md
@@ -0,0 +1,54 @@
+---
+title: Welcome
+no_list: true
+linkTitle: "Documentation"
+cascade:
+  type: docs
+preRelease: true
+lastRelease: v1.1.0-alpha.0
+kubernetesRelease: "1.24.0-alpha.0"
+prevKubernetesRelease: "1.23.5"
+---
+
+## Welcome
+
+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
+
+## Open Source
+
+### Community
+
+- GitHub: [repo](https://github.com/siderolabs/talos)
+- Slack: Join our [slack channel](https://slack.dev.talos-systems.io)
+- Matrix: Join our Matrix channels:
+  - Community: [#talos:matrix.org](https://matrix.to/#/#talos:matrix.org)
+  - Support: [#talos-support:matrix.org](https://matrix.to/#/#talos-support:matrix.org)
+- Support: Questions, bugs, feature requests [GitHub Discussions](https://github.com/siderolabs/talos/discussions)
+- Forum: [community](https://groups.google.com/a/siderolabs.com/forum/#!forum/community)
+- Twitter: [@SideroLabs](https://twitter.com/talossystems)
+- Email: [[email protected]](mailto:[email protected])
+
+If you're interested in this project and would like to help in engineering efforts, or have general usage questions, we are happy to have you!
+We hold a weekly meeting that all audiences are welcome to attend.
+
+We would appreciate your feedback so that we can make Talos even better!
+To do so, you can take our [survey](https://docs.google.com/forms/d/1TUna5YTYGCKot68Y9YN_CLobY6z9JzLVCq1G7DoyNjA/edit).
+
+### Office Hours
+
+- When: Mondays at 16:30 UTC.
+- Where: [Google Meet](https://meet.google.com/day-pxhv-zky).
+
+You can subscribe to this meeting by joining the community forum above.
+
+## Enterprise
+
+If you are using Talos in a production setting, and need consulting services to get started or to integrate Talos into your existing environment, we can help.
+Sidero Labs, Inc. offers support contracts with SLA (Service Level Agreement)-bound terms for mission-critical environments.
+
+[Learn More](https://www.siderolabs.com/support/)
diff --git a/website/content/v1.1/bare-metal-platforms/_index.md b/website/content/v1.1/bare-metal-platforms/_index.md
@@ -0,0 +1,4 @@
+---
+title: "Bare Metal Platforms"
+weight: 20
+---
diff --git a/website/content/v1.1/bare-metal-platforms/digital-rebar.md b/website/content/v1.1/bare-metal-platforms/digital-rebar.md
@@ -0,0 +1,172 @@
+---
+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 controlplane.yaml
+created worker.yaml
+created talosconfig
+```
+
+> The loadbalancer is used to distribute the load across multiple controlplane nodes.
+> This isn't covered in detail, because we assume some loadbalancing knowledge before hand.
+> If you think this should be added to the docs, please [create a issue](https://github.com/siderolabs/talos/issues).
+
+At this point, you can modify the generated configs to your liking.
+Optionally, you can specify `--config-patch` with RFC6902 jsonpatch which will be applied during the config generation.
+
+#### Validate the Configuration Files
+
+```bash
+$ talosctl validate --config controlplane.yaml --mode metal
+controlplane.yaml is valid for metal mode
+$ talosctl validate --config worker.yaml --mode metal
+worker.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 `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 controlplane or worker.
+
+### Download the boot files
+
+Download a recent version of `boot.tar.gz` from [github.](https://github.com/siderolabs/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/siderolabs/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
+- 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](../overview).
+
+### Bootstrap Etcd
+
+To configure `talosctl` we will need the first control plane node's IP:
+
+Set the `endpoints` and `nodes`:
+
+```bash
+talosctl --talosconfig talosconfig config endpoint <control plane 1 IP>
+talosctl --talosconfig talosconfig config node <control plane 1 IP>
+```
+
+Bootstrap `etcd`:
+
+```bash
+talosctl --talosconfig talosconfig bootstrap
+```
+
+### Retrieve the `kubeconfig`
+
+At this point we can retrieve the admin `kubeconfig` by running:
+
+```bash
+talosctl --talosconfig talosconfig kubeconfig .
+```
diff --git a/website/content/v1.1/bare-metal-platforms/equinix-metal.md b/website/content/v1.1/bare-metal-platforms/equinix-metal.md
@@ -0,0 +1,125 @@
+---
+title: "Equinix Metal"
+description: "Creating Talos cluster using Equinix Metal."
+---
+
+## Prerequisites
+
+This guide assumes the user has a working API token, the [Equinix Metal CLI](https://github.com/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/siderolabs/talos/releases).
+
+## Special Considerations
+
+### PXE Boot Kernel Parameters
+
+The following is a list of kernel parameters required by Talos:
+
+- `talos.platform`: set this to `equinixMetal`
+- `init_on_alloc=1`: required by KSPP
+- `slab_nomerge`: required by KSPP
+- `pti=on`: required by KSPP
+
+### User Data
+
+<!-- textlint-disable one-sentence-per-line -->
+
+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`.
+
+<!-- textlint-enable one-sentence-per-line -->
+
+## 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 controlplane.yaml
+created worker.yaml
+created talosconfig
+```
+
+Now add the required shebang (e.g. `#!talos`) at the top of `controlplane.yaml`, and `worker.yaml`
+At this point, you can modify the generated configs to your liking.
+Optionally, you can specify `--config-patch` with RFC6902 jsonpatch which will be applied during the config generation.
+
+#### Validate the Configuration Files
+
+```bash
+talosctl validate --config controlplane.yaml --mode metal
+talosctl validate --config worker.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 Control Plane Nodes
+
+```bash
+metal 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
+metal device create \
+  --project-id $PROJECT_ID \
+  --facility $FACILITY \
+  --ipxe-script-url $PXE_SERVER \
+  --operating-system "custom_ipxe" \
+  --plan $PLAN\
+  --hostname $HOSTNAME\
+  --userdata-file worker.yaml
+```
+
+### Bootstrap Etcd
+
+Set the `endpoints` and `nodes`:
+
+```bash
+talosctl --talosconfig talosconfig config endpoint <control plane 1 IP>
+talosctl --talosconfig talosconfig config node <control plane 1 IP>
+```
+
+Bootstrap `etcd`:
+
+```bash
+talosctl --talosconfig talosconfig bootstrap
+```
+
+### Retrieve the `kubeconfig`
+
+At this point we can retrieve the admin `kubeconfig` by running:
+
+```bash
+talosctl --talosconfig talosconfig kubeconfig .
+```