hcp-ansible/roles/consul/README.md

Consul

This role configures HashiCorp consul on Debian-based distributions.

Requirements

This role requires that the unzip package is installed on the target host.

Role Variables

Service Configuration

consul_version: latest

Specifies the version of Consul to install. Default is latest, which installs the latest stable version. It is recommended to pin the consul version to install, as setting latest will cause the role to query the github API, andyou might run into rate limiting issues. A pinned version should look like X.Y.Z, in accordance with the consul's release repository (just strip out the leading consul_)

consul_start_service: true

Indicates whether the Consul service should start after installation. Defaults to true.

consul_config_dir: "/etc/consul.d"

Path to the directory where Consul's configuration files are stored.

consul_data_dir: "/opt/consul"

Specifies the directory where Consul will store its data.

consul_certs_dir: "{{ consul_config_dir }}/tls"

Path to the directory where Consul's TLS certificates should be stored when using internal TLS.

consul_logs_dir: "/var/log/consul"

Directory path where Consul's log files will be stored if logging to file is enabled.

consul_extra_files: false

If true, allows additional files to be copied over to the target host by the role.

consul_extra_files_list: []

A list of additional files to manage with the role if consul_extra_files is set to true. This is a list of objects like:

- src: /path/on/deploy/machine
  dest: /path/to/copy/over

Sources can be any type of file, directory or jinja2 templates. Destination should match the type of the source. Jinja2 templates inside of a directory that would be copied over are also templated, and their .j2 extensions will be stripped out.

Example:

consul_extra_files_list:
  - src: /local/path/to/tls/files
    dest: "{{ consul_certs_dir }}"
  - src: /another/single/file.j2
    dest: /var/lib/file

consul_env_variables: {}

Environment variables to be set for the Consul service, defined as key-value pairs.

Extra Configuration

consul_extra_configuration: {}

Dictionary for any additional Consul configuration options not covered by other variables. This should be used only for options not provided by existing variables.

General Configuration

consul_domain: consul

The domain for Consul, typically set to consul.

consul_datacenter: dc1

Specifies the datacenter for the Consul instance.

consul_primary_datacenter: "{{ consul_datacenter }}"

Sets the primary datacenter, defaulting to the value of consul_datacenter.

consul_gossip_encryption_key: "{{ 'mysupersecretgossipencryptionkey' | b64encode }}"

Sets the gossip encryption key for secure communication between Consul agents. This key must be a 32-byte base64-encoded string.

consul_enable_script_checks: false

Indicates whether script checks are enabled for Consul.

Leave Configuration

consul_leave_on_terminate: true

Specifies whether the consul agent should leave the cluster when it is terminated (e.g., SIGTERM). Defaults to false, indicating the agent will not leave the cluster upon termination.

consul_rejoin_after_leave: true

Specifies whether the Consul agent should automatically rejoin the cluster after leaving.

Join Configuration

consul_join_configuration:
  retry_join:
    - "{{ ansible_default_ipv4.address }}"
  retry_interval: 30s
  retry_max: 0

Specifies the addresses that the Consul agent should attempt to join upon starting, the interval between attempts to join the cluster, and the maximum number of join attempts before giving up. A value of 0 for retry_max indicates unlimited retries.

Server Configuration

consul_enable_server: true

Enables the Consul server functionality.

consul_bootstrap_expect: 1

Specifies the number of servers that are expected to bootstrap the cluster. In this example, 1 indicates that this server will be the only one in the cluster during the initial bootstrapping phase.

UI Configuration

consul_ui_configuration:
  enabled: "{{ consul_enable_server }}"

Enables the Consul UI based on whether the Consul server is enabled. If consul_enable_server is set to true, the UI will be accessible.

Address Configuration

consul_bind_addr: "0.0.0.0"

Specifies the address that Consul will bind to for incoming connections.

consul_advertise_addr: "{{ ansible_default_ipv4.address }}"

Defines the address that Consul will advertise to other members of the cluster.

consul_address_configuration:
  client_addr: "{{ consul_bind_addr }}"
  bind_addr: "{{ consul_advertise_addr }}"
  advertise_addr: "{{ consul_advertise_addr }}"

This block contains the address configuration for Consul. It will be merged into the global Consul configuration to facilitate setup and avoid repeating entries.

ACL Configuration

consul_acl_configuration:
  enabled: false
  default_policy: "deny"
  enable_token_persistence: true
  # tokens:
  #   agent: ""

This block matches the "acl" stanza from the Consul documentation.

Service Mesh Configuration

consul_mesh_configuration:
  enabled: false

This block matches the "connect" stanza from the Consul documentation.

DNS Configuration

consul_dns_configuration:
  allow_stale: true
  enable_truncate: true
  only_passing: true

This block matches the "dns_config" stanza from the Consul documentation.

Internal TLS Configuration

consul_enable_tls: false

Enables TLS for Consul listeners if set to true.

consul_tls_configuration:
  defaults:
    ca_file: "/etc/ssl/certs/ca-certificates.crt"
    cert_file: "{{ consul_certs_dir }}/cert.pem"
    key_file: "{{ consul_certs_dir }}/key.pem"
    verify_incoming: false
    verify_outgoing: true
  internal_rpc:
    verify_server_hostname: true

The consul_tls_configuration value matches the "tls" block from the Consul documentation.

consul_certificates_extra_files_dir: []

The consul_certificates_extra_files_dir values allows users to copy certificates by appending to consul_extra_files_list. consul_extra_files must be set to true if using this feature.

Telemetry Configuration

consul_enable_prometheus_metrics: false

This variable enable prometheus metrics for the Consul server or agent.

consul_prometheus_retention_time: 60s

This variable matches the telemetry.prometheus_retention_time from the Consul documentation. It defaults to 60s and derives from the default 0s because in case consul_enable_prometheus_metrics is true, this variable need to be greater than 0s in order to enable prometheus metrics endpoint.

consul_telemetry_configuration: {}

This block matches the "telemetry" stanza from the Consul documentation.

Consul Logging

consul_log_level: info

Sets the logging level for Consul. Accepted values are trace, debug, info, warn, and error. See Consul documentation on log levels for more details.

consul_enable_log_to_file: false

Enables logging to a file if set to true. When enabled, the settings in consul_log_to_file_configuration will define the log file path, rotation frequency, and retention of logs.

consul_log_to_file_configuration:
  log_file: "{{ consul_logs_dir }}/consul.log"
  log_rotate_duration: 24h
  log_rotate_max_files: 30

Specifies configuration for file-based logging:

• log_file: Defines the path to the Consul log file (e.g., consul_logs_dir/consul.log). See Consul log file configuration for details.
• log_rotate_duration: Sets the duration before log rotation occurs (e.g., 24h for daily rotation).
• log_rotate_max_files: Maximum number of rotated log files to retain.

With consul_enable_log_to_file set to true, these settings provide a default configuration for logging to a file, allowing Consul to manage log files and rotation automatically.

Dependencies

None.

Example Playbook

# calling the role inside a playbook with either the default or group_vars/host_vars
- hosts: servers
  roles:
    - ednz_cloud.hashistack.consul

License

MIT / BSD

Author Information

This role was created by Bertrand Lanson in 2023.