Consul

This Ansible role performs a basic Consul installation, including filesystem structure, example configuration, and Consul UI installation.

It can also bootstrap a minimal development or evaluation cluster of 3 server agents running in a Vagrant and VirtualBox based environment. See README_VAGRANT.md and the associated Vagrantfile for more details about the developer mode setup.

Requirements

This role requires a Debian or RHEL based Linux distribution. It might work with other software versions, but does work with the following specific software and versions:

Ansible: 2.1.1.0
Consul: 0.7.0
Debian: 8

Role Variables

The role specifies variables in defaults/main.yml and vars/*.yml.

Name	Default Value	Description
`consul_version`	`0.7.0`	Consul version to install
`consul_zip_url`	`https://releases.hashicorp.com/consul/{{ consul_version }}/consul_{{ consul_version }}_linux_amd64.zip`	Consul download URL
`consul_zip_sha256`	SHA256 SUM	Consul download SHA256 summary
`consul_bin_path`	`/usr/local/bin`	Consul binary installation path
`consul_config_path`	`/etc/consul.d`	Consul configuration file path
`consul_data_path`	`/var/consul`	Consul data path
`consul_log_path`	`/var/log/consul`	Consul log path
`consul_user`	`consul`	Consul OS user
`consul_group`	`bin`	Consul OS group
`consul_datacenter`	boone	Consul datacenter label
`consul_domain`	`local`	Consul domain name
`consul_log_level`	`INFO`	Consul logging level
`consul_syslog_enable`	true	Consul logs to syslog
`consul_ui_url`	`https://dl.bintray.com/mitchellh/consul/0.5.2_web_ui.zip`	Consul UI download URL
`consul_ui_pkg`	`0.5.2_web_ui.zip`	Conul UI package file name
`consul_ui_sha256`	SHA256 SUM	Consul UI download SHA256 summary
`consul_iface`	`eth1`	Consul network interface
`consul_bind_address`	dynamic from hosts inventory	The interface address to bind to
`consul_dnsmasq`	`false`	Whether to install and configure DNS API forwarding on port 53 using dnsmasq

OS Distribution Variables

The Consul binary works on most Linux platforms and is not distribution specific. Some distributions require installation of specific OS packages with different nomenclature, so this role has support for major Linux distributions.

Name	Default Value	Description
`consul_centos_pkg`	`{{ consul_version }}_linux_amd64.zip`	Consul package filename
`consul_centos_url`	`{{ consul_zip_url }}`	Consul package download URL
`consul_centos_sha256`	SHA256 SUM	Consul download SHA256 summary
`consul_centos_os_packages`	list	List of OS packages to install
`consul_debian_pkg`	`{{ consul_version }}_linux_amd64.zip`	Consul package filename
`consul_debian_url`	`{{ consul_zip_url }}`	Consul package download URL
`consul_debian_sha256`	SHA256 SUM	Consul download SHA256 summary
`consul_debian_os_packages`	list	List of OS packages to install
`consul_redhat_pkg`	`{{ consul_version }}_linux_amd64.zip`	Consul package filename
`consul_redhat_url`	`{{ consul_zip_url }}`	Consul package download URL
`consul_redhat_sha256`	SHA256 SUM	Consul download SHA256 summary
`consul_redhat_os_packages`	list	List of OS packages to install
`consul_ubuntu_pkg`	`{{ consul_version }}_linux_amd64.zip`	Consul package filename
`consul_ubuntu_url`	`{{ consul_zip_url }}`	Consul package download URL
`consul_ubuntu_sha256`	SHA256 SUM	Consul download SHA256 summary
`consul_ubuntu_os_packages`	list	List of OS packages to install

Dependencies

None

Example Playbook

After you have reviewed and altered any necessary variables, and created a host inventory file, basic Consul installation is possible using the included site.yml playbook example:

ansible-playbook -i hosts site.yml

You can also pass variables in using the --extra-vars option to the ansible-playbook command:

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

Be aware that for clustering, the included site.yml does the following:

Executes consul role (installs Consul and bootstraps cluster)
Reconfigures bootstrap node to run without bootstrap-expect setting
Restarts bootstrap node

NEW

The role now includes support for DNS forwarding with dnsmasq.

Enable like this:

ansible-playbook -i hosts site.yml --extra-vars "consul_dnsmasq=true"

Then, you can query any of the agents via DNS directly via port 53, for example:

dig @consul1.local consul3.node.consul

; <<>> DiG 9.8.3-P1 <<>> @consul1.local consul3.node.consul
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 29196
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;consul3.node.consul.   IN  A

;; ANSWER SECTION:
consul3.node.consul.  0 IN  A 10.1.42.230

;; Query time: 42 msec
;; SERVER: 10.1.42.210#53(10.1.42.210)
;; WHEN: Sun Aug  7 18:06:32 2016
;;

Vagrant and VirtualBox

See examples/README_VAGRANT.md for details on quick Vagrant deployments under VirtualBox for testing, etc.

License

BSD

Author Information

Brian Shumate

Contributors

Special thanks to the folks listed in CONTRIBUTORS.md for their contributions to this project.

cruisemaniac/ansible-consul