NFDI4Earth Server Administration

Version: v3.7

Welcome aboard to our central server administration project! This is the central space for developing and refining our Ansible-driven solution to administrate the whole server infrastructure of all the NFDI4Earth components.

Roles in detail

Here you can find some specific documentations related to the different roles. These are auto-generated using ansible-doctor

Basics

How to use this package

Install ansible

# set up a virtenv at current location
python3 -m venv venv/ --prompt "$(pwd | grep -o "[^/]*$")"
# activate virtenv
. venv/bin/activate
# install requirements
pip install -r requirements.txt
# verify installation
ansible --version

Handle host_vars

You can find details in the structure section.

In a nutshell: Get host_vars by running the playbook handle_vars.yaml.

Preparations

Create directories:

MKDIR vault/secrets
MKDIR host_vars

Create empty files for the secrets you would like to pull. For example, if you would like to pull the secrets related to the Knowledge Hub, create files vault/secrets/knowledgehub_prod and vault/secrets/knowledgehub_test. Into these files, copy the passwords you received from an admin.

Install sshpass with:

sudo apt-get install sshpass

You'll need to add the host fingerprint to your known hosts. You can look up the IP address in inventory/hosts.yaml. Then, try to connect via SSH and select "yes". For example, execute for the KH:

ssh service@141.76.56.227

Also add the supportapps_prod server (141.76.57.63) to your known hosts.

Running the playbook handle_vars

This is the basic command:

ansible-playbook handle_vars.yaml

Optional arguments:

-k | ssh password of supportapps VM

You need to set this, when you pull from or push the files to the central storage (supportapps VM)!

--ask-vault-pass | password to decrypt vars file of supportapps VM

You need to set this argument when the var-file supportapps_prod is encrypted and ansible has to read/decrypt it!

When you want to establish a connection to the central VM (that stores the host_vars), we need a prompt for the SSH-password (-k).

ansible-playbook handle_vars.yaml -k

And when you are going to push to or pull from the central VM, we need a prompt for the vault-password, additionally (--ask-vault-pass):

ansible-playbook handle_vars.yaml -k --ask-vault-pass

Note: Alternatively, you can also store this pass in a file and tell ansible where to find it via ansible.cfg by adding:

e.g.: vault_password_file = ./my/vault/secrets/supportapps_prod

Pulling and decrypting secrets

The playbook handle_vars offers several options. If you want to pull and decrypt secrets, do the following.

Run

ansible-playbook handle_vars.yaml -k --ask-vault-pass

and choose option 4 (pull). Press ENTER twice, unless you used different paths than the default paths.

Then, run again:

ansible-playbook handle_vars.yaml -k

This time, choose option 5 (decrypt), which will decrypt the yaml files in host_vars.

Run a playbook

Before running a playbook, consider taking a snapshot of the VM in the ZIH cloud.

Run your first playbook by reading the system informations of all hosts.

ansible-playbook system.yaml --vault-id <hostname resp. name of vault-password-file>

If you do not want to store the password file on your system resp. you want to handle it in a separate PW-manager, you can ask for an interactive prompt (to enter the vault-password)

Run only dedicated roles in a playbook

All host-related playbooks (onestop4all, edutrain, knowledgehub, supportapps &webapps) have set tags per included role. This enables you to execute only dedicated roles by defining one or more tags during execution:

ansible-playbook onestop4all.yaml --tags main

Add a new host

  1. add host to ./inventory/hosts.yaml

    • basically
    • to all the related groups

  2. add new host_vars files with the same name as hostname in hosts.yaml

Add a new role

The simplest starting point is to add a new directory inside [roles][./roles] containing at least a tasks directory with a main.yaml inside.

Just have a look a the other roles for some inspiration.

NOTE Add tags and comments (esp.) to the main.yaml files, as we auto-generate a documentation from them!

Update docs

There is currently no automatic update procedure on the auto-generated docs.

python collect_docs.py

What it does:

Further resources