Extending enough.community

After getting started, you may want to add some host/service in enough.community infrastructure.

Overview

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.

Scenario definition

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:

  • create instances

    molecule create -s dummy
    
  • log into instances

    molecule login -s dummy --host dummy-host
    molecule login -s dummy --host external-host
    
  • destroy instances

    molecule destroy -s dummy
    

About hostnames

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.

Adding playbooks

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

Adding tests

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

Most services rely on DNS, emails and monitoring. To enable them you have to add the corresponding hosts in your molecule scenario and include their playbook in your scenario playbook.

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.

Documentation

You are kindly invited to document your scenario in docs. Most playbooks are documented in a dedicated file included from docs/index.rst.

Tweaking hosts

You can set ssh port, choose OS image and set default user by tweaking hosts-base.yml.