[DRAFT] Improve documentation for bootstrapping and manager deployment

docs/guides/configuration-guide/manager.mdx

@@ -22,8 +22,8 @@ In the example, OSISM release 7.0.5 is used.
 1. Set the new manager version in the configuration repository.
 
    ```
-   MANAGER_VERSION=7.0.5
-   sed -i -e "s/manager_version: .*/manager_version: ${MANAGER_VERSION}/g" environments/manager/configuration.yml
+   MANAGER_VERSION="7.0.5"
+   sed -i "~s,^manager_version:.*\$,manager_version: ${MANAGER_VERSION}," environments/manager/configuration.yml
    ```
 
 2. If `openstack_version` or `ceph_version` are set in `environments/manager/configuration.yml`
@@ -41,10 +41,11 @@ In the example, OSISM release 7.0.5 is used.
    <TabItem value="osism-6" label="OSISM < 7.0.0">
    If Gilt is not installed via the `requirements.txt` of the manager environment it is
    important to use a version smaller v2. The v2 of Gilt is not yet usable.
-
    ```
-   gilt overlay  # you have to do this 2x, this is not a copy & paste error
-   gilt overlay
+   python3 -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt
+     gilt overlay && gilt overlay
    ```
 
    Optionally, this is normally not necessary, it is possible to reference a specific tag of the
@@ -63,11 +64,48 @@ In the example, OSISM release 7.0.5 is used.
    workflows for changes to the configuration repository, only a generic example for Git.
 
    ```
-   git commit -a -s -m "manager: use OSISM version 7.0.5"
+   git commit -a -s -m "manager: use OSISM version ${MANAGER_VERSION?}"
    git push
    ```
 
-5. The upgrade is described in the [Manager Upgrade Guide](../upgrade-guide/manager).
+## Working with Git-Branches
+
+:::info
+
+For example, for compliance and security reasons, many organizations prefer to prepare changes to
+production systems on dedicated Git branches, roll them out to the production environment
+using the 4-eyes control principle and then finally transfer them to the `main` branch through a
+review and release process.
+
+A typical scenario is the [Manager Upgrade](../upgrade-guide/manager.mdx).
+
+OSISM offers the option of using specific GIT branches on the Manager.
+
+:::
+
+The branch can be changed in the following way:
+
+1. Create a branch
+   ```bash
+   git checkout -b YOUR-BRANCH-FOR-CHANGE-XYZ
+   ```
+2. Set the branch name of your deployment branch with the variable `configuration_git_version` in `configuration.yml`.
+   This needs always to be changed on the manager node later if you merge the current branch to another target branch.
+   ```bash
+   BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+   sed -i "~s,^configuration_git_version:.*\$,configuration_git_version: ${BRANCH}," environments/configuration.yml
+   git commit -m "Starting to work on #<issue-id>" -s environment/configuration.yml
+   git push
+   ```
+3. Login to the manager and activate the branch
+   (not needed when performing a initial manager install )
+   ```bash
+   cd /opt/configuration
+   git fetch
+   git checkout YOUR-BRANCH-FOR-CHANGE-XYZ
+   osism apply configuration
+   ```
+4. Start your work on the topic and perfom a final review when the topic is complete
 
 ## OpenSearch integration
 

docs/guides/deploy-guide/bootstrap.md

@@ -7,93 +7,150 @@ sidebar_position: 40
 
 :::info
 
-The prerequisite for bootstraping the nodes of a cluster the Manager node has to be
-prepares. What a Manager node is and how to prepare it is documented in the
-[Manager chapter of the Deploy Guide](./manager.md).
+As a prerequisite for the bootstraping the nodes of a cluster, the manager node has to be
+prepared. What a Manager node is and how to prepare it is documented in the
+[Manager chapter of the deploy guide](./manager.md).
 
 All the nodes must also have already been provisioned. How manual provisioning is done
-is documented in the [Provisioning chapter of the Deploy Guide](./provisioning.md).
+is documented in the [Provisioning chapter of the Deploy Guide](./provisioning).
 
 :::
 
 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 bare-metal nodes](./provisioning.md).
+The guide for this can be found in the section [Provisioning of bare-metal nodes](./provisioning).
 
 The following steps are applied to bootstrap all nodes. After the completion of the bootstrap,
-the nodes are already ready for use.
+the nodes are ready for the deployment of the services.
 
-1. Create operator user.
 
-   ```
-   osism apply operator -u osism
-   ```
+## Group assignments
 
-   * When using the [osism/node-image](https://github.com/osism/node-image) the user is `osism`
-     and the password of this user is `password`. If you install Ubuntu manually the user usually
-     is `ubuntu`. If you want to use any other user here, that's no problem. It is important that
-     this user has sudo rights. The password according to what you have set yourself.
+Assign the nodes to the suitable roles in `inventory/20-roles`
 
-   * The operator public SSH key has to be added in advance on all nodes to `authorized_keys` file
-     of the user specified with `-u`. This key is stored as `operator_public_key` in the file
-     `environments/configuration.yml`.
+* Assign all nodes to the "generic" group
+* Assign the nodes to the suitable groups
 
-     Alternatively (not recommended), the password can be stored in plain text in a file `/opt/configuration/secrets/conn_password`.
-     The parameter `--conn-pass-file /opt/configuration/secrets/conn_password` must then also be specified:
 
-     ```
-     osism apply operator -u osism \
-       --conn-pass-file /opt/configuration/secrets/conn_password
-     ```
+TODO: Does it make sense to describe the purpose of the groups with a few words to
+help newbies to make the right descicions?
 
-   * It is important that this user has sudo rights with `NOPASSWD`.
+| Groupname             | Description                                           |
+|-----------------------|-------------------------------------------------------|
+| `[generic]`           | Roles which do not have any service specific settings |
+| `[manager]`           | Roles for the manager nodes                           |
+| `[monitoring]`        | The log, metric and alerting infrastructure roles     |
+| `[control]`           | Openstack contoller roles                             |
+| `[compute]`           | Openstack compute nodes roles                         |
+| `[ceph-control]`      | Ceph mon servers                                      |
+| `[ceph-resource]`     | Ceph OSDs, ...                                        |
+| `[ceph-rgw:children]` | Rados Gateway roles                                   |
 
-     Alternatively (not recommended), the password can be stored in plain text in a file `/opt/configuration/secrets/become_password`.
-     The parameter `--become-pass-file /opt/configuration/secrets/become_password` must then also be specified:
 
-     ```
-     osism apply operator -u osism \
-       --become-pass-file /opt/configuration/secrets/become_password
-     ```
+## Create operator user
 
-   * If a password is required for both sudo and login, use both arguments at the same time.
+Ansible must be given access to the systems so that OSISM can orchestrate the systems.
 
-     ```
-     osism apply operator -u osism \
-       --become-pass-file /opt/configuration/secrets/become_password \
-       --conn-pass-file /opt/configuration/secrets/conn_password
-     ```
+In principle, this is achieved by the operator role. The basic command for this is as follows:
+```
+osism apply operator -u osism
+```
+
+Initial access to set up access can either be via a known password or an SSH public key already stored on the system can be used for this.
+
+The operator public SSH key has to be added in advance on all nodes to `authorized_keys` file
+of the user specified with `-u`. This key is stored as `operator_public_key` in the file
+`environments/configuration.yml`.
+
+It is important that this user has sudo rights with `NOPASSWD` to get root access for perfoming automations.
+
+Alternatively (not recommended), the password can be stored in plain text in a file `/opt/configuration/secrets/become_password`.
+The parameter `--become-pass-file /opt/configuration/secrets/become_password` must then also be specified:
+
+```
+osism apply operator -u osism \
+   --become-pass-file /opt/configuration/secrets/become_password
+```
+
+:::warning
+
+The initial user (specified i.e. with `-u osism`) will not be deactivated by default.
+It is a good idea to delete the user at this point of the installation so that the user does not
+accidentally remain active on the system with their known password and attackers can exploit this.
+This can be achieved via the [`user_delete` array in the `user` role](https://github.com/osism/ansible-collection-commons/blob/main/roles/user/defaults/main.yml).
+
+:::
+
+
+### Use a SSH public key
+
+This is the recommended way.
+
+When using custom [osism/node-image](https://github.com/osism/node-image) the build argument `ssh_public_key_user_osism` can be used
+to add the public key to the node image.
+If you us this method, no additional flags are needed for executing the "operator" role.
 
-   * When using the [osism/node-image](https://github.com/osism/node-image) the user is `osism` and the password of this
-     user is `password`. If you install Ubuntu manually the user usually is `ubuntu`. The password according to what you
-     have set yourself
+### Use a password
 
-2. Proxy deployment (optional). This is only necessary if you use the proxy on the manager to enable external access to
-   the nodes.
+When using the [osism/node-image](https://github.com/osism/node-image) the user is `osism`
+and the password of this user is `password`. If you install Ubuntu manually the user usually
+is `ubuntu`. If you want to use any other user here, that's no problem. It is important that
+this user has sudo rights. The password according to what you have set yourself.
+
+When using a custom [osism/node-image](https://github.com/osism/node-image) the build argument `password_hash` can be used
+to define your own password for the node image.
+
+
+The parameter `--conn-pass-file /opt/configuration/secrets/conn_password` must be specified:
+
+```
+echo "password" > /opt/configuration/secrets/conn_password
+osism apply operator -u osism \
+  --limit 'all:!manager' \
+  --conn-pass-file /opt/configuration/secrets/conn_password
+```
+
+If a password is required for both sudo and login, use both arguments at the same time.
+
+```
+osism apply operator -u osism \
+   --become-pass-file /opt/configuration/secrets/become_password \
+   --conn-pass-file /opt/configuration/secrets/conn_password
+```
+
+## Optional: Using a proxy with your environment
+
+
+1. Optional: Deploy squid proxy on the manager:
 
    ```
    osism apply squid
    ```
 
-3. Proxy configuration (optional). This is only necessary if you use the proxy on the manager to enable external access to
-   the nodes.
+   This is only necessary if you use the proxy on the manager to enable external access of the nodes to the internet.
+
+2. Have a look to the [proxy documentation](../configuration-guide/proxy.md) and configure it before running this playbook.
+3. Apply proxy settings to the nodes
 
    ```
    osism apply proxy
    ```
 
-4. Network configuration. It is recommended to backup the existing network configuration.
+## Network configuration. It is recommended to backup the existing network configuration.
+
+1. Configure the network setup
+   Have a look to the [network documentation](../configuration-guide/network) and configure it before running this playbook
 
    ```
    osism apply network
    ```
 
-5. Reboot (optional). The reboot at this point is recommended to ensure that the network configuration is working.
+2. Recommendend, but not mandatory: The reboot at this point is recommended to ensure that the network configuration is working.
 
    ```
    osism apply reboot -l 'all:!manager' -e ireallymeanit=yes
    ```
 
-6. Check if all systems are reachable (you probably have to do this several times until all systems are accessible).
+3. Check if all systems are reachable (you probably have to do this several times until all systems are accessible).
 
    ```
    osism apply ping
@@ -103,7 +160,7 @@ the nodes are already ready for use.
 
      ```
      fatal: [net003]: UNREACHABLE! => {"changed": false, "msg": "Connection timed
-     out.", "unreachable": true}``
+     out.", "unreachable": true}
      ```
 
    * System has already been rebooted and is not accessible via the network.
@@ -114,41 +171,45 @@ the nodes are already ready for use.
      to host\r", "unreachable": true}
      ```
 
-7. Refresh facts.
+## Bootstrap the nodes
+
+1. [Refresh facts](../operations-guide/manager/facts).
 
    ```
    osism apply facts
    ```
 
-8. Bootstrap.
+2. Bootstrap nodes
 
    ```
    osism apply bootstrap
    ```
 
-9. Reboot (non-optional). Since the kernel version often changes after the initial bootstrap,
+3. Reboot (non-optional). Since the kernel version often changes after the initial bootstrap,
    the reboot should always be performed.
 
    ```
    osism apply reboot -l 'all:!manager' -e ireallymeanit=yes
    ```
 
-10. Check if all systems are reachable (you probably have to do this several times until all systems are accessible).
+4. Check if all systems are reachable (you probably have to do this several times until all systems are accessible).
+
+   ```
+   osism apply ping
+   ```
 
-    ```
-    osism apply ping
-    ```
+## Finalize Boostrapping
 
-11. Prepare the SSH configuration of the manager node.
+1. Prepare the SSH configuration of the manager node.
 
-    ```
-    osism apply sshconfig
-    ```
+   ```
+   osism apply sshconfig
+   ```
 
-12. Make all SSH public keys known.
+2. Make all SSH public keys known.
 
-    ```
-    osism apply known-hosts
-    ```
+   ```
+   osism apply known-hosts
+   ```
 
 Ready. All nodes are now bootstrapped and available to deploy services.

docs/guides/deploy-guide/index.md

@@ -15,8 +15,10 @@ What a configuration repository is and how it is created is described in the
 
 :::
 
-* Step 1: [Preparation of the seed node](./seed.md)
-* Step 2: [Preparation of the manager node](./manager.md)
-* Step 3: [Provisioning of the bare-metal nodes](./provisioning.md)
-* Step 4: [Bootstrap of the bare-metal nodes](./bootstrap.md)
-* Step 5: [Deployment of the services](./services/index.md)
+* Step 1: [Creation of a configuration repository](../configuration-guide/configuration-repository#creating-a-new-configuration-repository)
+* Step 2: [Preparation of the seed node](./seed)
+* Step 3: [Preparation of the manager node](./manager)
+* Step 4: [Provisioning of the bare-metal nodes](./provisioning)
+* Step 5: [Bootstrap of the bare-metal nodes](./bootstrap)
+* Step 6: [Deployment of the services](./services)
+