Overall improvements (#151)

Signed-off-by: Christian Berendt <[email protected]>

docs/getting-started.md

@@ -0,0 +1,15 @@
+---
+sidebar_label: Getting Started
+sidebar_position: 10
+---
+
+# Getting Started
+
+OSISM is deployed in a series of successive phases. The phases are documented in this chapter.
+
+1. [Creation of a configuration repository](./guides/configuration-guide/configuration-repository#creating-a-new-configuration-repository)
+2. [Preparation of a seed node](./guides/deploy-guide/seed)
+3. [Preparation of a manager node](./guides/deploy-guide/manager)
+4. [Provisioning of the bare-metal nodes](./guides/deploy-guide/bootstrap#provisioning-of-management-and-control-plane-nodes)
+5. [Bootstrap of the bare-metal nodes](./guides/deploy-guide/bootstrap)
+6. [Deployment of the services](./guides/deploy-guide/services)

docs/guides/configuration-guides/ceph.md → docs/guides/configuration-guide/ceph.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Ceph
-sidebar_position: 20
+sidebar_position: 40
 ---
 
 # Ceph

docs/guides/configuration-guides/commons/index.md → docs/guides/configuration-guide/commons/index.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Commons
-sidebar_position: 10
+sidebar_position: 30
 ---
 
 # Commons

docs/getting-started/configuration-repository.md → docs/guides/configuration-guide/configuration-repository.md

@@ -3,7 +3,84 @@ sidebar_label: Configuration repository
 sidebar_position: 10
 ---
 
-# Creating a new configuration repository
+# Configuration Repository
+
+The entire configuration required for OSISM is stored in a single Git monorepo.
+
+## Configuration repository layout
+
+A configuration repository is always composed of the same basic layout.
+
+* `gilt.yml` & `requirements.txt` files
+* `environments` directory
+* `inventory` directory
+* `netbox` directory (optional)
+
+### `gilt.yml` & `requirements.txt` files
+
+[Gilt](https://gilt.readthedocs.io) is a Git layering tool. We use Gilt to maintain the image versions,
+Ansible configuration and scripts within the `environments/manager` directory.
+
+The [current gilt.yml](https://github.com/osism/cfg-generics/blob/main/gilt.yml) file is always
+located in the [osism/cfg-generics](https://github.com/osism/cfg-generics) repository.
+
+```yaml title="gilt.yml (date of this example: 2023-10-09)"
+---
+- git: https://github.com/osism/cfg-generics.git
+  version: main
+  files:
+    - src: src/render-images.py
+      dst: ./environments/manager/render-images.py
+    - src: gilt.yml
+      dst: ./gilt.yml
+    - src: requirements.txt
+      dst: ./requirements.txt
+    - src: environments/manager/images.yml
+      dst: environments/manager/images.yml
+    - src: environments/manager/run.sh
+      dst: environments/manager/run.sh
+    - src: environments/manager/ansible.cfg
+      dst: environments/manager/ansible.cfg
+    - src: environments/manager/requirements.*
+      dst: environments/manager/
+      post_commands:
+        - python3 render-images.py
+        - rm render-images.py
+```
+
+
+In the `requirements.txt` the necessary dependencies are listed to be able to execute Gilt.
+
+To use Gilt the dependencies are installed first.
+
+```
+pip3 install -r requirements.txt
+```
+
+After that you can update the manager environment in `environments/manager`. Since the `gilt.yml`
+itself is updated with Gilt it is always important to run the command twice.
+
+```
+gilt overlay
+gilt overlay
+```
+
+If a stable OSISM release is used, the version to be used is specified by `MANAGER_VERSION`.
+In the example, OSISM release 6.0.0 is used. More detail about this in
+[Configuration Guides > Manager > Stable release](manager#stable-release).
+
+```
+MANAGER_VERSION=6.0.0 gilt overlay
+MANAGER_VERSION=6.0.0 gilt overlay
+```
+
+### `environments` directory
+
+### `inventory` directory
+
+### `netbox` directory
+
+## Creating a new configuration repository
 
 The initial content for this repository is generated using the
 [cookiecutter](https://github.com/osism/cfg-cookiecutter).
@@ -92,7 +169,7 @@ How to add a deploy key on GitHub is documented in
 
 The configuration repository that is initially created with the Cookiecutter is not directly usable.
 For example, the inventory needs to be built. All further information can be found in the
-[Configuration Guide](../guides/configuration-guides/index.md).
+[Configuration Guides](./).
 
 ### Notes
 

docs/guides/configuration-guide/index.md

@@ -0,0 +1,6 @@
+---
+sidebar_label: Configuration Guides
+sidebar_position: 30
+---
+
+# Configuration Guides

docs/guides/configuration-guides/inventory.md → docs/guides/configuration-guide/inventory.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Inventory
-sidebar_position: 4
+sidebar_position: 10
 ---
 
 # Inventory

docs/guides/configuration-guides/manager.md → docs/guides/configuration-guide/manager.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Manager
-sidebar_position: 5
+sidebar_position: 20
 ---
 
 # Manager

docs/guides/configuration-guides/openstack/index.md → docs/guides/configuration-guide/openstack/index.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: OpenStack
-sidebar_position: 30
+sidebar_position: 50
 ---
 
 # OpenStack

docs/guides/configuration-guides/services/index.md → docs/guides/configuration-guide/services/index.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Services
-sidebar_position: 20
+sidebar_position: 30
 ---
 
 # Services

docs/guides/deploy-guide/bootstrap.md

@@ -1,13 +1,13 @@
 ---
 sidebar_label: Bootstrap
-sidebar_position: 5
+sidebar_position: 40
 ---
 
 # Bootstrap
 
 Before the nodes can be bootstrapped, they must all have already been provisioned.
 The guide for this can be found in the section
-[Provisioning of management and control plane nodes](bootstrap#provisioning-of-management-and-control-plane-nodes)
+[Provisioning of management and control plane nodes](./provisioning)
 
 The following steps are applied to bootstrap all nodes. After the completion of the bootstrap, the nodes are already ready for use.
 
@@ -96,73 +96,3 @@ The following steps are applied to bootstrap all nodes. After the completion of
    ```
 
 Ready. All nodes are now bootstrapped and available to deploy services.
-
-## Provisioning of management and control plane nodes
-
-For the initial deployment of the management plane and the control plane of OSISM,
-the nodes must be pre-provisioned with Ubuntu 22.04. Currently, only Ubuntu 22.04 is supported
-by OSISM.
-
-Data plane nodes can be automatically provisioned after the initial deployment and
-do not need to be pre-provisioned.
-
-It is recommended not to install the initial nodes of the management plane and the
-control plane manually. An ISO image is provided for this purpose which automatically
-provisions a node. The ISO images are available for download in the
-[osism/node-image](https://github.com/osism/node-image) repository.
-
-There are different variants of the ISO image. The variants differ in the disc layout.
-The available variants are described in the README file of the [osism/node-image](https://github.com/osism/node-image)
-repository.
-
-### Manual provisioning
-
-If none of the provided variants is suitable, this section describes the manual
-installation with the help of the Ubuntu 22.04 live ISO image. The manual installation
-is possible without network connectivity.
-
-* Download the latest ISO image for Ubuntu 22.04 from [releases.ubuntu.com](https://www.releases.ubuntu.com/22.04/).
-  * Use the `ubuntu-22.04.1-live-server-amd64.iso` image.
-  * The version number may be different, always use the latest available version of 22.04 LTS.
-* Choose `English` as language.
-* Choose `Install Ubuntu Server`.
-* Choose `English as language` (again).
-* Choose your location (e.g. `Germany`).
-* Choose `en_US.UTF-8` as locale.
-* Choose the keyboard layout from a list, use `English (US)`.
-* Choose and configure the primary network interface.
-  * Depending on the environment, the network may not work at this point. Then select any interface
-    and then select `Do not configure the network at this time` in the next step.
-* Set the hostname.
-  * The hostname is e.g. `node` and not a FQDN like `node.systems.osism.xyz`.
-* Set `osism` as full name for the new user.
-* Set `osism` as the username for the account.
-  * The later used operator user `dragon` is created during the bootstrap and **should not be created** during the installation
-  * The account is only needed initially and can be deleted after completion of the bootstrap.
-* Set a password for the account.
-* Choose `Manual` as partitioning method and execute the partitioning according to company specifications
-  * The use of a UEFI is recommended
-  * The use of a RAID is recommended. We prefer the use of software RAIDs to make us less dependent on hardware.
-    But there is nothing against using hardware RAIDs.
-  * The use of a LVM2 is recommended. `system` is recommended as the name for the volume group.
-  * Dedicated disks may be provided for `/var/lib/docker` on the controller nodes. In this case, do not
-    use an LV for `/var/lib/docker` but the devices provided for it.
-  * Do not configure devices that are not required for the operating system.
-  * The use of own file systems for the following mountpoints is recommended. The size of the individual partitions
-    is minimal. Depending on the node type, the individual partitions should be made larger. This applies in
-    particular to `/var/lib/docker`. On controllers at least 100 GByte should be used.
-    * `/` (10 GByte, logical volume `root`)
-    * `/home` (2 GByte, logical volume `home`)
-    * `/tmp` (5 GByte, logical volume `tmp`)
-    * `/var/lib/ceph` (50 GByte, logical volume `ceph`) (optional for storage nodes)
-    * `/var/lib/docker` (30 GByte, logical volume `docker`, do not set the `nosuid` flag on `/var/lib/docker`)
-      * When using XFS as the file system for `/var/lib/docker`, note the following: Running on XFS without `d_type` support
-        causes Docker to skip the attempt to use the `overlay` or `overlay2` driver.
-    * `/var/log/audit` (1 GByte, logical volume `audit`)
-    * `/var` (10 GByte, logical volume `var`)
-    * `swap` (min 8 GByte, logical volume `swap`)
-* Choose `No automatic updates`.
-* Choose `OpenSSH server` as software to install.
-  * **Do not install any other software component.** Everything you need will be installed later by OSISM.
-    In particular, it is not necessary to install a desktop environment.
-* After completion, restart the system.

docs/guides/deploy-guide/manager.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Manager
-sidebar_position: 1
+sidebar_position: 20
 ---
 
 # Manager
@@ -9,7 +9,7 @@ The prerequisite for the deployment of the Manager is the preparation of a
 [configuration repository](https://osism.github.io/docs/getting-started/configuration-repository).
 
 1. Install Ubuntu 22.04 on the node to be used as manager
-   (see [Provisioning of management and control plane nodes](./bootstrap.md##provisioning-of-management-and-control-plane-nodes)).
+   (see [Provisioning of management and control plane nodes](./provisioning)).
 
 2. A copy of the configuration repository is checked out on a local system,
    the so-called seed node, with which the manager node can be reached via SSH.