-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improve the configuration repository docs
Signed-off-by: Christian Berendt <[email protected]>
- Loading branch information
Showing
1 changed file
with
58 additions
and
52 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,7 +9,10 @@ The configuration required for OSISM is stored in a single Git monorepo, the con | |
|
|
||
| ## Configuration repository layout | ||
|
|
||
| A configuration repository is always composed of the same basic layout. | ||
| A configuration repository is always composed of the same basic layout. This section describes what | ||
| content is available in a configuration repository. In the section | ||
| [Creating a new configuration repository](#creating-a-new-configuration-repository) is the creation | ||
| of a new configuration repository documented. | ||
|
|
||
| * **`environments` directory** | ||
| * **`inventory` directory** | ||
|
|
@@ -26,40 +29,31 @@ A configuration repository is always composed of the same basic layout. | |
| 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. | ||
|
|
||
| To use Gilt the dependencies are installed first. If Gilt is not installed via the `requirements.txt` it | ||
| is important to use a version smaller v2. The v2 of Gilt is not yet usable. | ||
|
|
||
| ``` | ||
| 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 | ||
| ``` | ||
|
|
||
| ## Creating a new configuration repository | ||
|
|
||
| The initial content for this repository is generated using the | ||
| [cookiecutter](https://github.com/osism/cfg-cookiecutter). | ||
|
|
||
| Cookiecutter generates a simple bootstrap configuration for your new cluster by prompting | ||
| you for the basic details of the new system environment. | ||
|
|
||
| The configuration repository will not be created on the future manager node. It is created on a local | ||
| workstation. If the local workstation cannot be used for this purpose, a dedicated virtual system can | ||
| be used. It is important for the further process that no packages are installed manually on the manager. | ||
| Especially not Docker. | ||
| be used. More detailed information about this topic can be obtained in the documentation of the | ||
| [seed node](../deploy-guide/seed.md). | ||
|
|
||
| ### Git repository | ||
| ### Step 1: Preparation | ||
|
|
||
| #### Decide where to store the 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 | ||
| as well. | ||
|
|
||
| Host and path to the Git repository are specified via the `git_` parameters: The | ||
| `git_` parameters do not specify the path to the cookiecutter to use. | ||
| Host and path to the Git repository are specified via the `git_` parameters. These are | ||
| requested in the 2nd step.The `git_` parameters do not specify the path to the cookiecutter | ||
| to use. | ||
|
|
||
| ``` | ||
| [8/20] git_host (github.com): | ||
|
|
@@ -72,27 +66,36 @@ Host and path to the Git repository are specified via the `git_` parameters: The | |
| In this case, the generated configuration in the `output/configuration` directory is | ||
| stored on GitHub in the `regiocloud/configuration` repository. | ||
|
|
||
| ### Creation | ||
| #### Have a look at the parameters reference | ||
|
|
||
| At the end of the chapter you find the parameters reference. The parameters listed there are | ||
| queried during the execution of Cookiecutter. | ||
|
|
||
| ### Step 2: Execute cookiecutter to generate the basic layout/configuration | ||
|
|
||
| In this example a new configuration repository is created with the defaults. The current stable | ||
| version of OSISM is used. The use of latest is described in the section | ||
| [Use of latest](#use-of-latest). | ||
|
|
||
| The directory `output` is created and used as output volume. | ||
| The directory `output` is created and used as output volume. It is only necessary to create the directory. | ||
|
|
||
| ``` | ||
| mkdir output | ||
| ``` | ||
|
|
||
| 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. | ||
| The cookiecutter is executed within a container. [Docker must be usable on the system](https://docs.docker.com/engine/install/) on which the cookiecutter is to be used. It should also work with podman. | ||
|
|
||
| ``` | ||
| docker run \ | ||
| -e TARGET_UID="$(id -u)" \ | ||
| -e TARGET_GID="$(id -g)" \ | ||
| -v $(pwd)/output:/output \ | ||
| --rm -it quay.io/osism/cookiecutter | ||
| ``` | ||
|
|
||
| After the call, a few parameters are asked for. The parameters are documented in detail in the [Parameters reference](#parameters-reference) section. | ||
|
|
||
| ``` | ||
| [1/20] with_ceph (1): | ||
| [2/20] with_keycloak (0): | ||
| [3/20] ceph_network_backend (192.168.80.0/20): | ||
|
|
@@ -116,56 +119,46 @@ docker run \ | |
| [...] | ||
| ``` | ||
|
|
||
| ### Use of latest | ||
|
|
||
| When you want to use latest this is done via the parameter `manager_version`. | ||
| By default, this is always set to the current stable version. | ||
|
|
||
| ``` | ||
| manager_version [7.0.0]: latest | ||
| ``` | ||
|
|
||
| If the `manager_version` parameter is set to `latest` it is also possible to explicitly | ||
| set the `openstack_version` and the `ceph_version`. | ||
| ### Step 3: Upload the new configuration to the remote git repository | ||
|
|
||
| ### Make commit | ||
|
|
||
| The content is now committed to the previously created Git repository. | ||
| How to add a deploy key on GitHub is documented in | ||
| Add the initial configuration state to the repository. 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). | ||
| Read permissions are sufficient. | ||
|
|
||
| ``` | ||
| $ git clone [email protected]:YOUR_ORG/YOUR_NEW_CONFIGURATION_REPOSITORY.git YOUR_NEW_CONFIGURATION_REPOSITORY | ||
| $ cp -r output/configuration/* output/configuration/.gitignore YOUR_NEW_CONFIGURATION_REPOSITORY | ||
| $ cp -r output/configuration/{*,.gitignore} YOUR_NEW_CONFIGURATION_REPOSITORY | ||
| $ cd YOUR_NEW_CONFIGURATION_REPOSITORY | ||
| $ git add .gitignore * | ||
| $ git commit -m "Initial commit" | ||
| $ git add -A . | ||
| $ git commit -m "Initial commit after bootstrap" | ||
| $ git push | ||
| ``` | ||
|
|
||
| The content is now committed to the previously created Git repository. | ||
|
|
||
| :::warning | ||
|
|
||
| The `secrets` directory is not stored in the Git repository. Its contents can be | ||
| stored in a suitable location. | ||
| stored in a trustworthy 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. Write access | ||
| is not required. The public SSH key is stored in the file `secrets/id_rsa.configuration.pub`. | ||
|
|
||
| ::: | ||
|
|
||
| ### Post-processing | ||
| ### Step 4: Post-processing of the generated configuration | ||
|
|
||
| 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](./). | ||
| [Configuration Guide](../configuration-guide/). | ||
|
|
||
| ### Notes | ||
| The password for Ansible Vault encrypted files, is stored at `secrets/vaultpass`. | ||
| The password of the generated Keepass file is `password`. This should be changed if the Keepass file is used. | ||
|
|
||
| * The password for Ansible Vault encrypted files, ist stored at `secrets/vaultpass`. | ||
| * The password of the generated Keepass file is `password`. This has to be changed. | ||
| Version all your configuration changes using git. | ||
|
|
||
| ### Parameters | ||
| ## Parameter reference | ||
|
|
||
| | Parameter | Description | Default | | ||
| |:---------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------| | ||
|
|
@@ -183,13 +176,26 @@ For example, the inventory needs to be built. All further information can be fou | |
| | `ip_external` | The external IP address of the API (resolves to `fqdn_external`) | `192.168.96.9` | | ||
| | `ip_internal` | The internal IP address of the API (resolves to `fqdn_internal`) | `192.168.32.9` | | ||
| | `manager_version` | The version of OSISM. An overview of available OSISM releases can be found on [release.osism.tech](https://release.osism.tech) | `7.0.0` | | ||
| | `name_server` | Nameserver. Only one nameserver is set here because the query of multiple values in Cooiecutter is weird. Add more nameservers afterwards. | `149.112.112.112` | | ||
| | `ntp_server` | NTP server. Only one NTP server is set here because the query of multiple values in Cooiecutter is weird. Add more NTP servers afterwards. | `de.pool.ntp.org` | | ||
| | `name_server` | Nameserver. Only one nameserver is set here because the query of multiple values in Cookiecutter is weird. Add more nameservers afterward. | `149.112.112.112` | | ||
| | `ntp_server` | NTP server. Only one NTP server is set here because the query of multiple values in Cookiecutter is weird. Add more NTP servers afterward. | `de.pool.ntp.org` | | ||
| | `openstack_version` | The version of OpenStack. When using a stable OSISM release (`manager_version != latest`), this value is ignored | `2023.2` | | ||
| | `project_name` | Name of the configuration repository directory | `configuration` | | ||
| | `with_ceph` | `1` to use Ceph, `0` to not use Ceph | `1` | | ||
| | `with_keycloak` | `1` to prepare Keycloak integration , `0` to not prepare Keycloak integration | `0` | | ||
|
|
||
| ### Use of latest | ||
|
|
||
| When you want to use latest this is done via the parameter `manager_version`. | ||
| By default, this is always set to the current stable version. | ||
|
|
||
| ``` | ||
| manager_version [7.0.0]: latest | ||
| ``` | ||
|
|
||
| If the `manager_version` parameter is set to `latest` it is also possible to explicitly | ||
| set the `openstack_version` and the `ceph_version`. | ||
|
|
||
|
|
||
| ## Preparing a new configuration repository | ||
|
|
||
| ### Manager environment | ||
|
|
||