Ansible-Role "<ROLE_NAME>"

What does it do?

This role provides all necessary tasks to .

What do I need?

Prerequisites

To use this role, the following software must be installed on your workstation:

• ansible

To deploy this role to a managed host, the following software must be installed on the target:

• Python3
• SSHd

Dependencies

Other roles required by this role can be easily installed using ansible-galaxy if necessary. As the roles reside in SLUB's local Git server instance, you might need a password for certain repositories despite most of them being publicly available. This command will install the required roles in the correct location so they are found in the search path:

	ansible-galaxy install -r requirements.yml -p ../

Infrastructure

It is recommended to use Debian VMs as deployed by SLUB's GUBS tool with this role. Otherwise you will not have access to the software packages that are located in SLUB's private Debian package repository.

Can i have a Quick Start?

Most options already have sensible defaults in ansible.cfg. However, you can override these defaults using CLI options/flags if you want to. The flags can be combined if necessary, and most of them have long versions as well. Get more information using ansible-playbook --help.

To simply run the playbook, just call the site.yml playbook like this:

ansible-playbook site.yml -u <username>

If you want to limit the execution to a subset of all hosts that are listed in the inventory, use the -l or --limit option like this:

ansible-playbook site.yml -l <hostna*>
ansible-playbook site.yml -l <hostname>
ansible-playbook site.yml -l <hostname1>:<hostname2>:...
ansible-playbook site.yml -l <inventory_group>
ansible-playbook site.yml --limit=<hostna*>

If you do not have Vault password files in the directory above the role direcory, you have to give the Vault password before execution:

	ansible-playbook site.yml --ask-vault-pass

You can use your own inventory file by adding the -i or --inventory=INVENTORY option:

	ansible-playbook site.yml -i inventory.yml
	ansible-playbook site.yml --inventory=inventory.yml

Tasks in this role have been tagged to enable users to only run subsets of tasks. This can be leveraged to decrease run times or run only certain tasks after small changes. To list all available tags, use:

	ansible-playbook site.yml --list-tags

You can then run only certain tagged tasks by using the --tags option:

	ansible-playbook site.yml -t tag1,tag2,...,tagN
	ansible-playbook site.yml --tags=tag1,tag2,...,tagN

How can I run tests?

Tests have been implemented using the Molecule framework. The details on using the test suite are described below molecule/.

To run some quick tests, you can do:

# pure syntax check
molecule syntax
# run yamllint and ansible-lint
molecule lint
# list available test scenarios, e.g. based on different OS images or platforms
molecule list
# create the test environment for a specific scenario (can be left out for "default")
molecule create [-s scenario]
# run your tasks against the test env
molecule converge [-s scenario]      # multiple times if needed
# run idempotence checks to se if any of the tasks keeps changing (subsequent runs shouldn't trigger changes)
molecule idempotence [-s scenario]
# cleanup test env (remove VM/container)
molecule destroy [-s scenario]

We recommend running those tests before pushing any code to the Git server.

On every git push, the GitLab-CI pipeline will run a similar set of tests to ensure that all changes are working. Find the details in the .gitlab-ci.yml file located at the project root directory.

What can be configured?

Ansible Role

Many variables have been "hidden" in encrypted Ansible Vaults. For security reasons, these Vaults are maintained in a separate private internal repository of SLUB's Git. However, in order to better understand the data within the vaults, you can find \*.vault.example files below the vars/ directory.

If you work outside of SLUBArchive and have no access to the vault repository, make sure to put the necessary vaults in the expected paths at ../ansible_vaults/<ROLENAME>/.

Variable defaults have been set in defaults/main.yml. You can overwrite them with your own values by setting them in vars/main.yml.

Git configuration

Just run the setup_gitconfig.sh script that comes with the repo to correctly setup all necessary local Git configurations.

What changes have been made lately?

All changes can be found in the CHANGELOG file located at the project root directory. Alternatively, you can have a look at the commit log to get a detailed view.

Who is maintaining this project?

All authors/maintainers are listed in the kudos.txt file located at the project root directory.

How can I contribute?

If you have any comments or find bugs, please contact langzeitarchiv@slub-dresden.de, create an issue or send us a pull request.

Details on how to contribute to this project can be found at the CONTRIBUTING.md file located at the project root directory.

If you have commited to the project yourself, you can leave a note in the kudos.txt file located at the project root directory. Be assured of our eternal gratitude.

Is there a Code of Conduct?

Yes there is. You can find it in the CODE-OF-CONDUCT.md file located at the project root directory. It's kept very brief by design.