Add your own roles and playbooks

Adding your own roles and playbooks

You might feel the need to add your own roles to OpenConext-deploy. This could be the case for instance when you want to use an alternative loadbalancer, or a role to provision users etc. The current OpenConext-deploy provides a way to do so in a standardized way.

All relevant OpenConext roles are in a single playbook, which then includes environment specific files that allows you to include your own roles and your own playbooks. The playbook includes a way to download your own roles and load your own playbook in a standardized manner. A wrapper script around the ansible-playbook command is provided as well in order to eliminate the long ansible-playbook commands and automatically download and find your own downloaded roles.

Every set of servers running a full instance of OpenConext is called an environment. You might have just one installation (like the VM) or you might have a full blown DTAP (development, test, acceptance and production) environment. Every environment contains the following directory structure:

/group_vars/somegroupname.yml
/host_vars/host.name.yml
/inventory

When you use ./prep-env command from the installation page, it will automatically create this directory structure for you in /environments-external. With that you have a standard environment, containing everything to deploy OpenConext.

If you want to add your own roles and playbooks, you can do so in the following manner:

The ansible-galaxy command is used to download your roles. You can use any repository format supported by ansible-galaxy to host your own roles. See the Ansible Galaxy documentation for supported repositories.

You can than create a file "requirements.yml" and place that in your environment repository. Make sure that your environment repository is in de the directory external-environments. So when you have for instance an environment called "test3", you would have the structure environments-external/test3/. In the requirements.yml file we set the repository name to "roles-external/YOURROLENAME". This will make sure that the role is downloaded to roles-external/YOURROLENAME. It allows later on to let your plays find the role automatically. So, if you would like to include Geerling's Apache role for instance, you would create a requirements.yml file like this:

- src: https://github.com/geerlingguy/ansible-role-apache.git
  name: roles-external/apache
  scm: git

Now you can add this role to your own playbook. A dummy file is present in the vm and template environment. If you want to add a play with your apache role, and tag it with the tag apache, you would put this in the file playbook.yml in your environments directory:

---
- hosts: all
  roles:
    - { role: apache, tags: ['apache'] }

If you then use the provision wrapper command to deploy it will automatically include the playbook and find your role. Suppose your environment is called acc (so you have the aforementioned directory structure placed in environments-external/acc), your secrets are in secrets.yml and your remote username is deployuser, you would then call the provision script with the following parameters:

provision acc secrets.yml deployuser --tags apache

The requirements.yml file can be used to get roles from multiple sources. You can also use a repository with multiple roles in in. Make sure that repository has a directory called meta with an empty file main.yml in.