Architecure section rework (#336)

* architecure rework

Signed-off-by: Francesco Giudici <francesco.giudici@suse.com>

* Update docs/architecture-components.md

Co-authored-by: Andrea Mazzotti <andrea.mazzotti@suse.com>

* architecture: update the drawing

Signed-off-by: Francesco Giudici <francesco.giudici@suse.com>

* architecture: merge resource pages with resource-reference ones

Signed-off-by: Francesco Giudici <francesco.giudici@suse.com>

* fix broken links

Signed-off-by: Francesco Giudici <francesco.giudici@suse.com>

* architecture: update the drawing

Signed-off-by: Francesco Giudici <francesco.giudici@suse.com>

* architecture: switch the architecture schema colors with light/dark

Solution from our Docusaurus master: thanks Nuno!

Co-authored-by: Nuno do Carmo <nuno.carmo@suse.com>

Signed-off-by: Francesco Giudici <francesco.giudici@suse.com>

---------

Signed-off-by: Francesco Giudici <francesco.giudici@suse.com>

docs/architecture-clusterdeployment.md

@@ -0,0 +1,14 @@
+---
+sidebar_label: Kubernetes cluster provisioning
+title: ''
+---
+
+## Kubernetes cluster provisioning
+The goal of the Kubernetes Cluster deployment phase is to create a new RKE2 or K3s cluster using the available [MachineInventories](machineinventory-reference.md), i.e., the hosts that have successfully completed the [Machine onboarding](architecture-machineonboarding.md) phase.
+
+The Elemental Kubernetes cluster deployment involves the following steps:
+* The user creates a [MachineInventorySelectorTemplate](machineinventoryselectortemplate-reference.md) resource: it allows to define a _selector_ to identify a subset of the available [MachineInventories](machineinventory-reference.md) based on the value of their labels.
+* The user defines a [Rancher cluster](cluster-reference.md) and adds to the `machinePools` definition a reference to the [MachineInventorySelectorTemplate](machineinventoryselectortemplate-reference.md) created in the step before.
+* The [Rancher RKE2/K3s Cluster provisioning](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-uuides/launch-kubernetes-with-rancher#rke2) reacts to the Rancher cluster resource creation by generating a number of [MachineInventorySelectors](machineinventoryselector-reference.md) resources equal to the _quantity_ specified in the _machinePools_.
+* The Elemental Operator pairs each generated [MachineInventorySelector](machineinventoryselector-reference.md) resource with an available [MachineInventory](machineinventory-reference.md) and installs the [rancher-system-agent](https://github.com/rancher/system-agent) daemon on the host tracked by the [MachineInventory](machineinventory-reference.md).
+The [Rancher RKE2/K3s Cluster provisioning](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-uuides/launch-kubernetes-with-rancher#rke2) takes over the K3s/RKE provisiong using [rancher-system-agent](https://github.com/rancher/system-agent) _plans_: it installs the required components (e.g., containerd, K3s, ...) and creates the configuration files till the successful deployment of the new Kubernetes cluster.

docs/architecture-components.md

@@ -0,0 +1,43 @@
+---
+sidebar_label: Elemental components
+title: ''
+---
+
+# Elemental components
+
+The components required to provide the [Elemental services](architecture-services.md) are:
+* the [``elemental``](#elemental-command-line-tool) command line tool
+* the [``elemental-operator``](#elemental-operator-daemon) daemon
+* the [``elemental-register``](#elemental-register-command-line-tool) command line tool
+* the [``elemental-system-agent``](#elemental-system-agent-daemon) daemon
+* one or more [Elemental OS container images](#elemental-os-container-image)
+
+### ``elemental`` command line tool
+The ``elemental`` tool is part of the <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> project.
+It performs the actual OS installation and upgrade operations on the host and is used to execute the [cloud-config](cloud-config-reference.md) directives added in the [Elemental CRDs](custom-resources.md).
+
+The ``elemental`` binary is included in all the base OS images distributed with Elemental.
+
+### ``elemental-operator`` daemon
+The **elemental-operator** daemon performs two main tasks:
+1. embeds the Elemental Kubernetes controllers to manage all the [Elemental CRDs](custom-resources.md)
+2. exposes the _registration endpoints_ to allow the host to register and download the OS installation configuration during the [machine onboarding](architecture-machineonboarding.md)
+
+The `elemental-operator` daemon is deployed on the Rancher cluster as a `Deployment` via the [Elemental Operator Helm Chart](elementaloperatorchart-reference.md).
+
+### ``elemental-register`` command line tool
+The **elemental-register** binary is the client used to register the host against the _registration endpoints_ exposed by the [elemental-operator](#elemental-operator-daemon). It collects and forwards the host data to allow the [elemental-operator](#elemental-operator-daemon) to fill the [SMBIOS](smbios.md) and the [Hardware](hardwarelabels.md) label templates.
+
+If the registraton phase is performed successfully, the **elemental-register** gets the full configuration stored in the [MachineRegistration](machineregistration-reference.md) from the **elemental-operator**.
+As the last step, the **elemental-register** client calls the [elemental](#elemental-command-line-tool) binary passing the retrieved configuration to kick off the OS installation.
+
+### ``elemental-system-agent`` daemon
+The ``elemental-system-agent`` is built from the [Rancher System Agent project](https://github.com/rancher/system-agent) and allows Elemental to deploy _plans_ to assist with the host provisioning.
+Notably, the ``rancher-system-agent`` installation and configuration required for the [Kubernetes Cluster provisioning service](architecture-clusterdeployment.md) is performed through an ``elemental-system-agent`` _plan_.
+
+### Elemental OS container image
+An <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> OS image is an OCI container image containing all the files that will make up the OS of the target host. It contains not only all the binaries and libraries, but also the kernel and the boot files required by a linux system.
+
+The Elemental OS image is an opinionated <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> OS image which is based on [SLE Micro](https://www.suse.com/products/micro/) and contains specific Elemental configurations and binaries (the [elemental](#elemental-command-line-tool) and the [elemental-register](#elemental-register-command-line-tool) ones).
+
+The Elemental OS images are tracked in the [ManagedOSVersions](managedosversion-reference.md) resources. The [ManagedOSVersions](managedosversion-reference.md) resources are dynamically created from [ManagedOSVersionChannel](managedosversionchannel-reference.md) resources. A default[ManagedOSVersionChannel](managedosversionchannel-reference.md) resource is deployed with each Elemental Operator installation.

docs/architecture-machineonboarding.md

@@ -0,0 +1,16 @@
+---
+sidebar_label: Machine onboarding
+title: ''
+---
+
+## Machine onboarding
+The goal of the Machine Onboarding service is to register a new machine in the Elemental Operator catalog ([MachineInventory](machineinventory-reference.md) resources) and provision the host with the OS, applying the desired configuration.
+
+The Machine Onboarding involves the following steps:
+* The user creates a [MachineRegistration](machineregistration-reference.md) resource: the MachineRegistration includes the configuration required for the OS installation.
+As soon as the MachineRegistration is created, the Elemental Operator exposes an HTTP _registration endpoint_: it is the entrypoint required by the onboarding hosts to register to the operator.
+* The user requests a self-installing image via a [SeedImage](seedimage-reference.md) resource: it only requires a reference to a MachineRegistration resource and to an OS container image compatible with the Elemental Toolkit.
+As soon as the SeedImage is created, the Elemental Operator triggers the build process of the self-installing image: once completed, the URL is exposed in the `status.downloadURL` field of the [SeedImage](seedimage-reference.md) resource.
+* The user downloads the self-installing image and uses it to boot an unprovisioned host:
+the host [authenticates](https://elemental.docs.rancher.com/authentication) to the _registration endpoint_ of the Elemental Operator, gets the full configuration stored in the MachineRegistration and installs the OS on the local storage device. As soon as the host has completed the registration process, the Elemental Operator creates a unique [MachineInventory](machineinventory-reference.md) resource tracking the host.
+The self-installing image can be used to onboard any number of hosts.

docs/architecture-services.md

@@ -0,0 +1,5 @@
+# Services
+
+Elemental functionality is provided through the following list of services:
+* [Machine Onboarding](architecture-machineonboarding.md): allows hosts to be OS provisioned and registered in the Elemental Operator catalog.
+* [Kubernetes Cluster Deployment](architecture-clusterdeployment.md): triggers the creation of a Kubernetes Cluster on the available host registered in the Elemental Operator catalog. 

docs/architecture.md

@@ -1,124 +1,31 @@
 ---
-sidebar_label: Architecture
+sidebar_label: Overview
 title: ''
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
 <head>
   <link rel="canonical" href="https://elemental.docs.rancher.com/architecture"/>
 </head>
 
-# Architecture
+# Architecture overview
+Elemental is the combination of two main projects: the <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> and the <Vars name="elemental_operator_name" link="elemental_operator_url" />.
 
-The Elemental stack can be divided in two main parts: the Elemental OS, an immutable and customizable OS which comprises the tools and the steps needed to prepare the Cloud Native OS image and perform the actual OS installation on the host, and the <Vars name="elemental_operator_name" />, that allows central management of the Elemental OS via Rancher, the Kubernetes way.
+The <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> enables OS installation and updates from OCI container images, so the OS can be distributed and retrieved via container registries.
 
-![Elemental Architecture](images/elemental-arch-v1.3_nobg.png)
-----
-## Elemental OS
-In order to deploy the Elemental OS we need:
+The <Vars name="elemental_operator_name" link="elemental_operator_url" /> extends Rancher with OS provisioning and OS management functionalities, leveraging the Elemental Toolkit.
+It bridges the gap between the <Vars name="elemental_toolkit_name" link="elemental_toolkit_url"/> and the
+[Rancher RKE2/K3s Cluster provisioning](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/launch-kubernetes-with-rancher#launching-kubernetes-on-new-nodes-in-an-infrastructure-provider-1),
+to provide a seamless experience going from hosts without OS to fully configured Kubernetes Clusters.
 
-- an Elemental base OS image
-- an Elemental installation configuration
-- the <Vars name="elemental_cli_name" /> tool, which installs the Elemental OS image on the target host applying the Elemental installation configuration
+This is achieved through a [set of services](architecture-services.md) offered by Elemental that are made possible thanks to the [components](architecture-components.md) borrowed from the Elemental Toolkit and the Elemental Operator projects.
 
-### Elemental OS image
-The Elemental OS image is an OCI container image containing all the files that will make up the OS of the target host. It will contain not only all the desired binaries and libraries, but also the kernel and the boot files required by a linux system.
-The <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> is at the core of the Elemental OS, enabling to boot and upgrade an OS from container images. It also provides a framework that allows to combine different packages to bake custom OS container images. For more information check the <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> project page.
-
-### Elemental installation configuration
-In order to provision a machine with an Elemental OS image, installation configuration parameters are required: things such as the boot device, the root password, system configuration, users and custom files are things that should be provided aside from the Elemental OS image. All the data can be provided in a single .yaml file. More details can be found in the <Vars name="elemental_toolkit_name" link="elemental_toolkit_url" /> documentation.
-
-### Elemental CLI
-
-<Vars name="elemental_cli_name" /> is the tool that allows to turn the Elemental OS image in a bootable and installed OS: it can generate an <Vars name="elemental_iso_name" /> image from the provided Elemental OS container image. The generated <Vars name="elemental_iso_name" /> image can be used to boot a virtual machine or a bare metal host and start the Elemental OS installation.
-
-The <Vars name="elemental_cli_name" /> allows also to install the Elemental OS on the storage device of the live booted host, applying the provided Elemental installation configuration. For the list and syntax of the commands available in the <Vars name="elemental_cli_name" />, check the <Vars link="elemental_cli_url">online documentation</Vars>.
-
-### <Vars name="elemental_iso_name" />
-The <Vars name="elemental_iso_name" /> is a live ISO based on the Elemental OS (an Elemental live ISO).
-It includes all the tools needed to perform a full node provisioning, from the OS to Kubernetes, including the [<Vars name="elemental_cli_name" />](#elemental-cli) and the [<Vars name="elemental_register_name" />](#elemental-register-client).
-
-----
-
-## Elemental Operator
-The <Vars name="elemental_operator_name" /> is responsible for managing OS upgrades and a secure device inventory to assist
-with zero touch provisioning.
-It provides an <Vars name="elemental_operator_name" /> Helm Chart and an <Vars name="elemental_register_name" />.
-
-### Elemental Operator Helm Chart
-The <Vars name="elemental_operator_name" /> Helm Chart must be installed on a Rancher Cluster. It enables new hosts to:
-
-- register against the <Vars name="elemental_operator_name" />.
-- retrieve the Elemental installation configuration (which is stored in custom Kubernetes resources) to start the Elemental OS installation.
-- download and install the <Vars name="ranchersystemagent_name" link="ranchersystemagent_url" />, which enables Rancher to provision and manage K3s and RKE2 on the Elemental nodes.
-
-The <Vars name="elemental_operator_name" /> allows control of the Elemental Nodes by extending the Kubernetes APIs with a set of _elemental.cattle.io_ [Kubernetes CRDs](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/):
-
-- MachineRegistration
-- MachineInventory
-- MachineInventorySelector
-- MachineInventorySelectorTemplate
-- ManagedOSImage
-- ManagedOSVersion
-- ManagedOSVersionChannel
-- SeedImage
-
-#### MachineRegistration
-The MachineRegistration includes the Elemental installation configuration (provided by the user) and a registration token (generated by the <Vars name="elemental_operator_name" />), from which a registration URL is derived.
-
-The registration URL is the way through which an host can access the <Vars name="elemental_operator_name" /> services, to kick off the Elemental provisioning process.
-
-The MachineRegistration has a `Ready` condition which turns to true when the <Vars name="elemental_operator_name" /> has successfully generated the registration URL and an associated ServiceAccount. From this point on the target host can connect to the registration URL to kick off the provisioning process.
-
-An HTTP GET request against the registration URL returns the _registration file_: a .yaml file containing the registration data (i.e., the _spec:config:elemental:registration_ section only from the just created MachineRegistration).
-The registration file contains all the required data to allow the target host to perform self registration and start the Elemental provisioning. See the [<Vars name="elemental_register_name" /> section](#elemental-register-client) for more info on the registration process and the [config:elemental:registration section in the MachineRegistration reference](machineregistration-reference.md#configelementalregistration) for more details on the available registration options.
-
-#### MachineInventory
-When a new host registers successfully, the <Vars name="elemental_operator_name" /> creates a MachineInventory resource representing that particular host.
-The MachineInventory stores the TPM hash of the tracked host, retrieved during the registration process, and allows to execute arbitrary commands (plans) on the machine.
-
-A MachineInventory has two conditions:
-
-- `AdoptionReady`, which indicates the machine has been adopted by a selector to be part of a cluster.
-- `Ready`, which indicates that the machine has been registered and provisioned with an Elemental OS.
-
-#### MachineInventorySelector
-A MachineInventorySelector selects MachineInventories based on applied selectors (usually pattern matching on MachineInventory label values).
-
-MachineInventorySelectors have two conditions:
-
-- `InventoryReady`, turns to true if the MachineInventorySelector has found a matching MachineInventory and has successfully set itself as the MachineInventory owner.
-- `Ready`, tracks if the selector already adopted a machine and started the kubernetes provisioning process (node bootstrap).
-
-#### MachineInventorySelectorTemplate
-The MachineInventorySelectorTemplate is a user defined resource that will be used as the blueprint to create the required MachineInventorySelectors: it includes the selector to identify the eligible MachineInventories.
-
-#### SeedImage
-A SeedImage is a resource to handle the installation media creation. Includes the reference to the base installation system and a reference to the machine registration. It is used to create and serve installation ISOs including
-the MachineRegistration metadata required for the machine registration. The installation media is created and being served in a devoted Pod.
-
-SeedImage have two conditions:
-
-- `SeedImageReady`, tracks the status of the associated pod.
-- `Ready`, tracks if all the SeedImage child resources have been successfully created.
-
-### Elemental Register client
-New hosts start the Elemental provisioning process through the <Vars name="elemental_register_name" />: this tool requires a valid elemental-operator registration URL as input (see the [MachineRegistration section](#machineregistration)), and performs the following steps:
-
-- setups a websocket connection to the registration URL
-- authenticates itself using the registration token and the onboard [TPM (Trusted Platform Module)](https://en.wikipedia.org/wiki/Trusted_Platform_Module)
-- sends [SMBIOS data](smbios.md) to the <Vars name="elemental_operator_name" />
-- retrieves the Elemental installation configuration
-- starts the [<Vars name="elemental_cli_name" />](#elemental-cli) and performs the Elemental OS installation
-
-**Note**
-if no TPM 2.0 is available on the host, TPM can be emulated by software: see the `emulate-tpm` key in the [config.elemental.register reference document](machineregistration-reference.md#configelementalregistration).
-
-<Vars name="elemental_operator_name" /> includes a Kubernetes operator installed in the management cluster and a client
-side installed in nodes, so they can self register into the management cluster. Once a node is
-registered the <Vars name="elemental_operator_name" /> will kick-start the OS installation and schedule the Kubernetes
-provisioning using the <Vars name="ranchersystemagent_name" link="ranchersystemagent_url" />.
-Rancher System Agent is responsible for bootstrapping RKE2/k3s and Rancher from an OCI registry. This means
-an update of containerd, k3s, RKE2, or Rancher does not require an OS upgrade
-or node reboot.
-
-----
+<ThemedImage
+  alt="Elemental Architecture"
+  sources={{
+    light: useBaseUrl('img/elemental-architecture-v1.5.png'),
+    dark: useBaseUrl('img/elemental-architecture-v1.5-dark.png'),
+  }}
+/>

docs/custom-resources.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: Custom Resources
+title: ''
+---
+
+<head>
+  <link rel="canonical" href="https://elemental.docs.rancher.com/custom-resources"/>
+</head>
+
+# Custom Resources
+
+The <Vars name="elemental_operator_name" /> allows control of the Elemental Nodes by extending the Kubernetes APIs with a set of _elemental.cattle.io_ [Kubernetes CRDs](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/):
+
+- [MachineRegistration](machineregistration-reference.md)
+- [MachineInventory](machineinventory-reference.md)
+- [MachineInventorySelector](machineinventoryselector-reference.md)
+- [MachineInventorySelectorTemplate](machineinventoryselectortemplate-reference.md)
+- [ManagedOSImage](managedosimage-reference.md)
+- [ManagedOSVersion](managedosversion-reference.md)
+- [ManagedOSVersionChannel](managedosversionchannel-reference.md)
+- [SeedImage](seedimage-reference.md)

docs/elemental_behind_proxy.md

@@ -46,7 +46,7 @@ You can do it either with [UI](quickstart-ui#add-a-machine-registration-endpoint
 
 ## Elemental-register
 
-[Elemental-register](architecture#elemental-register-client) is the first communication endpoint between the new host and Rancher Manager, this is the first place where proxy settings need to be set.
+[Elemental-register](architecture-components#elemental-register-command-line-tool) is the first communication endpoint between the new host and Rancher Manager, this is the first place where proxy settings need to be set.
 
 :::warning warning
 At the time of writing, it's only possible to configure proxy settings for the ISO with the CLI. The proxy settings aren't implemented in the UI.
@@ -64,7 +64,7 @@ kubectl apply -f <my_seedimage_yaml_file>
 kubectl get seedimage <seed_image_name> -n <namespace> -o yaml
 ```
 
-Boot the ISO and you should see your new system appears in [Machine inventory](architecture#machineinventory).
+Boot the ISO and you should see your new system appears in [Machine inventory](machineinventory-reference.md).
 
 ## Create Elemental cluster
 

docs/machineinventory-reference.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: MachineInventory reference
+title: ''
+---
+
+<head>
+  <link rel="canonical" href="https://elemental.docs.rancher.com/machineinventory-reference"/>
+</head>
+
+# MachineInventory
+When a new host registers successfully, the <Vars name="elemental_operator_name" /> creates a MachineInventory resource representing that particular host.
+The MachineInventory stores the TPM hash of the tracked host, retrieved during the registration process, and allows to execute arbitrary commands (plans) on the machine.
+
+A MachineInventory has two conditions:
+
+- `AdoptionReady`, which indicates the machine has been adopted by a selector to be part of a cluster.
+- `Ready`, which indicates that the machine has been registered and provisioned with an Elemental OS.

docs/machineinventoryselector-reference.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: MachineInventorySelector reference
+title: ''
+---
+
+<head>
+  <link rel="canonical" href="https://elemental.docs.rancher.com/machineinventoryselector-reference"/>
+</head>
+
+# MachineInventorySelector reference
+
+A MachineInventorySelector selects MachineInventories based on applied selectors (usually pattern matching on MachineInventory label values).
+
+MachineInventorySelectors have two conditions:
+
+- `InventoryReady`, turns to true if the MachineInventorySelector has found a matching MachineInventory and has successfully set itself as the MachineInventory owner.
+- `Ready`, tracks if the selector already adopted a machine and started the kubernetes provisioning process (node bootstrap).

docs/machineinventoryselectortemplate-reference.md

@@ -9,7 +9,9 @@ title: ''
 
 # MachineInventorySelectorTemplate reference
 
-The MachineInventorySelectorTemplate is the resource responsible of defining the matching criteria to pair an inventoried machine with a Cluster resource.
+The MachineInventorySelectorTemplate is a user defined resource that will be used as the blueprint to create the required [MachineInventorySelectors](machineinventoryselector-reference.md).
+
+It is the resource responsible of defining the matching criteria to pair an inventoried machine with a Cluster resource.
 
 The relevant key is the `selector` which includes label selector expressions.
 

docs/machineregistration-reference.md

@@ -1,15 +1,24 @@
 ---
-sidebar_label: MachineRegistration reference
+sidebar_label: MachineRegistration
 title: ''
 ---
 
 <head>
-  <link rel="canonical" href="https://elemental.docs.rancher.com/machineregistration-reference"/>
+  <link rel="canonical" href="https://elemental.docs.rancher.com/machineregistration"/>
 </head>
 
 # MachineRegistration reference
 
-The MachineRegistration resource is the responsible of defining a machine registration end point. Once created it generates a registration URL used by nodes to register so they are inventoried.
+The MachineRegistration resource allows:
+* to configure the registration process
+* to provide OS installation parameters
+* to define the [Elemental services](architecture-services.md) enabled for the registering machine
+Once created it generates the registration URL used by nodes to register and start the [machine onboarding](architecture-machineonboarding.md) process.
+
+The MachineRegistration has a `Ready` condition which turns to true when the <Vars name="elemental_operator_name" /> has successfully generated the registration URL and an associated `ServiceAccount`. From this point on the target host can connect to the registration URL to kick off the provisioning process.
+
+An HTTP GET request against the registration URL returns the _registration file_: a .yaml file containing the registration data (i.e., the _spec:config:elemental:registration_ section from the just created MachineRegistration).
+The registration file contains all the required data to allow the target host to perform self registration and start the Elemental provisioning.
 
 There are several keys that can be configured under a `MachineRegistration` resource spec.
 

docs/quickstart-ui.md

@@ -143,7 +143,7 @@ You can now boot your nodes with this image and they will:
 
 ## Machine Inventory
 
-When nodes are booting up for the first time, they connect to Rancher Manager and a [`Machine Inventory`](architecture#machineinventory) is created for each node.
+When nodes are booting up for the first time, they connect to Rancher Manager and a [`Machine Inventory`](machineinventory-reference.md) is created for each node.
 
 ![Machine Inventory menu](images/quickstart-ui-machine-inventory-menu.png)
 

sidebars.js

@@ -26,7 +26,28 @@ const sidebars = {
         "quickstart-cli"
       ]
     },
-    "architecture",
+    {
+      "type": "category",
+      "collapsible": true,
+      "collapsed": true,
+      "label": "Architecture",
+      "link": {"type": "doc", "id": "architecture"},
+      "items": [
+        "architecture-components",
+        "custom-resources",
+        {
+          "type": "category",
+          "collapsible": true,
+          "collapsed": true,
+          "label": "Services",
+          "link": {"type": "doc", "id": "architecture-services"},
+          "items": [
+            "architecture-machineonboarding",
+            "architecture-clusterdeployment",
+          ]
+        },
+      ]
+    },
     {
       "type": "category",
       "collapsible": true,
@@ -49,12 +70,14 @@ const sidebars = {
       "items": [
         "cloud-config-reference",
         "machineregistration-reference",
+        "machineinventory-reference",
+        "machineinventoryselector-reference",
         "machineinventoryselectortemplate-reference",
         "managedosimage-reference",
         "managedosversionchannel-reference",
         "managedosversion-reference",
-        "cluster-reference",
         "seedimage-reference",
+        "cluster-reference",
         "elementaloperatorchart-reference",
         "kubernetesversions",
         "smbios",