After getting started, you may want to add some host/service in enough.community infrastructure.
The enough.community infrastructure is developed and deployed using ansible. The main playbook is enough-community-playbook.yml.
The development, tuning and corrections of the playbook is done in a separate environment with automated testing. Molecule is the test infrastructure.
Each playbook (for instance molecule/weblate/weblate-playbook.yml) is related to a molecule scenario, i.e. a set of hosts and a test playbook to get a minimal infrastructure setup allowing to validate the service playbook. As an example, the weblate scenario found in molecule/weblate/ defines the following hosts:
- a postfix master
- a bind server
- an icinga server
- the weblate host
With these, the weblate scenario is able to test the weblate deployment, its monitoring, its ability to send emails, etc.
Some generally useful playbooks are grouped in the misc scenario.
The presence of a bind-host in most scenarios allows to spoof all records from enough.community domain during the tests (and could spoof any other domain). This disallow external requests like e.g. ACME challenge for TLS Certificates. To overcome this limitation, the domain of the scenario is defined in a one-time testing subdomain when a bind-host is used by the scenario and the variable with_fake_LE has been defined (meaning that we should use the “fake Let’s Encrypt unlimited testing infrastructure”).
The preprod scenario aggregates all enough.community playbooks and should be used to very they fit together as expected.
Adding a host¶
Ansible hosts are defined in inventory/01-hosts.yml. This file is autogenerated by molecule scenarios and is not meant to be manually modified.
Adding a scenario¶
Let’s start with a dummy scenario.
Next, edit molecule/dummy/molecule.yml. You could at least:
edit the scenario’s name
scenario: name: dummy
control the hosts to be created
- name: dummy-host flavor: "s1-2" - name: external-host flavor: "s1-2"
The flavor refers to OVH OpenStack provisionned ressources.
You should then be able to:
molecule create -s dummy
log into instances
molecule login -s dummy --host dummy-host molecule login -s dummy --host external-host
molecule destroy -s dummy
For the most part we do not use groups and hostnames matche the service they provide. We use service-host as a naming convention. Each given host (e.g. postfix-host) matches the corresponding service (e.g. “infrastructure’s mail relay”).
- if you need to choose a hostname, derive it from the service,
- by using a name for which there already is a scenario (postfix-host for instance), you will deploy the corresponding service.
The molecule default playbook is molecule/dummy/playbook.yml. It should include all playbooks used for the scenario, i.e.:
- others scenarios playbooks, like molecule/icinga/icinga-playbook.yml or molecule/postfix/postfix-playbook.yml
- the playbook specific to this scenario, here molecule/icinga/dummy-playbook.yml, which is intended to be included in enough-community-playbook.yml. This playbook may include other playbooks.
- tests specific playbooks, starting with test, e.g. molecule/icinga/test-dummy-playbook.yml.
Once the playbooks are added, you should be able to check their syntax and run them with:
molecule syntax -s dummy molecule converge -s dummy
The purpose of the tests is mainly to detect that Ansible has deployed a functional service. See them as functionnal and non-regression testing to maintaining our Ansible base.
We use testinfra for this purpose. The easiest way to get started with it is to look at some existing tests. For simple testing see molecule/bind/tests/test_external_bind.py. For a request based test, see e.g. molecule/weblate/tests/test_icingaweb.py.
Since the tests run with virtual machines provisionned exclusively for the test, you can do whatever you want (i.e. even some destructive action).
The test can be launched with
molecule verify -s dummy
Testing is not monitoring. You are kindly invited to setup monitoring for your services and to test via testinfra that monitoring has been setup as you wish.
You can launch a destroy, create, converge, verify, destroy cycle with
molecule test -s dummy
Interaction with others scenarios¶
You will also be interested by:
- molecule/misc/sexy-debian-playbook.yml for getting usefull tools,
- molecule/certs/certs-playbook.yml for getting useful TLS certificates,
- molecule/authorized_keys/authorized-keys-playbook.yml for installing ssh keys,
- molecule/misc/commit_etc-playbook.yml for committing changes to /etc/ at the end of your playbook.
You are kindly invited to document your scenario in docs. Most playbooks are documented in a dedicated file included from docs/index.rst.
You can set ssh port, choose OS image and set default user by tweaking hosts-base.yml.