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)
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
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=="
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
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
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
# if you want Consul to send metrics to a datadog
consul_telemetry_dogstatsd_address: "127.0.0.1:8125"
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
Consul allows adding headers to the HTTP API responses, to enable CORS set the consul_cors_support
variable to true
consul_cors_support: true
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.
These are the handlers that are defined in handlers/main.yml
.
restart consul
restart dnsmasq
reload consul config
reload systemd
---
- 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.
---
- 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
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"
$ 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
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
Copyright (c) Matthew Finlayson under the Apache license.