automium.consul

Ansible Role for Deploying Consul

Consul

[![Build Status](https://api.travis-ci.org/automium/ansible-consul.svg?branch=master)](https://travis-ci.org/entercloudsuite/ansible-consul) [![Galaxy](https://img.shields.io/badge/galaxy-automium.consul-blue.svg?style=flat-square)](https://galaxy.ansible.com/automium/consul)

Features

Configure Consul with YAML

You can configure the Consul service using YAML, which is converted to JSON. Here’s an example configuration:

consul_master_token: myToken
consul_server: true
consul_configs:
  main:
    acl_datacenter: pantheon
    acl_master_token: "{{ consul_master_token | to_uuid }}"
    bootstrap: true
    bind_addr: 0.0.0.0
    client_addr: 0.0.0.0
    datacenter: pantheon
    data_dir: "{{ consul_data_dir }}"
    log_level: INFO
    node_name: master
    server: "{{ consul_server }}"
    ui: true

This role does not have predefined settings, allowing you to write your Consul configuration in a simple YAML format. This can be very useful as you can use other Ansible features to create custom data. You can express anything using Ansible's templating, like fetching data from inventory, etc.

The example above uses simple key/value pairs, but you can also define more complex structures like dictionaries and lists.
If you need help converting your JSON configuration to YAML, you can use this handy converter.

Requirements

This role has been tested on Ubuntu 16.04 but is expected to work on any Linux distribution. It requires:

systemd
unzip

Default Role Variables

---
consul_packer_provision: false
consul_group_name: consul
consul_group_gid: 3000
consul_user_name: consul
consul_user_uid: 3000
consul_user_home: /opt/consul
consul_config_dir: "{{ consul_user_home }}/conf.d"
consul_data_dir: "{{ consul_user_home }}/data"
consul_version: 1.6.3
consul_cap_net_bind_service: "{{ consul_configs.main.server | default('false') }}"
consul_server: false
consul_uri: "https://releases.hashicorp.com/consul/{{ consul_version }}/consul_{{ consul_version }}_linux_amd64.zip"
consul_config_src: main.json.j2
consul_config_validate: "{{ consul_user_home }}/bin/consul validate -config-format=json %s"
consul_extra_args: []
consul_service_file:
  src: consul.service.j2
  dest: /etc/systemd/system/consul.service
consul_service_status: started
enable_on_boot: yes

# Use this variable to skip the configuration step
# no_configure

# Use this variable to skip the installation step
# no_install

consul_config:
  datacenter: dc-1
  data_dir: "{{ consul_data_dir }}"
  log_level: INFO
  node_name: node-1
  server: "{{ consul_server }}"

Example Playbook

Basic Role Configuration

- hosts: consul_servers
  vars:
    consul_master_token: myToken
    consul_server: true
    consul_config:
      acl_datacenter: pantheon
      acl_master_token: "{{ consul_master_token | to_uuid }}"
      bootstrap: true
      bind_addr: 0.0.0.0
      client_addr: 0.0.0.0
      datacenter: pantheon
      data_dir: "{{ consul_data_dir }}"
      log_level: INFO
      node_name: master
      server: "{{ consul_server }}"
      ui: true
  roles:
      - entercloudsuite.consul

Don’t Configure, Just Install

---
- name: run the main role
  hosts: all
  roles:
    - role: entercloudsuite.consul
      configure: false
      install: true
      consul_service_status: "stopped"
      consul_master_token: myToken
      consul_server: true
      consul_configs:
        main:
          acl_datacenter: pantheon
          acl_master_token: "{{ consul_master_token | to_uuid }}"
          bootstrap: true
          bind_addr: 0.0.0.0
          client_addr: 0.0.0.0
          datacenter: pantheon
          data_dir: "{{ consul_data_dir }}"
          log_level: INFO
          node_name: master
          server: "{{ consul_server }}"
          ui: true

Don’t Install, Just Configure

---
- name: run the main role
  hosts: all
  roles:
    - role: entercloudsuite.consul
      configure: true
      install: false
      consul_service_status: "started"
      consul_master_token: myToken
      consul_server: true
      consul_configs:
        main:
          acl_datacenter: pantheon
          acl_master_token: "{{ consul_master_token | to_uuid }}"
          bootstrap: true
          bind_addr: 0.0.0.0
          client_addr: 0.0.0.0
          datacenter: pantheon
          data_dir: "{{ consul_data_dir }}"
          log_level: INFO
          node_name: master
          server: "{{ consul_server }}"
          ui: true

Consul Agent Configurations

Here’s an example of configuring an agent to join the server group.

    - role: ansible-consul
      configure: true
      install: true
      consul_service_status: "started"
      consul_version: 1.6.3
      consul_configs:
        main:
          bind_addr: "{{ ansible_default_ipv4['address'] }}"
          client_addr: 0.0.0.0
          node_name: "{{ ansible_hostname }}"
          data_dir: "{{ consul_data_dir }}"
          datacenter: "pantheon"
          enable_syslog: true
          server: false
          ui: true
          enable_script_checks: true
          rejoin_after_leave: true
          retry_join: "{{ groups['server'] | map('extract', hostvars, ['ansible_default_ipv4', 'address']) | list }}"

Consul Server Example

To set up a Consul server to create a new cluster.

    - role: ansible-consul
      configure: true
      install: true
      consul_service_status: "started"
      consul_version: 1.6.3
      consul_configs:
        main:
          bind_addr: "{{ ansible_default_ipv4['address'] }}"
          client_addr: 0.0.0.0
          node_name: "{{ ansible_hostname }}"
          data_dir: "{{ consul_data_dir }}"
          datacenter: "pantheon"
          enable_syslog: true
          server: true
          ui: true
          enable_script_checks: true
          rejoin_after_leave: true
          retry_join: "{{ groups['server'] | map('extract', hostvars, ['ansible_default_ipv4', 'address']) | list }}"
          ports:
            dns: 53
          dns_config:
            udp_answer_limit: 64
          bootstrap_expect: "{{ groups['server'] | length | int }}"
          recursors:
            - 1.1.1.1
            - 8.8.8.8

Testing

Tests can be performed using Molecule.

Install Molecule or run docker-compose run --rm molecule to start a local Docker container.
Run molecule create to start the target Docker container.
Use molecule login to access the running container.
Edit the role files as needed.
Include any additional required roles in the molecule/default/requirements.yml file.
Modify the molecule/default/playbook.yml as necessary.
Define tests under the molecule/default/tests folder.
Run molecule converge to execute the Ansible Playbook and molecule verify for testing.
Use molecule destroy to remove the Docker container.

To perform all steps with one command, run molecule test. For VM deployments, use the playbook_deploy.yml file with the command: ansible-playbook ansible-docker/molecule/default/playbook_deploy.yml -i VM_IP_OR_FQDN, -u ubuntu --private-key private.pem.