Skip to content

Commit

Permalink
add documentation
Browse files Browse the repository at this point in the history 
Signed-off-by: Marc Schöchlin <[email protected]>
  • Loading branch information
@scoopex
scoopex committed Jun 14, 2024
1 parent 1f38f77 commit 397a590
Show file tree
Hide file tree
Showing 15 changed files with 359 additions and 139 deletions.
52 changes: 45 additions & 7 deletions docs/guides/configuration-guide/manager.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
UPGRADE_RELEASE="7.0.5"
sed -i "~s,^manager_version:.*\$,manager_version: ${UPGRADE_RELEASE}," environments/manager/configuration.yml
```

2. If `openstack_version` or `ceph_version` are set in `environments/manager/configuration.yml`
Expand All @@ -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
Expand All @@ -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 ${UPGRADE_RELEASE?}"
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

Expand Down
181 changes: 119 additions & 62 deletions docs/guides/deploy-guide/bootstrap.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,78 +22,131 @@ The guide for this can be found in the section [Provisioning of bare-metal nodes
The following steps are applied to bootstrap all nodes. After the completion of the bootstrap,
the nodes are already ready for use.

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
``
* 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
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.
2. Proxy deployment (optional). This is only necessary if you use the proxy on the manager to enable external access to
the nodes.
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`.
```
osism apply squid
```
It is important that this user has sudo rights with `NOPASSWD` to get root access for perfoming automations.
3. Proxy configuration (optional). This is only necessary if you use the proxy on the manager to enable external access to
the nodes.
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 proxy
```
```
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.
### Use a password
4. Network configuration. It is recommended to backup the existing network configuration.
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
The proxy deployment is optional. This is only necessary if you use the proxy on the manager to enable external access of
the nodes to the internet.
Deploy squid proxy on the manager:
```
osism apply squid
```
Configure the proxy values unter `proxy_proxies` and `docker_configure_proxy`.
This is only necessary if you use the proxy on the manager to enable external access to the nodes.
```
osism apply proxy
```
## Network configuration. It is recommended to backup the existing network configuration.
1. Configure the network setup
```
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
Expand All @@ -114,41 +167,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
osism apply bootstrap -l 'all:!manager'
```
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.
12 changes: 7 additions & 5 deletions docs/guides/deploy-guide/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
* Step 2: [Preparation of the manager node](./manager)
* Step 3: [Provisioning of the bare-metal nodes](./provisioning)
* Step 4: [Bootstrap of the bare-metal nodes](./bootstrap)
* Step 5: [Deployment of the services](./services)
* 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)

20 changes: 13 additions & 7 deletions docs/guides/deploy-guide/manager.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ on the seed node. The deployment of the seed node itself is documented in the
```
cd environments/manager
```
If you are working with git branches,
read [the instructions](../configuration-guide/manager.mdx).

### Step 1: Create operator user

Expand All @@ -67,14 +69,16 @@ ANSIBLE_USER=osism \
./run.sh operator
```

When the `./run.sh operator` is executed, the following prompts are displayed.
When the `./run.sh operator` is executed, the following prompts are displayed:

| Prompt | Value | Comment |
|:---------------------------------------------|:---------------------------------------------------|:-------------------------------------|
| `SSH password:` | Password so that the `ANSIBLE_USER` can login | Enabled by `ANSIBLE_ASK_PASS` |
| `BECOME password[defaults to SSH password]:` | Password so that the `ANSIBLE_USER` can use `sudo` | Enabled by `ANSIBLE_BECOME_ASK_PASS` |
| `Vault password:` | Value of `secrets/vaultpass` | Enabled by `ANSIBLE_ASK_VAULT_PASS` |

**Useful information if something goes wrong in the step described**

* If a password is required to login to the manager node, `ANSIBLE_ASK_PASS=True` must be set.
* If an SSH key is required to login to the manager node, the key has to be added on the manager
node to `~/.ssh/authorized_keys` in the home directory of the user specified as `ANSIBLE_USER` first.
Expand Down Expand Up @@ -112,13 +116,15 @@ in the Ansible documentation.
| `ANSIBLE_BECOME_ASK_PASS` | Boolean | Toggle to prompt for privilege escalation password. |
| `ANSIBLE_SSH_ARGS` | String | If set, this will override the Ansible default ssh arguments. |
| `ANSIBLE_USER` | String | The user Ansible ‘logs in’ as. |
To verify the creation of the operator user, use the private key file `id_rsa.operator`. Make


To verify the proper creation of the operator user, use the private key file `id_rsa.operator`. Make
sure you purge all keys from ssh-agent identity cache using `ssh-add -D`. You can print the list
using `ssh-add -l`. The list should be empty.

```
ssh-add -D
ssh -o IdentitiesOnly=yes -i id_rsa.operator dragon@testbed-manager
ssh -o IdentitiesOnly=yes -i PATH_TO_YOUR_SECRETS/id_rsa.operator dragon@YOUR_MANAGER_NODE
```

### Step 2: Apply the network configuration
Expand All @@ -140,7 +146,7 @@ Then you can deploy the network configuration with the network role.
./run.sh network
```

Upon completion of the network configurtion, a node reboot should be performed to ensure the configuration
Upon completion of the network configuration, a node reboot should be performed to ensure the configuration
is functional and reboot safe. Since network services are not restarted automatically, later changes to the
network configuration are not effective without a manual apply of the network configuration or reboot of the
nodes.
Expand Down Expand Up @@ -199,9 +205,9 @@ Finally, the Ansible Vault password is made known on the manager node. Before th
with the `dragon` user.

```
ssh -o IdentitiesOnly=yes -i PATH_TO_YOUR_SECRETS/id_rsa.operator dragon@YOUR_MANAGER_NODE
osism set vault password
Ansible Vault password: ********
```

Ready. The manager is now prepared and you can continue with the bootstrap of the other nodes.
The seed node used until here is no longer necessary.
Ready. The manager is now prepared, and you can continue with the bootstrap of the other nodes.
The seed node used until here is now no longer necessary.
Loading

0 comments on commit 397a590

Please sign in to comment.