hcp-ansible/roles/consul/README.md

**Consul**
=========

This role configures [HashiCorp consul](https://www.hashicorp.com/products/consul) on **Debian-based** distributions.

**Requirements**
------------

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

**Role Variables**
--------------

### Service Configuration

```yaml
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](https://releases.hashicorp.com/consul/) (just strip out the leading `consul_`)

```yaml
consul_start_service: true
```
Indicates whether the Consul service should start after installation. Defaults to `true`.

```yaml
consul_config_dir: "/etc/consul.d"
```
Path to the directory where Consul's configuration files are stored.

```yaml
consul_data_dir: "/opt/consul"
```
Specifies the directory where Consul will store its data.

```yaml
consul_certs_dir: "{{ consul_config_dir }}/tls"
```
Path to the directory where Consul's TLS certificates should be stored when using internal TLS.

```yaml
consul_logs_dir: "/var/log/consul"
```
Directory path where Consul's log files will be stored if logging to file is enabled.

```yaml
consul_extra_files: false
```
If `true`, allows additional files to be copied over to the target host by the role.

```yaml
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:

```yaml
- 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:

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

```yaml
consul_env_variables: {}
```
Environment variables to be set for the Consul service, defined as key-value pairs.

### Extra Configuration

```yaml
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

```yaml
consul_domain: consul
```
The domain for Consul, typically set to `consul`.

```yaml
consul_datacenter: dc1
```
Specifies the datacenter for the Consul instance.

```yaml
consul_primary_datacenter: "{{ consul_datacenter }}"
```
Sets the primary datacenter, defaulting to the value of `consul_datacenter`.

```yaml
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.

```yaml
consul_enable_script_checks: false
```
Indicates whether script checks are enabled for Consul.

### Leave Configuration

```yaml
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.

```yaml
consul_rejoin_after_leave: true
```
Specifies whether the Consul agent should automatically rejoin the cluster after leaving.

### Join Configuration

```yaml
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

```yaml
consul_enable_server: true
```
Enables the Consul server functionality.

```yaml
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

```yaml
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

```yaml
consul_bind_addr: "0.0.0.0"
```
Specifies the address that Consul will bind to for incoming connections.

```yaml
consul_advertise_addr: "{{ ansible_default_ipv4.address }}"
```
Defines the address that Consul will advertise to other members of the cluster.

```yaml
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

```yaml
consul_acl_configuration:
  enabled: false
  default_policy: "deny"
  enable_token_persistence: true
  # tokens:
  #   agent: ""
```
This block matches the "acl" stanza from the [Consul documentation](https://developer.hashicorp.com/consul/docs/agent/config/config-files#acl).

### Service Mesh Configuration

```yaml
consul_mesh_configuration:
  enabled: false
```
This block matches the "connect" stanza from the [Consul documentation](https://developer.hashicorp.com/consul/docs/agent/config/config-files#connect).

### DNS Configuration

```yaml
consul_dns_configuration:
  allow_stale: true
  enable_truncate: true
  only_passing: true
```
This block matches the "dns_config" stanza from the [Consul documentation](https://developer.hashicorp.com/consul/docs/agent/config/config-files#dns_config).

### Internal TLS Configuration

```yaml
consul_enable_tls: false
```
Enables TLS for Consul listeners if set to `true`.

```yaml
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](https://developer.hashicorp.com/consul/docs/agent/config/config-files#tls-configuration-reference).


```yaml
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

```yaml
consul_enable_prometheus_metrics: false
```
This variable enable prometheus metrics for the Consul server or agent.

```yaml
consul_prometheus_retention_time: 60s
```
This variable matches the `telemetry.prometheus_retention_time` from the [Consul documentation](https://developer.hashicorp.com/consul/docs/agent/config/config-files#telemetry-parameters). 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.

```yaml
consul_telemetry_configuration: {}
```
This block matches the "telemetry" stanza from the [Consul documentation](https://developer.hashicorp.com/consul/docs/agent/config/config-files#telemetry-parameters).

### Consul Logging

```yaml
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](https://developer.hashicorp.com/consul/docs/agent/config/cli-flags#_log_level) for more details.

```yaml
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.

```yaml
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](https://developer.hashicorp.com/consul/docs/agent/config/config-files#log-parameters) 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
----------------

```yaml
# 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.