SDG National Reporting Initiative Ansible Scripts

This repository contains the Ansible scripts for the SDG National Reporting Intiative. We use Ansible to help automate the provisioning and restoration of technical infrastructure. These scripts also serve as a form of documentation on how to set up various infrastructure assets for the project.

Requirements

You'll need to run the playbooks on a system with Ansible installed (tested with version 2.4.3.0). If you want to test locally against a Vagrant box, you will need to have Vagrant installed on your system (see the Testing with Vagrant section below).

How to Use

ansible-playbook <playbook_filepath> -i <inventory_filepath>

This project makes heavy use of tags to control which tasks are run. Of particular note should be the always and never tags:

• Tasks tagged always will always run unless one of the task's other tags is explicitly skipped.
• Tasks tagged never will only run if one of the task's other is explicitly stated.

A typical usage is to set up a new API machine to production while skipping SSL certificate registration with Let's Encrypt:

ansible-playbook ansible/deploy_sdg_api -i ansible/inventories/production --tags production --skip-tags ssl-cert

Variables

Many of the tasks require certain variables to be filled out. To see which values you need to provide, check defaults/main.yml for each role; some of these variables will have default values, and others will be empty, requiring you to provide a value. You can fill out the default values, but it is better to copy these values into a dedicated variable file. There are many ways to provide the variables for running tasks, but the best way is to use group variables.

In the group_vars directory, simply create an extensionless file named after the inventory you wish to provide variables for. For example, if I wanted to provide variables when running against the production inventory, I would create the file group_vars/production and define my variables in there.

You can provide variables that are available for every inventory by defining them in group_vars/all.

Testing with Vagrant

You can test most of the playbook roles using Vagrant. There is a Vagrantfile included in the root of the repo which you will need to configure with the playbook you want to test. The Ansible provisioning configured in the Vagrantfile is set to ignore any tasks labeled with the production tag, in case there are tasks that you can't test locally and need to ignore (you can learn more in the Ansible tags documentation).

Directory Layout

To understand the directory layout structure, please familiarize yourself with the Content Organization section of the Best Practices guide from the offical Ansible documentation.

Configuration

Check the defaults directory under each role to get a list of the configurable variables for that role (some of the variables don't have default values and will need to be set before you can run the playbooks).

You can override the default values either by creating a vars/main.yml file under the corresponding role or by setting them in the proper group file under the group_vars directory.

For connection configurations, see the variables in the inventory files under inventories.

Playbooks

There are currently two playbooks:

jenkins_playbook.yml

This playbook installs Jenkins and restores any configurations and plugins.

sdg_api_playbook.yml

This playbook sets up and deploys the API service backing the SDG National Reporting Initiative Website.