Consul

This Ansible role helps you install Consul, by setting up the filesystem and configuring either a server or client. It includes useful operational features.

You can also create a development cluster with 3 servers using Vagrant and VirtualBox. Check README_VAGRANT.md and the Vagrantfile for more info.

Role Philosophy

"Everyone wants to build, but no one wants to maintain."
― Kurt Vonnegut

This role mainly focuses on setting up the Consul server cluster for the first time and doesn't provide extensive ongoing maintenance features. Many users appreciate that the Vagrant setup makes it easy to get a local Consul server running.

Installation and Migration

Originally created by Brian Shumate as brianshumate.consul, it was transferred to the ansible-collections group for community maintenance. To install the role, create a file called requirements.yml in the roles/ subdirectory of your project with the following content:

---
- src: https://github.com/ansible-collections/ansible-consul.git
  name: ansible-consul
  scm: git
  version: master

You can find tagged releases in this repository to specify a particular version.

If you are using Ansible Tower, it will automatically install the role. For command-line users, run:

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

Requirements

You need either FreeBSD, Debian, Red Hat Enterprise Linux, or Windows Server 2012 R2 to use this role. It also works well with the following software versions:

• Consul: 1.8.7
• Ansible: 2.8.2
• Alma Linux: 8, 9
• Alpine Linux: 3.8
• CentOS: 7, 8
• Debian: 9
• FreeBSD: 11
• Mac OS X: 10.15 (Catalina)
• RHEL: 7, 8
• Rocky Linux: 8
• OracleLinux: 7, 8
• Ubuntu: 16.04
• Windows: Server 2012 R2

For default "local" installation mode, the role downloads one Consul archive, unzips it, and installs it across the selected hosts. It requires that the unzip command is available on the Ansible control host. The role won’t work without unzip in the PATH.

Caveats

This role has limited support for using the limit option (ansible -l) to restrict hosts, which may lead to issues with required host variables. Using it can result in errors like:

Undefined is not JSON serializable.

Role Variables

The role uses variables defined in three places:

• Host inventory file (check examples/vagrant_hosts for an example)
• vars/*.yml (for OS-specific variables)
• defaults/main.yml (for other settings)

NOTE: The role needs the inventory group for the consul servers to be set as consul_group_name. If not defined correctly, the role will not work as expected.

Key Role Variables:

• consul_version: Version to install, set to latest for the newest version (default: 1.8.7).
• consul_user: OS user for Consul (default: consul on Linux, LocalSystem on Windows).
• consul_data_path: Path for Consul data storage (default: /opt/consul on Linux).
• consul_ports: Customize specific port settings for Consul (default values provided in documentation).
• consul_acl_enable: Activate ACLs (default: false).

Example Playbook

You can quickly install using the included site.yml playbook:

ansible-playbook -i hosts site.yml

You can pass additional variables using --extra-vars:

ansible-playbook -i hosts site.yml --extra-vars "consul_datacenter=maui"

For clustering, site.yml does the following:

1. Runs the Consul role (installs Consul and sets up the cluster).
2. Reconfigures the bootstrap node to run without the bootstrap-expect setting.
3. Restarts the bootstrap node.

Additional Features

The role supports various features like ACLs, DNS forwarding (with Dnsmasq), and TLS encryption. Features can be activated with specific variables detailed in the documentation.

License

BSD License

Author Information

Created by Brian Shumate

Contributors

Thanks to all contributors listed in CONTRIBUTORS.md for their contributions. Your contributions are welcome if you agree to the terms in CONTRIBUTING.md.