docs: add notes on version compatibility and improve the bootstrappin…

…g guide Fix the order in which the Getting Started pages are shown. Fix link to Talos kernel options. Add emphasis on the required boot order. Add a section on configPatches for ServerClasses Add notes on version compatibility and 2 extra steps for IPMI + installation disk Signed-off-by: Gerard de Leeuw <[email protected]>
siderolabs · Sep 24, 2021 · d923bb0 · d923bb0
1 parent a2bb2d0
commit d923bb0
Show file tree

Hide file tree

Showing 7 changed files with 54 additions and 9 deletions.
diff --git a/website/content/docs/v0.3/Getting Started/prereq-cli-tools.md b/website/content/docs/v0.3/Getting Started/prereq-cli-tools.md
@@ -1,6 +1,6 @@
 ---
 description: "Prerequisite: CLI tools"
-weight: 99
+weight: 2
 title: "Prerequisite: CLI tools"
 ---
 
@@ -39,10 +39,13 @@ The main article for installing `clusterctl` can be found
 
 ```bash
 sudo curl -Lo /usr/local/bin/clusterctl \
-  "https://github.com/kubernetes-sigs/cluster-api/releases/download/v0.3.21/clusterctl-$(uname -s | tr '[:upper:]' '[:lower:]')-amd64" \
+  "https://github.com/kubernetes-sigs/cluster-api/releases/download/v0.3.23/clusterctl-$(uname -s | tr '[:upper:]' '[:lower:]')-amd64" \
 sudo chmod +x /usr/local/bin/clusterctl
 ```
 
+> Note: Sidero is currently only compatible with CAPI v1alpha3,
+> so versions of `clusterctl` above v0.3.x will not work.
+
 ## Install `talosctl`
 
 The `talosctl` tool is used to interact with the Talos (our Kubernetes-focused

diff --git a/website/content/docs/v0.3/Getting Started/prereq-dhcp.md b/website/content/docs/v0.3/Getting Started/prereq-dhcp.md
@@ -1,6 +1,6 @@
 ---
 description: "Prerequisite: DHCP Service"
-weight: 99
+weight: 4
 title: "Prerequisite: DHCP service"
 ---
 

diff --git a/website/content/docs/v0.3/Getting Started/prereq-kubernetes.md b/website/content/docs/v0.3/Getting Started/prereq-kubernetes.md
@@ -1,6 +1,6 @@
 ---
 description: "Prerequisite: Kubernetes"
-weight: 99
+weight: 3
 title: "Prerequisite: Kubernetes"
 ---
 

diff --git a/website/content/docs/v0.3/Guides/bootstrapping.md b/website/content/docs/v0.3/Guides/bootstrapping.md
@@ -89,11 +89,14 @@ Issue the following to create a single-node cluster:
 
 ```bash
 talosctl cluster create \
+ --kubernetes-version 1.21.3 \
   -p 69:69/udp,8081:8081/tcp \
   --workers 0 \
   --endpoint $PUBLIC_IP
 ```
 
+> Note: Kubernetes 1.21.x is the highest version compatible with `clusterctl` v0.3.x.
+
 Note that there are several ports mentioned in the command above.
 These allow us to access the services that will get deployed on this node.
 
@@ -135,6 +138,26 @@ NAME                                   HOSTNAME        ACCEPTED   ALLOCATED   CL
 00000000-0000-0000-0000-d05099d33360   192.168.254.2   false      false       false
 ```
 
+## Setting up IPMI
+
+Sidero can use IPMI information to control Server power state, reboot servers and set boot order.
+IPMI information will be, by default, setup automatically if possible as part of the acceptance process.
+See [IPMI](/docs/v0.3/resource-configuration/servers/#ipmi) for more information.
+
+IMPI connection information can also be set manually in the Server spec after initial registration:
+
+```bash
+kubectl patch server 00000000-0000-0000-0000-d05099d33360 --type='json' -p='[{"op": "add", "path": "/spec/bmc", "value": {"endpoint": "192.168.88.9", "user": "ADMIN", "pass":"ADMIN"}}]'
+```
+
+If IPMI info is not set, servers should be configured to boot first from network, then from disk.
+
+## Configuring the installation disk
+
+Note that for bare-metal setup, you would need to specify an installation disk.
+See [Installation Disk](/docs/v0.3/configuration/servers/#installation-disk) for details on how to do this.
+You should configure this before accepting the server.
+
 ## Accept the Servers
 
 Note in the output above that the newly registered servers are not `accepted`.
@@ -178,14 +201,15 @@ For instance:
 ```bash
 export CONTROL_PLANE_SERVERCLASS=any
 export WORKER_SERVERCLASS=any
-export KUBERNETES_VERSION=v1.20.1
+export TALOS_VERSION=v0.11
+export KUBERNETES_VERSION=v1.21.3
 export CONTROL_PLANE_PORT=6443
 export CONTROL_PLANE_ENDPOINT=1.2.3.4
 clusterctl config cluster management-plane -i sidero > management-plane.yaml
 ```
 
 In addition, you can specify the replicas for control-plane & worker nodes in management-plane.yaml manifest for TalosControlPlane and MachineDeployment objects.
-Also, they can be scaled if needed:
+Also, they can be scaled if needed (after applying the `management-plane.yaml` manifest):
 
 ```bash
 kubectl get taloscontrolplane

diff --git a/website/content/docs/v0.3/Resource Configuration/environments.md b/website/content/docs/v0.3/Resource Configuration/environments.md
@@ -8,7 +8,7 @@ Environments are a custom resource provided by the Metal Controller Manager.
 An environment is a codified description of what should be returned by the PXE server when a physical server attempts to PXE boot.
 
 Especially important in the environment types are the kernel args.
-From here, one can tweak the IP to the metadata server as well as various other kernel options that [Talos](hhttps://www.talos.dev/docs/v0.11/reference/kernel/#commandline-parameters) and/or the Linux kernel supports.
+From here, one can tweak the IP to the metadata server as well as various other kernel options that [Talos](https://www.talos.dev/docs/v0.11/reference/kernel/#commandline-parameters) and/or the Linux kernel supports.
 
 Environments can be supplied to a given server either at the Server or the ServerClass level.
 The hierarchy from most to least respected is:

diff --git a/website/content/docs/v0.3/Resource Configuration/serverclasses.md b/website/content/docs/v0.3/Resource Configuration/serverclasses.md
@@ -62,3 +62,21 @@ Additionally, Sidero automatically creates and maintains a server class called `
 Attempts to add qualifiers to it will be reverted.
 
 [label-selector-docs]: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/label-selector/
+
+## `configPatches`
+
+Server configs of servers matching a server class can be updated by using the `configPatches` section of the custom resource.
+See [patching](/docs/v0.3/guides/patching) for more information on how this works.
+
+An example of settings the default install disk for all servers matching a server class:
+
+```yaml
+apiVersion: metal.sidero.dev/v1alpha1
+kind: ServerClass
+...
+spec:
+  configPatches:
+    - op: replace
+      path: /machine/install/disk
+      value: /dev/sda
+```
diff --git a/website/content/docs/v0.3/Resource Configuration/servers.md b/website/content/docs/v0.3/Resource Configuration/servers.md
@@ -36,7 +36,7 @@ spec:
 
 ## Installation Disk
 
-A an installation disk is required by Talos on bare metal.
+An installation disk is required by Talos on bare metal.
 This can be specified in a `configPatch`:
 
 ```yaml
@@ -110,7 +110,7 @@ If IPMI information is set, server boot order might be set to boot from disk, th
 to PXE boot once that is required.
 
 Without IPMI info, Sidero can still register servers, wipe them and provision clusters, but Sidero won't be able to reboot servers once they are removed from the cluster.
-If IPMI info is not set, servers should be configured to boot first from network, then from disk.
+**If IPMI info is not set, servers should be configured to boot first from network, then from disk.**
 
 Sidero can also fetch IPMI credentials via the `Secret` reference: