Ansible Consul Role

consul is an ansible role which:

installs consul
configures consul
optionally installs and configures consul ui
optionally installs dnsmasq
optionally install consulate
optionally install consul-cli
configures consul service(s)

Installation

Using ansible-galaxy:

$ ansible-galaxy install savagegus.ansible-consul

Using arm (Ansible Role Manager):

$ arm install savagegus.consul

Using git:

$ git clone https://github.com/jivesoftware/ansible-consul.git

Variables

Here is a list of all the default variables for this role, which are also available in defaults/main.yml.

---
consul_version: 0.6.0
consul_archive: "consul_{{ consul_version }}_linux_amd64.zip"
consul_download: "https://releases.hashicorp.com/consul/{{ consul_version }}/{{ consul_archive }}"
consul_download_username: ""
consul_download_password: ""
consul_download_folder: /tmp

consul_is_ui: false
consul_ui_archive: "consul_{{ consul_version }}_web_ui.zip"
consul_ui_download: "https://releases.hashicorp.com/consul/{{ consul_version }}/{{ consul_ui_archive }}"
consul_ui_dir: "{{ consul_home }}/dist"
consul_ui_server_name: "{{ ansible_fqdn }}"
consul_ui_require_auth: false
consul_ui_nginx_template: "consul-nginx.conf.j2"
consul_ui_auth_user_file: /etc/htpasswd/consul
consul_ui_server_port: 80
consul_install_nginx: true
consul_install_nginx_config: true
consul_enable_nginx_config: true
consul_service_state: restarted

consul_install_consul_cli: false
consul_cli_archive: "master.zip"
consul_cli_download: "https://github.com/CiscoCloud/consul-cli/archive/{{ consul_cli_archive }}"

consul_home: /opt/consul
consul_config_dir: /etc/consul.d
consul_config_file: /etc/consul.conf
consul_log_file: /var/log/consul
consul_data_dir: "{{ consul_home }}/data"

consul_dns_allow_stale: false
consul_dns_max_stale: 5s
consul_dns_node_ttl: 0s
consul_dns_service_ttl: 0s
consul_dns_enable_truncate: false
consul_dns_only_passing: false
consul_recursors: []

consul_upstart_template: "consul.conf.j2"
consul_systemd_template: "consul.systemd.j2"
consul_initd_template: "consul.initd.sh.j2"
consul_dnsmasq_upstream_template: "resolv_dnsmasq.conf.j2"
consul_kv_template: "consulkv.j2"
consul_add_path_template: "consul.sh.j2"
consul_config_template: "consul.json.j2"

consul_binary: consul

consul_user: consul
consul_group: consul

consul_use_systemd: false
consul_use_upstart: true
consul_use_initd: false

consul_is_server: false

consul_domain: consul.

consul_servers: ['127.0.0.1']
consul_log_level: "INFO"
consul_syslog: false
consul_rejoin_after_leave: true
consul_leave_on_terminate: false

consul_join_at_start: false
consul_retry_join: false
consul_retry_interval: 30s
consul_retry_max: 0

consul_servers_wan: []
consul_join_wan: false
consul_retry_join_wan: false
consul_retry_interval_wan: 30s
consul_retry_max_wan: 0
consul_advertise_address_wan: false
consul_advertise_address: "127.0.0.1" - default: `undefined`. If this variable is not defined it is not set in the config
consul_bind_address: "0.0.0.0"
consul_dynamic_bind: false
consul_client_address: "127.0.0.1"

consul_client_address_bind: false
consul_datacenter: "default"
consul_disable_remote_exec: true

consul_port_dns: 8600
consul_port_http: 8500
consul_port_https: -1
consul_port_rpc: 8400
consul_port_serf_lan: 8301
consul_port_serf_wan: 8302
consul_port_server: 8300
consul_install_dnsmasq: false
consul_install_consulate: false
consul_dnsmasq:
  listen_interface:
    - lo
    - docker0
    - eth0
  no_dhcp_interface:
    - lo
    - docker0
    - eth0
  upstream_servers:
    - 8.8.8.8
    - 8.8.4.4
consul_node_name: "{{ inventory_hostname }}"
consul_verify_server_hostname: false
consul_cors_support: false
consul_disable_update_check: false

An instance might be defined through:

# enable ui
consul_is_ui: true
# start as a server
consul_is_server: true
# name datacenter
consul_datacenter: test
# bootstrap
consul_bootstrap: true
# name the node
consul_node_name: vagrant
# bind to ip
consul_bind_address: "{{ ansible_default_ipv4['address'] }}"
# encrypt using string from consul keygen
consul_encrypt: "X4SYOinf2pTAcAHRhpj7dA=="

Enable TLS encryption

See https://www.consul.io/docs/agent/encryption.html for details.

These files will be created on your Consul host:

consul_cert_file: "{{ consul_home }}/cert/consul.crt"
consul_key_file: "{{ consul_home }}/cert/consul.key"
consul_ca_file: "{{ consul_home }}/cert/ca.crt"

When you provide these vars. You should use Ansible Vault to encrypt these vars or perhaps pass them on the command line.

consul_tls_cert: |
  CERT CONTENTS HERE

consul_tls_key: |
  KEY CONTENTS HERE

consul_tls_ca_cert: |
  CERT CONTENTS HERE

Atlas Variables

consul_atlas_infrastructure: "your_infrastructure_name"
consul_atlas_token: "your_consul_token"

# if you want to use Atlas autodiscovery for clustering
consul_atlas_join: true

Telemetry Variables

Consul has excellent telemetry support. To enable it, use any of the following variables:

# if you want Consul to send metrics to a statsd instance
consul_statsd_address: "127.0.0.1:8125"
# if you want Consul to send metrics to a statsite instance
consul_statsite_address: "127.0.0.1:8125"
# this sets the prefix consul uses for all metrics
consul_statsite_prefix: "consul"
# if you don't want to prepend runtime telemetry with the machine's hostname (consul 0.6.4 or later)
consul_telemetry_disable_hostname: true

DNS Variables

Consul provides the ability to use it as a DNS resolver for service and node lookups. To enable dns_config with the below default values, set the consul_dns_config variable to true

consul_dns_allow_stale: false
consul_dns_max_stale: 5s
consul_dns_node_ttl: 0s
consul_dns_service_ttl: 0s
consul_dns_enable_truncate: false
consul_udp_answer_limit: 3
consul_dns_only_passing: false
consul_recursors:
  - 8.8.8.8
  - 8.8.4.4

Cross-origin Resource Sharing

Consul allows adding headers to the HTTP API responses, to enable CORS set the consul_cors_support variable to true

consul_cors_support: true

Shutdown behavior

Consul may be configured to perform (or not) cluster leave when it recieves TERM/INT signals.

When service is stopped:

systemd sends INT
init (init.d script) sends TERM
upstart sends TERM

There are two variables that define if the node will attempt cluster leave when it recieves those signals:

consul_leave_on_terminate defines if leave is performed when TERM is recieved. default: false
consul_skip_leave_on_interrupt defines if leave is not performed when INT is recieved. default: undefined. If this variable is not defined default consul behavior (which depends on version and server/agent role) will be used.

Handlers

These are the handlers that are defined in handlers/main.yml.

restart consul
restart dnsmasq
reload consul config
reload systemd

Example playbook that configures a Consul server on Ubuntu

---

- hosts: all
  vars:
    consul_is_server: "true"
    consul_datacenter: "test"
    consul_bootstrap: "true"
    consul_bind_address: "{{ ansible_default_ipv4['address'] }}"
  roles:
    - ansible-consul

Example playbook that configures a Consul server on Ubuntu with runit

- hosts: all
  vars:
    consul_reload_config_handler: runit reload consul
    consul_restart_handler: runit restart consul
    consul_log_file: /dev/null
  roles:
    - ansible-consul
    - role: runit
      runit_pre_start_command: "setcap CAP_NET_BIND_SERVICE=+eip /opt/consul/bin/consul"
      runit_service_command: "/opt/consul/bin/consul"
      runit_service_params: "agent -config-dir /etc/consul.d -config-file=/etc/consul.conf"
      runit_service_env:
        GOMAXPROCS: "{{ ansible_processor_vcpus }}"

Logs will be handled by runit and consul_log_file set to /dev/null just to prevent /var/log/consul file creation as it conflicts with runit logs directory.

Example playbooks that configures a Consul server on CentOS 7

---

- hosts: all
  vars:
    consul_is_server: "true"
    consul_datacenter: "test"
    consul_bootstrap: "true"
    consul_bind_address: "{{ ansible_default_ipv4['address'] }}"
    consul_use_upstart: false
    consul_use_systemd: true
    nginx_user: "nginx"
  roles:
    - ansible-consul

Example to register consul services

consul_services:
  - service:
      name: "redis localhost"
      tags:
        - "redis"
      address: "127.0.0.1"
      port: 6379
      checks:
        - name: "Redis health check"
          tcp: "localhost:6379"
          interval: "10s"
          timeout: "1s"

Testing

$ git clone https://github.com/jivesoftware/ansible-consul.git
$ cd ansible-consul
$ ansible-galaxy install --role-file=requirements.yml --roles-path=roles --force
$ vagrant up

or use the TestKitchen tests

$ bundle
$ rm -rf roles
$ bundle exec kitchen test

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests and examples for any new or changed functionality.

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

lhoss/ansible-consul