Overall improvements (pt. 2) (#157)

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

docs/guides/configuration-guide/configuration-repository.md

@@ -67,7 +67,7 @@ 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).
+[Configuration Guide > Manager > Stable release](manager#stable-release).
 
 ```
 MANAGER_VERSION=6.0.0 gilt overlay
@@ -85,6 +85,8 @@ MANAGER_VERSION=6.0.0 gilt overlay
 The initial content for this repository is generated using the
 [cookiecutter](https://github.com/osism/cfg-cookiecutter).
 
+### Git repository
+
 The content generated by the cookiecutter in the `output/configuration` directory is
 committed to a new Git repository. By default, it is assumed that the configuration
 repository is stored on GitHub. This can also be GitLab or an internal Git service
@@ -96,53 +98,78 @@ Host and path to the Git repository are specified via the `git_` parameters: The
 ```
   [8/20] git_host (github.com):
   [9/20] git_port (22):
-  [10/20] git_repository (YOUR_ORG/YOUR_NEW_CONFIGURATION_REPOSITORY): osism/new-environment
+  [10/20] git_repository (YOUR_ORG/YOUR_NEW_CONFIGURATION_REPOSITORY): regiocloud/configuration
   [11/20] git_username (git):
   [12/20] git_version (main):
 ```
 
 In this case, the generated configuration in the `output/configuration` directory is
-stored on GitHub in the `osism/new-environment` repository.
+stored on GitHub in the `regiocloud/configuration` repository.
 
-When you want to use a stable release this is done via the parameter `manager_version`
-By default, this is always set to `latest`. If, for example, the stable release `6.0.0`
-is to be used, the value for this parameter is set to `6.0.0`.
+### Creation
+
+In this example a new configuration repository is created with the defaults. The latest versions of
+OSISM are used. The use of a stable release is described in the section
+[Use of a stable release](#use-of-a-stable-release).
+
+The directory `output` is created and used as output volume.
 
 ```
-manager_version [latest]: 6.0.0
+mkdir output
 ```
 
-If the `manager_version` parameter is set to a stable release then it is no longer necessary
-to set the `ceph_version` and `openstack_version` parameters. These are then no longer needed
-and are ignored The used versions result from the `manager_version`.
+The cookiecutter is executed within a container. Docker must be usable on the system
+on which the cookiecutter is to be used. It should also work with podman.
 
 ```
-$ mkdir output
-$ docker run --rm -v $(pwd)/output:/output -it quay.io/osism/cookiecutter
-  [1/20] with_ceph (1):
-  [2/20] ceph_network_backend (192.168.80.0/20):
-  [3/20] ceph_network_frontend (192.168.64.0/20):
-  [4/20] ceph_version (quincy):
-  [5/20] domain (osism.xyz):
-  [6/20] fqdn_external (api.osism.xyz):
-  [7/20] fqdn_internal (api-int.osism.xyz):
-  [8/20] git_host (github.com):
-  [9/20] git_port (22):
-  [10/20] git_repository (YOUR_ORG/YOUR_NEW_CONFIGURATION_REPOSITORY):
-  [11/20] git_username (git):
-  [12/20] git_version (main):
-  [13/20] ip_external (192.168.96.9):
-  [14/20] ip_internal (192.168.32.9):
-  [15/20] manager_version (latest):
-  [16/20] name_server (149.112.112.112):
-  [17/20] ntp_server (de.pool.ntp.org):
-  [18/20] openstack_version (2023.1):
-  [19/20] project_name (configuration):
+docker run --rm -v $(pwd)/output:/output -it quay.io/osism/cookiecutter
+[1/20] with_ceph (1):
+[2/20] ceph_network_backend (192.168.80.0/20):
+[3/20] ceph_network_frontend (192.168.64.0/20):
+[4/20] ceph_version (quincy):
+[5/20] domain (osism.xyz):
+[6/20] fqdn_external (api.osism.xyz):
+[7/20] fqdn_internal (api-int.osism.xyz):
+[8/20] git_host (github.com):
+[9/20] git_port (22):
+[10/20] git_repository (YOUR_ORG/YOUR_NEW_CONFIGURATION_REPOSITORY):
+[11/20] git_username (git):
+[12/20] git_version (main):
+[13/20] ip_external (192.168.96.9):
+[14/20] ip_internal (192.168.32.9):
+[15/20] manager_version (latest):
+[16/20] name_server (149.112.112.112):
+[17/20] ntp_server (de.pool.ntp.org):
+[18/20] openstack_version (2023.1):
+[19/20] project_name (configuration):
 [...]
 ```
 
 Since we run the cookiecutter inside a container, the user rights are not correct
-afterwards and have to be changed with `sudo chown -R $USER: output/`.
+afterwards and have to be changed.
+
+```
+sudo chown -R $USER: output/
+```
+
+### Use of a stable release
+
+When you want to use a stable release this is done via the parameter `manager_version`.
+By default, this is always set to `latest`. If, for example, the stable release `6.0.0`
+is to be used, the value for this parameter is set to `6.0.0`.
+
+The current stable release is listed at [release.osism.tech](https://release.osism.tech/).
+Always check there in advance and do not copy the stable release used here as an example.
+
+```
+manager_version [latest]: 6.0.0
+```
+
+If the `manager_version` parameter is set to a stable release then it is no longer necessary
+to set the `ceph_version` and `openstack_version` parameters. These are then no longer needed
+and are ignored. The used versions result from the `manager_version`.
+
+### Make commit
 
 The content is now committed to the previously created Git repository.
 
@@ -159,8 +186,8 @@ The `secrets` directory is not stored in the Git repository. Its contents can be
 stored in a suitable location.
 
 The `secrets` directory contains an SSH key pair which is used as a deploy key to
-make the configuration repository available on the manager node later. The public
-SSH key is stored in the file `secrets/id_rsa.configuration.pub`.
+make the configuration repository available on the manager node later. Write access
+is not required. The public SSH key is stored in the file `secrets/id_rsa.configuration.pub`.
 
 How to add a deploy key on GitHub is documented in
 [Managing deploy keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys).
@@ -169,7 +196,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 Guides](./).
+[Configuration Guide](./).
 
 ### Notes
 
@@ -241,12 +268,12 @@ For example, the inventory needs to be built. All further information can be fou
   </tr>
   <tr>
     <td><code>ip_external</code></td>
-    <td>The external IP address of the API (resolves to `fqdn_external`)</td>
+    <td>The external IP address of the API (resolves to <code>fqdn_external</code>)</td>
     <td><code>192.168.96.9</code></td>
   </tr>
   <tr>
     <td><code>ip_internal</code></td>
-    <td>The internal IP address of the API (resolves to `fqdn_internal`)</td>
+    <td>The internal IP address of the API (resolves to <code>fqdn_internal</code>)</td>
     <td><code>192.168.32.9</code></td>
   </tr>
   <tr>

docs/guides/configuration-guide/index.md

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

docs/guides/configuration-guide/manager.md

@@ -8,7 +8,8 @@ sidebar_position: 20
 ## Stable release
 
 It is recommended to use a stable release of OSISM. All available releases are listed on
-[release.osism.tech](https://release.osism.tech).
+[release.osism.tech](https://release.osism.tech). Always check there in advance and do not copy
+the stable release used here as an example.
 
 In the example, OSISM release 6.0.0 is used.
 

docs/guides/deploy-guide/index.md

@@ -1,11 +1,11 @@
 ---
-sidebar_label: Deploy Guides
+sidebar_label: Deploy Guide
 sidebar_position: 10
 ---
 
-# Deploy Guides
+# Deploy Guide
 
-💡 The Deploy Guides describe how to deploy individual nodes and services.
+💡 The Deploy Guide describe how to deploy individual nodes and services.
 
 A classification is made for services. For example, all infrastructure services
 such as RabbitMQ or MariaDB are covered in the Infrastructure Guide.
@@ -16,7 +16,7 @@ building a new machine.
 Before deploying services to nodes, they must all be bootstrapped. This is covered
 in the Bootstrap Guide.
 
-The guides always assume that a node is already initially accessible via SSH and only
+The guide always assume that a node is already initially accessible via SSH and only
 needs to be bootstrapped and integrated into the machine. Deploying bare-metal nodes
 with an operating system is not part of the Deploy Guides and is covered in the
 Advanced Guides.

docs/guides/deploy-guide/manager.md

@@ -5,9 +5,6 @@ sidebar_position: 20
 
 # Manager
 
-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](./provisioning)).
 
@@ -70,7 +67,7 @@ ANSIBLE_USER=osism \
   export ANSIBLE_ASK_VAULT_PASS=True
   ```
 
-## Network configuration
+## Apply the network configuration
 
 Most of the parameters required for Ansible (`ANSIBLE_BECOME_ASK_PASS`, `ANSIBLE_ASK_PASS`, `ANSIBLE_USER`, ...)
 in the previous step are no longer necessary. If Ansible Vault is used, however, `ANSIBLE_ASK_VAULT_PASS`

docs/guides/operations-guide/index.md

@@ -1,9 +1,9 @@
 ---
-sidebar_label: Operations Guides
+sidebar_label: Operations Guide
 sidebar_position: 30
 ---
 
-# Operations Guides
+# Operations Guide
 
 ## Node states
 

docs/guides/troubleshooting-guide/index.md

@@ -1,8 +1,8 @@
 ---
-sidebar_label: Troubleshooting Guides
+sidebar_label: Troubleshooting Guide
 sidebar_position: 40
 ---
 
-# Troubleshooting Guides
+# Troubleshooting Guide
 
-💡 The Troubleshooting Guides describe how to solve issues.
+💡 The Troubleshooting Guide describe how to solve issues.

docs/guides/upgrade-guide/index.md

@@ -1,9 +1,9 @@
 ---
-sidebar_label: Upgrade Guides
+sidebar_label: Upgrade Guide
 sidebar_position: 20
 ---
 
-# Upgrade Guides
+# Upgrade Guide
 
 In the examples, the pull of images (if supported by a role) is always run first. While
 this is optional, it is recommended to speed up the execution of the upgrade action in

docs/guides/upgrade-guide/manager.md

@@ -9,7 +9,7 @@ Always read the release notes first to learn what has changed and what
 adjustments are necessary
 
 1. Update the OSISM release in use in the configuration repository as described in
-   [Configuration Guides > Manager > Stable release](../configuration-guide/manager#stable-release).
+   [Configuration Guide > Manager > Stable release](../configuration-guide/manager#stable-release).
 
 2. Update the configuration repository on the manager.