hashistack

Table of Contents

Consul Configuration Documentation 🌍
🔧 Basics
🌍 General Settings
🌐 TLS Configuration
📂 Directory Paths
🔗 Join Configuration
🖥️ Server Configuration
🖥️ UI Configuration
🛡️ ACL Configuration
🛠️ Extra Configuration
🔗 Service Mesh Configuration
🌐 DNS Configuration
📊 Telemetry Configuration
📝 Logging Configuration

Consul Configuration Documentation 🌍

This section outlines the customizable variables for deploying and managing a Consul cluster using the hashistack-ansible collection. Each configuration map should adhere to the structure documented in the official Consul documentation as these maps will be merged into the final Consul configuration file.

🔧 Basics

To deploy a Consul cluster, start by enabling it:

enable_consul: "yes"

Specify the version of Consul to install:

consul_version: "1.18.1"

You can define a fully qualified domain name (FQDN) for Consul:

consul_fqdn: consul.ednz.lab

🌍 General Settings

Configure general settings for your Consul deployment:

consul_domain: consul
consul_datacenter: dc1
consul_primary_datacenter: "{{ consul_datacenter }}"
consul_gossip_encryption_key: "{{ _credentials.consul.gossip_encryption_key }}"
consul_enable_script_checks: false

These settings allow you to define the Consul domain, datacenter, and encryption key for secure communication.

🌐 TLS Configuration

Enable TLS for internal Consul communication:

consul_enable_tls: "{{ enable_tls_internal }}"

Define TLS configuration parameters:

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

📂 Directory Paths

Set the directory paths used by Consul for configuration, data, certificates, and logs:

consul_config_dir: "{{ hashistack_remote_config_dir }}/consul.d"
consul_data_dir: "/opt/consul"
consul_certs_dir: "{{ consul_config_dir }}/tls"
consul_logs_dir: "{{ hashistack_remote_log_dir }}/consul"

🔗 Join Configuration

Configure how Consul servers and agents join the cluster:

consul_join_configuration:
  retry_join: |
    {{
      groups['consul_servers'] |
      map('extract', hostvars, ['consul_address_configuration', 'bind_addr']) |
      list |
      to_json |
      from_json
    }}    
  retry_interval: 30s
  retry_max: 0

This setup helps ensure that Consul agents and servers can reliably join the cluster.

🖥️ Server Configuration

Enable and configure Consul servers:

consul_enable_server: "{{ 'consul_servers' in group_names }}"
consul_bootstrap_expect: "{{ (groups['consul_servers'] | length) }}"

🖥️ UI Configuration

Enable the Consul UI:

consul_ui_configuration:
  enabled: "{{ consul_enable_server }}"

🛡️ ACL Configuration

ACLs are enabled by default in Consul. Customize ACL settings and token management:

consul_acl_configuration:
  enabled: true
  default_policy: "deny"
  enable_token_persistence: true
  tokens:
    agent: "{{ _credentials.consul.tokens.agent.secret_id }}"

Define default agent policies to manage permissions:

consul_default_agent_policy: |
  node_prefix "" {
    policy = "write"
  }
  service_prefix "" {
    policy = "read"
  }

🛠️ Extra Configuration

Add additional configuration files and environment variables:

consul_extra_files_list: []
consul_extra_configuration: {}
consul_env_variables: {}

Use these settings to include any non-standard configurations or extra environment variables.

🔗 Service Mesh Configuration

Enable and configure the service mesh:

consul_mesh_configuration:
  enabled: true

This setting enables Consul's service mesh capabilities, allowing for secure and dynamic service-to-service communication.

🌐 DNS Configuration

Control DNS behavior within the Consul cluster:

consul_dns_configuration:
  allow_stale: true
  enable_truncate: true
  only_passing: true

These options help optimize DNS responses and ensure that only healthy services are resolved.

📊 Telemetry Configuration

Enable Prometheus metrics and customize telemetry settings:

consul_enable_prometheus_metrics: false
consul_prometheus_retention_time: 60s
consul_telemetry_configuration: {}

Note: The consul_telemetry_configuration map should be structured according to the official Consul documentation, as it will be merged into the final configuration file.

📝 Logging Configuration

Configure logging for Consul:

consul_log_level: info
consul_enable_log_to_file: "{{ enable_log_to_file | bool }}"
consul_log_to_file_configuration:
  log_file: "{{ consul_logs_dir }}/consul.log"
  log_rotate_duration: 24h
  log_rotate_max_files: 30

This configuration manages the verbosity and output of Consul logs.

This documentation provides an overview of the key variables and settings for configuring a Consul cluster using hashistack-ansible. Remember to follow the official Consul documentation for any specific configurations within each map to ensure proper integration into the final configuration file. Adjust the settings as needed to fit your environment and deployment requirements.