From 91c4720740efbceed6a3aaba89dc0be726ee6413 Mon Sep 17 00:00:00 2001 From: Bertrand Lanson Date: Sun, 27 Oct 2024 19:55:56 +0100 Subject: [PATCH] docs(roles): improve documentation for vault,nomad,consul and cni roles --- roles/cni/README.md | 70 +++++ roles/consul/.docsible | 13 - roles/consul/README.md | 480 +++++++++++++++++------------- roles/nomad/.docsible | 13 - roles/nomad/README.md | 538 +++++++++++++++++++++++----------- roles/vault/.docsible | 13 - roles/vault/README.md | 361 ++++++++++++++--------- roles/vault/defaults/main.yml | 6 +- 8 files changed, 931 insertions(+), 563 deletions(-) create mode 100644 roles/cni/README.md delete mode 100644 roles/consul/.docsible delete mode 100644 roles/nomad/.docsible delete mode 100644 roles/vault/.docsible diff --git a/roles/cni/README.md b/roles/cni/README.md new file mode 100644 index 0000000..3726133 --- /dev/null +++ b/roles/cni/README.md @@ -0,0 +1,70 @@ +**CNI** +========= + +This role configures [Container Networking Interface (CNI)](https://github.com/containernetworking/plugins) plugins on the target host, enabling networking capabilities for containerized applications. + +**Requirements** +------------ + +This role does not have any specific software requirements. However, it assumes that the target host has the necessary dependencies installed to manage containers. + +**Role Variables** +-------------- + +### Plugin Configuration + +```yaml +cni_plugins_version: "latest" +``` +Specifies the version of the CNI plugins to install. The default is `latest`, which installs the latest stable version. It is recommended to pin the CNI version to prevent unexpected changes. Pinned versions should be in the format `X.Y.Z`, based on the GitHub tags from the [CNI GitHub repository](https://github.com/containernetworking/plugins). + +```yaml +cni_plugins_install_path: /opt/cni/bin +``` +Defines the directory where the CNI plugins will be installed. This path is where the binaries will reside for container runtime access. + +```yaml +cni_plugins_install_consul_cni: false +``` +Indicates whether to install the Consul CNI plugin in addition to the standard CNI plugins. If set to `true`, the role will download and install the Consul CNI plugin from the HashiCorp releases repository, matching the version of the other CNI plugins. + +### User and Group Configuration + +```yaml +cni_user: nomad +``` +Specifies the user under which the CNI plugins will be executed. Default is `nomad`, which is commonly used for applications managed by HashiCorp Nomad. + +```yaml +cni_group: nomad +``` +Defines the group under which the CNI plugins will be executed. Default is `nomad`, ensuring that permissions are correctly set for the user and group running the plugins. + +**Note on Permissions:** + +The specified user and group are used to set the appropriate permissions for the installed plugins, ensuring that only the designated user has the required access to execute the binaries. + +**Dependencies** +------------ + +None. + +**Example Playbook** +---------------- + +```yaml +# Example playbook for installing CNI plugins +- hosts: servers + roles: + - ednz_cloud.hashistack.cni +``` + +**License** +------- + +MIT / BSD + +**Author Information** +------------------ + +This role was created by Bertrand Lanson in 2024. diff --git a/roles/consul/.docsible b/roles/consul/.docsible deleted file mode 100644 index 7713e0f..0000000 --- a/roles/consul/.docsible +++ /dev/null @@ -1,13 +0,0 @@ -aap_hub: null -automation_kind: null -category: null -critical: null -description: null -dt_dev: null -dt_prod: null -dt_update: 26/08/2024 -requester: null -subCategory: null -time_saving: null -users: null -version: null diff --git a/roles/consul/README.md b/roles/consul/README.md index a644b6b..df4b846 100644 --- a/roles/consul/README.md +++ b/roles/consul/README.md @@ -1,227 +1,297 @@ - +**Consul** +========= -# 📃 Role overview +This role configures [HashiCorp consul](https://www.hashicorp.com/products/consul) on **Debian-based** distributions. -## consul +**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). - -Description: Install and configure hashicorp consul for debian-based distros. +```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. -| Field | Value | -|--------------------- |-----------------| -| Readme update | 26/08/2024 | +### 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. -### Defaults +```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. -**These are static variables with lower priority** +```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. -#### File: defaults/main.yml +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. -| Var | Type | Value |Required | Title | -|--------------|--------------|-------------|-------------|-------------| -| [consul_version](defaults/main.yml#L4) | str | `latest` | n/a | n/a | -| [consul_start_service](defaults/main.yml#L5) | bool | `True` | n/a | n/a | -| [consul_config_dir](defaults/main.yml#L6) | str | `/etc/consul.d` | n/a | n/a | -| [consul_data_dir](defaults/main.yml#L7) | str | `/opt/consul` | n/a | n/a | -| [consul_certs_dir](defaults/main.yml#L8) | str | `{{ consul_config_dir }}/tls` | n/a | n/a | -| [consul_logs_dir](defaults/main.yml#L9) | str | `/var/log/consul` | n/a | n/a | -| [consul_envoy_install](defaults/main.yml#L11) | bool | `False` | n/a | n/a | -| [consul_envoy_version](defaults/main.yml#L12) | str | `latest` | n/a | n/a | -| [consul_extra_files](defaults/main.yml#L14) | bool | `False` | n/a | n/a | -| [consul_extra_files_list](defaults/main.yml#L15) | list | `[]` | n/a | n/a | -| [consul_env_variables](defaults/main.yml#L17) | dict | `{}` | n/a | n/a | -| [consul_extra_configuration](defaults/main.yml#L28) | dict | `{}` | n/a | n/a | -| [consul_domain](defaults/main.yml#L34) | str | `consul` | n/a | n/a | -| [consul_datacenter](defaults/main.yml#L35) | str | `dc1` | n/a | n/a | -| [consul_primary_datacenter](defaults/main.yml#L36) | str | `{{ consul_datacenter }}` | n/a | n/a | -| [consul_gossip_encryption_key](defaults/main.yml#L37) | str | `{{ 'mysupersecretgossipencryptionkey'\|b64encode }}` | n/a | n/a | -| [consul_enable_script_checks](defaults/main.yml#L38) | bool | `False` | n/a | n/a | -| [consul_leave_on_terminate](defaults/main.yml#L44) | bool | `True` | n/a | n/a | -| [consul_rejoin_after_leave](defaults/main.yml#L45) | bool | `True` | n/a | n/a | -| [consul_join_configuration](defaults/main.yml#L51) | dict | `{'retry_join': ['{{ ansible_default_ipv4.address }}'], 'retry_interval': '30s', 'retry_max': 0}` | n/a | n/a | -| [consul_enable_server](defaults/main.yml#L61) | bool | `True` | n/a | n/a | -| [consul_bootstrap_expect](defaults/main.yml#L62) | int | `1` | n/a | n/a | -| [consul_ui_configuration](defaults/main.yml#L68) | dict | `{'enabled': '{{ consul_enable_server }}'}` | n/a | n/a | -| [consul_bind_addr](defaults/main.yml#L75) | str | `0.0.0.0` | n/a | n/a | -| [consul_advertise_addr](defaults/main.yml#L76) | str | `{{ ansible_default_ipv4.address }}` | n/a | n/a | -| [consul_address_configuration](defaults/main.yml#L77) | dict | `{'client_addr': '{{ consul_bind_addr }}', 'bind_addr': '{{ consul_advertise_addr }}', 'advertise_addr': '{{ consul_advertise_addr }}'}` | n/a | n/a | -| [consul_acl_configuration](defaults/main.yml#L86) | dict | `{'enabled': False, 'default_policy': 'deny', 'enable_token_persistence': True}` | n/a | n/a | -| [consul_mesh_configuration](defaults/main.yml#L97) | dict | `{'enabled': False}` | n/a | n/a | -| [consul_dns_configuration](defaults/main.yml#L104) | dict | `{'allow_stale': True, 'enable_truncate': True, 'only_passing': True}` | n/a | n/a | -| [consul_enable_tls](defaults/main.yml#L113) | bool | `False` | n/a | n/a | -| [consul_tls_configuration](defaults/main.yml#L114) | dict | `{'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}}` | n/a | n/a | -| [consul_certificates_extra_files_dir](defaults/main.yml#L124) | list | `[]` | n/a | n/a | -| [consul_enable_prometheus_metrics](defaults/main.yml#L133) | bool | `False` | n/a | n/a | -| [consul_prometheus_retention_time](defaults/main.yml#L134) | str | `60s` | n/a | n/a | -| [consul_telemetry_configuration](defaults/main.yml#L135) | dict | `{}` | n/a | n/a | -| [consul_log_level](defaults/main.yml#L141) | str | `info` | n/a | n/a | -| [consul_enable_log_to_file](defaults/main.yml#L142) | bool | `False` | n/a | n/a | -| [consul_log_to_file_configuration](defaults/main.yml#L143) | dict | `{'log_file': '{{ consul_logs_dir }}/consul.log', 'log_rotate_duration': '24h', 'log_rotate_max_files': 30}` | n/a | n/a | +Dependencies +------------ +None. -### Vars +Example Playbook +---------------- -**These are variables with higher priority** -#### File: vars/main.yml +```yaml +# calling the role inside a playbook with either the default or group_vars/host_vars +- hosts: servers + roles: + - ednz_cloud.hashistack.consul +``` -| Var | Type | Value |Required | Title | -|--------------|--------------|-------------|-------------|-------------| -| [consul_user](vars/main.yml#L3) | str | `consul` | n/a | n/a | -| [consul_group](vars/main.yml#L4) | str | `consul` | n/a | n/a | -| [consul_binary_path](vars/main.yml#L5) | str | `/usr/local/bin/consul` | n/a | n/a | -| [consul_envoy_binary_path](vars/main.yml#L6) | str | `/usr/local/bin/envoy` | n/a | n/a | -| [consul_deb_architecture_map](vars/main.yml#L7) | dict | `{'x86_64': 'amd64', 'aarch64': 'arm64', 'armv7l': 'arm', 'armv6l': 'arm'}` | n/a | n/a | -| [consul_envoy_architecture_map](vars/main.yml#L12) | dict | `{'x86_64': 'x86_64', 'aarch64': 'aarch64'}` | n/a | n/a | -| [consul_architecture](vars/main.yml#L15) | str | `{{ consul_deb_architecture_map[ansible_architecture] \| default(ansible_architecture) }}` | n/a | n/a | -| [consul_envoy_architecture](vars/main.yml#L16) | str | `{{ consul_envoy_architecture_map[ansible_architecture] \| default(ansible_architecture) }}` | n/a | n/a | -| [consul_service_name](vars/main.yml#L17) | str | `consul` | n/a | n/a | -| [consul_github_api](vars/main.yml#L18) | str | `https://api.github.com/repos` | n/a | n/a | -| [consul_envoy_github_project](vars/main.yml#L19) | str | `envoyproxy/envoy` | n/a | n/a | -| [consul_github_project](vars/main.yml#L20) | str | `hashicorp/consul` | n/a | n/a | -| [consul_github_url](vars/main.yml#L21) | str | `https://github.com` | n/a | n/a | -| [consul_repository_url](vars/main.yml#L22) | str | `https://releases.hashicorp.com/consul` | n/a | n/a | -| [consul_configuration](vars/main.yml#L24) | dict | `{'domain': '{{ consul_domain }}', 'datacenter': '{{ consul_datacenter }}', 'primary_datacenter': '{{ consul_primary_datacenter }}', 'data_dir': '{{ consul_data_dir }}', 'encrypt': '{{ consul_gossip_encryption_key }}', 'server': '{{ consul_enable_server }}', 'ui_config': '{{ consul_ui_configuration }}', 'connect': '{{ consul_mesh_configuration }}', 'leave_on_terminate': '{{ consul_leave_on_terminate }}', 'rejoin_after_leave': '{{ consul_rejoin_after_leave }}', 'enable_script_checks': '{{ consul_enable_script_checks }}', 'enable_syslog': True, 'acl': '{{ consul_acl_configuration }}', 'dns_config': '{{ consul_dns_configuration }}', 'log_level': '{{ consul_log_level }}', 'ports': {'dns': 8600, 'server': 8300, 'serf_lan': 8301, 'serf_wan': 8302, 'sidecar_min_port': 21000, 'sidecar_max_port': 21255, 'expose_min_port': 21500, 'expose_max_port': 21755}}` | n/a | n/a | -| [consul_configuration_string](vars/main.yml#L50) | str | `` | n/a | n/a | -| [consul_server_configuration_string](vars/main.yml#L57) | str | `` | n/a | n/a | +License +------- +MIT / BSD -### Tasks +Author Information +------------------ - -#### File: tasks/recursive_copy_extra_dirs.yml - -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Consul \| Ensure destination directory exists | ansible.builtin.file | False | -| Consul \| Create extra directory sources | ansible.builtin.file | True | -| Consul \| Template extra directory sources | ansible.builtin.template | True | - -#### File: tasks/merge_variables.yml - -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Consul \| Merge stringified configuration | vars | False | -| Consul \| Merge server specific stringified configuration | vars | True | -| Consul \| Merge join configuration | vars | False | -| Consul \| Merge addresses configuration | vars | False | -| Consul \| Merge TLS configuration | block | True | -| Consul \| Merge TLS configuration | vars | False | -| Consul \| Add certificates directory to extra_files_dir | ansible.builtin.set_fact | False | -| Consul \| Merge extra configuration settings | vars | False | -| Consul \| Merge log to file configuration | vars | True | -| Consul \| Merge telemetry configuration | block | False | -| Consul \| Merge prometheus metrics configuration | vars | True | -| Consul \| Merge telemtry configuration | vars | False | - -#### File: tasks/main.yml - -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Consul \| Set reload-check & restart-check variable | ansible.builtin.set_fact | False | -| Consul \| Import merge_variables.yml | ansible.builtin.include_tasks | False | -| Consul \| Import prerequisites.yml | ansible.builtin.include_tasks | False | -| Consul \| Import install_envoy.yml | ansible.builtin.include_tasks | True | -| Consul \| Import install.yml | ansible.builtin.include_tasks | False | -| Consul \| Import configure.yml | ansible.builtin.include_tasks | False | -| Consul \| Populate service facts | ansible.builtin.service_facts | False | -| Consul \| Set restart-check variable | ansible.builtin.set_fact | True | -| Consul \| Enable service: {{ consul_service_name }} | ansible.builtin.service | False | -| Consul \| Reload systemd daemon | ansible.builtin.systemd | True | -| Consul \| Start service: {{ consul_service_name }} | ansible.builtin.service | True | - -#### File: tasks/install.yml - -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Consul \| Get latest release of consul | block | True | -| Consul \| Get latest consul release from github api | ansible.builtin.uri | False | -| Consul \| Set wanted consul version to latest tag | ansible.builtin.set_fact | False | -| Consul \| Set wanted consul version to {{ consul_version }} | ansible.builtin.set_fact | True | -| Consul \| Get current consul version | block | False | -| Consul \| Stat consul version file | ansible.builtin.stat | False | -| Consul \| Get current consul version | ansible.builtin.slurp | True | -| Consul \| Download and install consul binary | block | True | -| Consul \| Set consul package name to download | ansible.builtin.set_fact | False | -| Consul \| Download checksum file for consul archive | ansible.builtin.get_url | False | -| Consul \| Extract correct checksum from checksum file | ansible.builtin.command | False | -| Consul \| Parse the expected checksum | ansible.builtin.set_fact | False | -| Consul \| Download consul binary archive | ansible.builtin.get_url | False | -| Consul \| Create temporary directory for archive decompression | ansible.builtin.file | False | -| Consul \| Unpack consul archive | ansible.builtin.unarchive | False | -| Consul \| Copy consul binary to {{ consul_binary_path }} | ansible.builtin.copy | False | -| Consul \| Update consul version file | ansible.builtin.copy | False | -| Consul \| Set restart-check variable | ansible.builtin.set_fact | False | -| Consul \| Cleanup temporary directory | ansible.builtin.file | False | -| Consul \| Copy systemd service file for consul | ansible.builtin.template | False | -| Consul \| Set reload-check & restart-check variable | ansible.builtin.set_fact | True | - -#### File: tasks/install_envoy.yml - -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Consul \| Get release for envoy:{{ consul_envoy_version }} | vars | False | -| Consul \| Check if envoy is already installed | ansible.builtin.stat | False | -| Consul \| Check current envoy version | ansible.builtin.command | True | -| Consul \| Set facts for wanted envoy release | ansible.builtin.set_fact | True | -| Consul \| Set facts for current envoy release | ansible.builtin.set_fact | True | -| Consul \| Create envoy directory | ansible.builtin.file | False | -| Consul \| Install envoy | block | True | -| Consul \| Remove old compose binary if different | ansible.builtin.file | False | -| Consul \| Download and install envoy version:{{ consul_envoy_version }} | ansible.builtin.get_url | False | -| Consul \| Update version file | ansible.builtin.copy | False | - -#### File: tasks/prerequisites.yml - -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Consul \| Create group {{ consul_group }} | ansible.builtin.group | False | -| Consul \| Create user {{ consul_user }} | ansible.builtin.user | False | -| Consul \| Create directory {{ consul_config_dir }} | ansible.builtin.file | False | -| Consul \| Create directory {{ consul_data_dir}} | ansible.builtin.file | False | -| Consul \| Create directory {{ consul_certs_dir }} | ansible.builtin.file | False | -| Consul \| Create directory {{ consul_logs_dir }} | ansible.builtin.file | True | - -#### File: tasks/configure.yml - -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Consul \| Create consul.env | ansible.builtin.template | False | -| Consul \| Copy consul.json template | ansible.builtin.template | False | -| Consul \| Set restart-check variable | ansible.builtin.set_fact | True | -| Consul \| Copy extra configuration files | block | True | -| Consul \| Get extra file types | ansible.builtin.stat | False | -| Consul \| Set list for file sources | vars | True | -| Consul \| Set list for directory sources | vars | True | -| Consul \| Template extra file sources | ansible.builtin.template | True | -| Consul \| Template extra directory sources | ansible.builtin.include_tasks | True | - - - - - - - -## Author Information -Bertrand Lanson - -#### License - -license (BSD, MIT) - -#### Minimum Ansible Version - -2.10 - -#### Platforms - -- **Ubuntu**: ['focal', 'jammy', 'noble'] -- **Debian**: ['bullseye', 'bookworm'] - - +This role was created by Bertrand Lanson in 2023. diff --git a/roles/nomad/.docsible b/roles/nomad/.docsible deleted file mode 100644 index 7713e0f..0000000 --- a/roles/nomad/.docsible +++ /dev/null @@ -1,13 +0,0 @@ -aap_hub: null -automation_kind: null -category: null -critical: null -description: null -dt_dev: null -dt_prod: null -dt_update: 26/08/2024 -requester: null -subCategory: null -time_saving: null -users: null -version: null diff --git a/roles/nomad/README.md b/roles/nomad/README.md index f05bde8..d32a824 100644 --- a/roles/nomad/README.md +++ b/roles/nomad/README.md @@ -1,221 +1,415 @@ - +**Nomad** +========= -# 📃 Role overview +This role configures [HashiCorp nomad](https://www.hashicorp.com/products/nomad) on **Debian-based** distributions. -## nomad +**Requirements** +------------ +This role requires that the `unzip` package is installed on the target host. +**Role Variables** +-------------- -Description: Install and configure hashicorp nomad for debian-based distros. +### Service Configuration +```yaml +nomad_version: latest +``` +Specifies the version of Nomad to install. Default is `latest`, which installs the latest stable version. It is recommended to pin the nomad 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 nomad's [release repository](https://releases.hashicorp.com/nomad/) (just strip out the leading `nomad_`) -| Field | Value | -|--------------------- |-----------------| -| Readme update | 26/08/2024 | +```yaml +nomad_start_service: true +``` +Indicates whether the Nomad service should start after installation. Defaults to `true`. +```yaml +nomad_config_dir: "/etc/nomad.d" +``` +Path to the directory where Nomad's configuration files are stored. +```yaml +nomad_data_dir: "/opt/nomad" +``` +Specifies the directory where Nomad will store its data. +```yaml +nomad_certs_dir: "{{ nomad_config_dir }}/tls" +``` +Path to the directory where Nomad's TLS certificates should be stored when using internal TLS. +```yaml +nomad_logs_dir: "/var/log/nomad" +``` +Directory path where Nomad's log files will be stored if logging to file is enabled. +```yaml +nomad_extra_files: false +``` +If `true`, allows additional files to be copied over to the target host by the role. -### Defaults +```yaml +nomad_extra_files_list: [] +``` +A list of additional files to manage with the role if `nomad_extra_files` is set to `true`. This is a list of objects like: -**These are static variables with lower priority** +```yaml +- src: /path/on/deploy/machine + dest: /path/to/copy/over +``` -#### File: defaults/main.yml +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. -| Var | Type | Value |Required | Title | -|--------------|--------------|-------------|-------------|-------------| -| [nomad_version](defaults/main.yml#L4) | str | `latest` | n/a | n/a | -| [nomad_start_service](defaults/main.yml#L5) | bool | `True` | n/a | n/a | -| [nomad_config_dir](defaults/main.yml#L6) | str | `/etc/nomad.d` | n/a | n/a | -| [nomad_data_dir](defaults/main.yml#L7) | str | `/opt/nomad` | n/a | n/a | -| [nomad_certs_dir](defaults/main.yml#L8) | str | `{{ nomad_config_dir }}/tls` | n/a | n/a | -| [nomad_logs_dir](defaults/main.yml#L9) | str | `/var/log/nomad` | n/a | n/a | -| [nomad_extra_files](defaults/main.yml#L11) | bool | `False` | n/a | n/a | -| [nomad_extra_files_list](defaults/main.yml#L12) | list | `[]` | n/a | n/a | -| [nomad_env_variables](defaults/main.yml#L14) | dict | `{}` | n/a | n/a | -| [nomad_extra_configuration](defaults/main.yml#L25) | dict | `{}` | n/a | n/a | -| [nomad_region](defaults/main.yml#L31) | str | `global` | n/a | n/a | -| [nomad_datacenter](defaults/main.yml#L32) | str | `dc1` | n/a | n/a | -| [nomad_bind_addr](defaults/main.yml#L38) | str | `0.0.0.0` | n/a | n/a | -| [nomad_advertise_addr](defaults/main.yml#L39) | str | `{{ ansible_default_ipv4.address }}` | n/a | n/a | -| [nomad_address_configuration](defaults/main.yml#L40) | dict | `{'bind_addr': '{{ nomad_bind_addr }}', 'addresses': {'http': '{{ nomad_advertise_addr }}', 'rpc': '{{ nomad_advertise_addr }}', 'serf': '{{ nomad_advertise_addr }}'}, 'advertise': {'http': '{{ nomad_advertise_addr }}', 'rpc': '{{ nomad_advertise_addr }}', 'serf': '{{ nomad_advertise_addr }}'}, 'ports': {'http': 4646, 'rpc': 4647, 'serf': 4648}}` | n/a | n/a | -| [nomad_autopilot_configuration](defaults/main.yml#L59) | dict | `{}` | n/a | n/a | -| [nomad_leave_on_interrupt](defaults/main.yml#L65) | bool | `False` | n/a | n/a | -| [nomad_leave_on_terminate](defaults/main.yml#L66) | bool | `False` | n/a | n/a | -| [nomad_enable_server](defaults/main.yml#L72) | bool | `True` | n/a | n/a | -| [nomad_server_bootstrap_expect](defaults/main.yml#L73) | int | `1` | n/a | n/a | -| [nomad_server_configuration](defaults/main.yml#L74) | dict | `{'enabled': '{{ nomad_enable_server }}', 'data_dir': '{{ nomad_data_dir }}/server', 'encrypt': "{{ 'mysupersecretgossipencryptionkey'\|b64encode }}", 'server_join': {'retry_join': ['{{ ansible_default_ipv4.address }}']}}` | n/a | n/a | -| [nomad_enable_client](defaults/main.yml#L86) | bool | `False` | n/a | n/a | -| [nomad_client_configuration](defaults/main.yml#L87) | dict | `{'enabled': '{{ nomad_enable_client }}', 'state_dir': '{{ nomad_data_dir }}/client', 'cni_path': '/opt/cni/bin', 'bridge_network_name': 'nomad', 'bridge_network_subnet': '172.26.64.0/20'}` | n/a | n/a | -| [nomad_ui_configuration](defaults/main.yml#L98) | dict | `{'enabled': '{{ nomad_enable_server }}'}` | n/a | n/a | -| [nomad_driver_enable_docker](defaults/main.yml#L105) | bool | `True` | n/a | n/a | -| [nomad_driver_enable_podman](defaults/main.yml#L106) | bool | `False` | n/a | n/a | -| [nomad_driver_enable_raw_exec](defaults/main.yml#L107) | bool | `False` | n/a | n/a | -| [nomad_driver_enable_java](defaults/main.yml#L108) | bool | `False` | n/a | n/a | -| [nomad_driver_enable_qemu](defaults/main.yml#L109) | bool | `False` | n/a | n/a | -| [nomad_driver_configuration](defaults/main.yml#L111) | dict | `{'raw_exec': {'enabled': False}}` | n/a | n/a | -| [nomad_driver_extra_configuration](defaults/main.yml#L115) | dict | `{}` | n/a | n/a | -| [nomad_log_level](defaults/main.yml#L121) | str | `info` | n/a | n/a | -| [nomad_enable_log_to_file](defaults/main.yml#L122) | bool | `False` | n/a | n/a | -| [nomad_log_to_file_configuration](defaults/main.yml#L123) | dict | `{'log_file': '{{ nomad_logs_dir }}/nomad.log', 'log_rotate_duration': '24h', 'log_rotate_max_files': 30}` | n/a | n/a | -| [nomad_acl_configuration](defaults/main.yml#L132) | dict | `{'enabled': False, 'token_ttl': '30s', 'policy_ttl': '60s', 'role_ttl': '60s'}` | n/a | n/a | -| [nomad_enable_tls](defaults/main.yml#L142) | bool | `False` | n/a | n/a | -| [nomad_tls_configuration](defaults/main.yml#L143) | dict | `{'http': True, 'rpc': True, 'ca_file': '/etc/ssl/certs/ca-certificates.crt', 'cert_file': '{{ nomad_certs_dir }}/cert.pem', 'key_file': '{{ nomad_certs_dir }}/key.pem', 'verify_server_hostname': True}` | n/a | n/a | -| [nomad_certificates_extra_files_dir](defaults/main.yml#L151) | list | `[]` | n/a | n/a | -| [nomad_telemetry_configuration](defaults/main.yml#L160) | dict | `{'collection_interval': '10s', 'disable_hostname': False, 'use_node_name': False, 'publish_allocation_metrics': False, 'publish_node_metrics': False, 'prefix_filter': [], 'disable_dispatched_job_summary_metrics': False, 'prometheus_metrics': False}` | n/a | n/a | -| [nomad_enable_consul_integration](defaults/main.yml#L174) | bool | `False` | n/a | n/a | -| [nomad_consul_integration_configuration](defaults/main.yml#L175) | dict | `{'address': '127.0.0.1:8500', 'auto_advertise': True, 'ssl': False, 'token': '', 'tags': []}` | n/a | n/a | -| [nomad_consul_integration_tls_configuration](defaults/main.yml#L182) | dict | `{'ca_file': '/etc/ssl/certs/ca-certificates.crt'}` | n/a | n/a | -| [nomad_consul_integration_server_configuration](defaults/main.yml#L185) | dict | `{'server_auto_join': True}` | n/a | n/a | -| [nomad_consul_integration_client_configuration](defaults/main.yml#L188) | dict | `{'client_auto_join': True, 'grpc_address': '127.0.0.1:8502'}` | n/a | n/a | -| [nomad_consul_integration_client_tls_configuration](defaults/main.yml#L192) | dict | `{'grpc_ca_file': '/etc/ssl/certs/ca-certificates.crt'}` | n/a | n/a | -| [nomad_enable_vault_integration](defaults/main.yml#L199) | bool | `False` | n/a | n/a | -| [nomad_vault_integration_configuration](defaults/main.yml#L200) | dict | `{}` | n/a | n/a | +Example: +```yaml +nomad_extra_files_list: + - src: /local/path/to/tls/files + dest: "{{ nomad_certs_dir }}" + - src: /another/single/file.j2 + dest: /var/lib/file +``` -### Vars +```yaml +nomad_env_variables: {} +``` +Environment variables to be set for the Nomad service, defined as key-value pairs. -**These are variables with higher priority** -#### File: vars/main.yml +### Extra Configuration -| Var | Type | Value |Required | Title | -|--------------|--------------|-------------|-------------|-------------| -| [nomad_user](vars/main.yml#L3) | str | `nomad` | n/a | n/a | -| [nomad_group](vars/main.yml#L4) | str | `nomad` | n/a | n/a | -| [nomad_binary_path](vars/main.yml#L5) | str | `/usr/local/bin/nomad` | n/a | n/a | -| [nomad_deb_architecture_map](vars/main.yml#L6) | dict | `{'x86_64': 'amd64', 'aarch64': 'arm64', 'armv7l': 'arm', 'armv6l': 'arm'}` | n/a | n/a | -| [nomad_architecture](vars/main.yml#L11) | str | `{{ nomad_deb_architecture_map[ansible_architecture] \| default(ansible_architecture) }}` | n/a | n/a | -| [nomad_service_name](vars/main.yml#L12) | str | `nomad` | n/a | n/a | -| [nomad_github_api](vars/main.yml#L13) | str | `https://api.github.com/repos` | n/a | n/a | -| [nomad_github_project](vars/main.yml#L14) | str | `hashicorp/nomad` | n/a | n/a | -| [nomad_github_url](vars/main.yml#L15) | str | `https://github.com` | n/a | n/a | -| [nomad_repository_url](vars/main.yml#L16) | str | `https://releases.hashicorp.com/nomad` | n/a | n/a | -| [nomad_configuration](vars/main.yml#L18) | dict | `{'datacenter': '{{ nomad_datacenter }}', 'region': '{{ nomad_region }}', 'data_dir': '{{ nomad_data_dir }}', 'leave_on_interrupt': '{{ nomad_leave_on_interrupt }}', 'leave_on_terminate': '{{ nomad_leave_on_terminate }}', 'acl': '{{ nomad_acl_configuration }}', 'server': '{{ nomad_server_configuration }}', 'client': '{{ nomad_client_configuration }}', 'ui': '{{ nomad_ui_configuration }}', 'log_level': '{{ nomad_log_level }}'}` | n/a | n/a | -| [nomad_configuration_string](vars/main.yml#L30) | str | `` | n/a | n/a | +```yaml +nomad_extra_configuration: {} +``` +Dictionary for any additional Nomad configuration options not covered by other variables. This should be used only for options not provided by existing variables. +### General Configuration -### Tasks +```yaml +nomad_region: global +``` +Sets the region of the Nomad cluster. This value is used to define the cluster's region and should match the desired regional configuration. +```yaml +nomad_datacenter: dc1 +``` +Defines the datacenter name for the Nomad agent. This is used for grouping nodes and services within a specific datacenter. -#### File: tasks/recursive_copy_extra_dirs.yml +### Address Configuration -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Nomad \| Ensure destination directory exists | ansible.builtin.file | False | -| Nomad \| Create extra directory sources | ansible.builtin.file | True | -| Nomad \| Template extra directory sources | ansible.builtin.template | True | +```yaml +nomad_bind_addr: "0.0.0.0" +``` +Specifies the address that Nomad will bind to for incoming connections. The default value `0.0.0.0` allows Nomad to listen on all available interfaces. -#### File: tasks/merge_variables.yml +```yaml +nomad_advertise_addr: "{{ ansible_default_ipv4.address }}" +``` +Sets the address that Nomad will advertise to other nodes in the cluster. It typically uses the default IPv4 address of the host. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Nomad \| Merge stringified configuration | vars | False | -| Nomad \| Merge addresses configuration | vars | False | -| Nomad \| Merge consul integration configuration | block | True | -| Nomad \| Merge consul tls configuration | block | True | -| Nomad \| Merge consul default client configuration | vars | False | -| Nomad \| Merge consul configuration for nomad servers | block | True | -| Nomad \| Merge consul default server configuration | vars | False | -| Nomad \| Merge consul configuration for nomad clients | block | True | -| Nomad \| Merge consul default client configuration | vars | False | -| Nomad \| Merge consul tls client configuration | vars | True | -| Nomad \| Merge consul block into main configuration | vars | False | -| Nomad \| Merge TLS configuration | block | True | -| Nomad \| Merge TLS configuration | vars | False | -| Nomad \| Add certificates directory to extra_files_dir | ansible.builtin.set_fact | False | -| Nomad \| Merge plugin configuration | vars | True | -| Nomad \| Merge extra configuration settings | vars | False | -| Nomad \| Merge log to file configuration | vars | True | -| Nomad \| Merge telemetry configuration | vars | False | +```yaml +nomad_address_configuration: + bind_addr: "{{ nomad_bind_addr }}" + addresses: + http: "{{ nomad_advertise_addr }}" + rpc: "{{ nomad_advertise_addr }}" + serf: "{{ nomad_advertise_addr }}" + advertise: + http: "{{ nomad_advertise_addr }}" + rpc: "{{ nomad_advertise_addr }}" + serf: "{{ nomad_advertise_addr }}" + ports: + http: 4646 + rpc: 4647 + serf: 4648 +``` +Defines the address configuration for the Nomad agent. This block matches the structure specified in the [Nomad documentation](https://developer.hashicorp.com/nomad/docs/configuration#advertise), including: -#### File: tasks/main.yml +- **bind_addr**: The address on which Nomad will listen for incoming connections. +- **addresses**: Specifies the addresses used for different communication channels (`http`, `rpc`, and `serf`). +- **advertise**: Lists the addresses that Nomad will advertise to other nodes for the respective channels (`http`, `rpc`, and `serf`). +- **ports**: Defines the ports for the various services, with `http`, `rpc`, and `serf` ports specified. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Nomad \| Set reload-check & restart-check variable | ansible.builtin.set_fact | False | -| Nomad \| Import merge_variables.yml | ansible.builtin.include_tasks | False | -| Nomad \| Import prerequisites.yml | ansible.builtin.include_tasks | False | -| Nomad \| Import install.yml | ansible.builtin.include_tasks | False | -| Nomad \| Import configure.yml | ansible.builtin.include_tasks | False | -| Nomad \| Populate service facts | ansible.builtin.service_facts | False | -| Nomad \| Set restart-check variable | ansible.builtin.set_fact | True | -| Nomad \| Enable service: {{ nomad_service_name }} | ansible.builtin.service | False | -| Nomad \| Reload systemd daemon | ansible.builtin.systemd | True | -| Nomad \| Start service: {{ nomad_service_name }} | ansible.builtin.service | True | +### Autopilot Configuration -#### File: tasks/install.yml +```yaml +nomad_autopilot_configuration: {} +``` +This variable defines the Autopilot configuration for the Nomad agent. It should match the structure of the Autopilot stanza as described in the [Nomad documentation](https://developer.hashicorp.com/nomad/docs/configuration/autopilot). The Autopilot configuration allows you to enable and configure features like automatic leader elections and health checks for the Nomad cluster. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Nomad \| Get latest release of nomad | block | True | -| Nomad \| Get latest nomad release from github api | ansible.builtin.uri | False | -| Nomad \| Set wanted nomad version to latest tag | ansible.builtin.set_fact | False | -| Nomad \| Set wanted nomad version to {{ nomad_version }} | ansible.builtin.set_fact | True | -| Nomad \| Get current nomad version | block | False | -| Nomad \| Stat nomad version file | ansible.builtin.stat | False | -| Nomad \| Get current nomad version | ansible.builtin.slurp | True | -| Nomad \| Download and install nomad binary | block | True | -| Nomad \| Set nomad package name to download | ansible.builtin.set_fact | False | -| Nomad \| Download checksum file for nomad archive | ansible.builtin.get_url | False | -| Nomad \| Extract correct checksum from checksum file | ansible.builtin.command | False | -| Nomad \| Parse the expected checksum | ansible.builtin.set_fact | False | -| Nomad \| Download nomad binary archive | ansible.builtin.get_url | False | -| Nomad \| Create temporary directory for archive decompression | ansible.builtin.file | False | -| Nomad \| Unpack nomad archive | ansible.builtin.unarchive | False | -| Nomad \| Copy nomad binary to {{ nomad_binary_path }} | ansible.builtin.copy | False | -| Nomad \| Update nomad version file | ansible.builtin.copy | False | -| Nomad \| Set restart-check variable | ansible.builtin.set_fact | False | -| Nomad \| Cleanup temporary directory | ansible.builtin.file | False | -| Nomad \| Copy systemd service file for nomad | ansible.builtin.template | False | -| Nomad \| Set reload-check & restart-check variable | ansible.builtin.set_fact | True | +Example configuration: -#### File: tasks/prerequisites.yml +```yaml +nomad_autopilot_configuration: + cleanup_dead_servers: true + last_contact_threshold: "200ms" + max_trailing_logs: 250 + server_stabilization_time: "10s" +``` -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Nomad \| Create group {{ nomad_group }} | ansible.builtin.group | False | -| Nomad \| Create user {{ nomad_user }} | ansible.builtin.user | False | -| Nomad \| Create directory {{ nomad_config_dir }} | ansible.builtin.file | False | -| Nomad \| Create directory {{ nomad_data_dir }} | ansible.builtin.file | False | -| Nomad \| Create directory {{ nomad_certs_dir }} | ansible.builtin.file | False | -| Nomad \| Create directory {{ nomad_logs_dir }} | ansible.builtin.file | True | +### Leave Configuration -#### File: tasks/configure.yml +```yaml +nomad_leave_on_interrupt: false +``` +Determines whether the Nomad agent should gracefully leave the cluster when it receives an interrupt signal (e.g., SIGINT). Defaults to `false`, meaning the agent will not leave the cluster on interrupt. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Nomad \| Create nomad.env | ansible.builtin.template | False | -| Nomad \| Copy nomad.json template | ansible.builtin.template | False | -| Nomad \| Set restart-check variable | ansible.builtin.set_fact | True | -| Nomad \| Copy extra configuration files | block | True | -| Nomad \| Get extra file types | ansible.builtin.stat | False | -| Nomad \| Set list for file sources | vars | True | -| Nomad \| Set list for directory sources | vars | True | -| Nomad \| Template extra file sources | ansible.builtin.template | True | -| Nomad \| Template extra directory sources | ansible.builtin.include_tasks | True | +```yaml +nomad_leave_on_terminate: false +``` +Specifies whether the Nomad 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. +### Server Configuration +```yaml +nomad_enable_server: true +``` +Indicates whether the Nomad agent should operate as a server. Defaults to `true`, enabling the server stanza. +```yaml +nomad_server_bootstrap_expect: 1 +``` +Specifies the number of servers that should join the cluster before bootstrapping. This value is set outside the server configuration block due to Jinja2's inability to convert strings to integers during dict merging. +```yaml +nomad_server_configuration: + enabled: "{{ nomad_enable_server }}" + data_dir: "{{ nomad_data_dir }}/server" + encrypt: "{{ 'mysupersecretgossipencryptionkey' | b64encode }}" + server_join: + retry_join: + - "{{ ansible_default_ipv4.address }}" +``` +Defines the server configuration stanza. Includes: +- `enabled`: References the `nomad_enable_server` variable to enable or disable the server. +- `data_dir`: Path to the directory where server data will be stored. +- `encrypt`: Base64-encoded key for gossip encryption. +- `server_join.retry_join`: A list of addresses to which the server will attempt to join the cluster. +Refer to the Nomad documentation for more details on the server configuration [here](https://developer.hashicorp.com/nomad/docs/configuration/server). +### Client Configuration -## Author Information -Bertrand Lanson +```yaml +nomad_enable_client: false +``` +Indicates whether the Nomad agent should operate as a client. Defaults to `false`, disabling the client stanza. -#### License +```yaml +nomad_client_configuration: + enabled: "{{ nomad_enable_client }}" + state_dir: "{{ nomad_data_dir }}/client" + cni_path: "/opt/cni/bin" + bridge_network_name: nomad + bridge_network_subnet: "172.26.64.0/20" +``` +Defines the client configuration stanza. Includes: +- `enabled`: References the `nomad_enable_client` variable to enable or disable the client. +- `state_dir`: Path to the directory where client state data will be stored. +- `cni_path`: Specifies the path to the Container Network Interface (CNI) binaries. +- `bridge_network_name`: The name of the bridge network used by the client. +- `bridge_network_subnet`: The subnet for the bridge network. -license (BSD, MIT) +Refer to the Nomad documentation for more details on the client configuration [here](https://developer.hashicorp.com/nomad/docs/configuration/client). -#### Minimum Ansible Version +### UI Configuration -2.10 +```yaml +nomad_ui_configuration: + enabled: "{{ nomad_enable_server }}" +``` +Configures the Nomad UI. By default, the `enabled` field determines whether the UI is active and is set based on the `nomad_enable_server` variable, meaning the UI will only be enabled if the Nomad server is enabled. -#### Platforms +### Drivers Configuration -- **Ubuntu**: ['focal', 'jammy', 'noble'] -- **Debian**: ['bullseye', 'bookworm'] +```yaml +nomad_driver_enable_docker: true +``` +Indicates whether the Docker driver should be enabled. Currently, this setting is not functional but is included for future development. - +```yaml +nomad_driver_enable_podman: false +``` +Indicates whether the Podman driver should be enabled. Currently, this setting is not functional. + +```yaml +nomad_driver_enable_raw_exec: false +``` +Indicates whether the Raw Exec driver should be enabled. Currently, this setting is not functional. + +```yaml +nomad_driver_enable_java: false +``` +Indicates whether the Java driver should be enabled. Currently, this setting is not functional. + +```yaml +nomad_driver_enable_qemu: false +``` +Indicates whether the QEMU driver should be enabled. Currently, this setting is not functional. + +```yaml +nomad_driver_configuration: + raw_exec: + enabled: false +``` +This block defines the configuration for Nomad drivers. The example shows the configuration for the Raw Exec driver, which is currently disabled. + +```yaml +nomad_driver_extra_configuration: {} +``` +A dictionary for any additional driver configuration options not covered by other variables. This should be used only for options not provided by existing variables and will be merged with the `nomad_driver_configuration`, taking precedence over existing settings. + +### Nomad Logging + +```yaml +nomad_log_level: info +``` +Sets the logging level for Nomad. Accepted values are `trace`, `debug`, `info`, `warn`, and `error`. See [Nomad documentation on log levels](https://developer.hashicorp.com/nomad/docs/configuration#log_level) for more details. + +```yaml +nomad_enable_log_to_file: false +``` +Enables logging to a file if set to `true`. When enabled, the settings in `nomad_log_to_file_configuration` will define the log file path, rotation frequency, and retention of logs. + +```yaml +nomad_log_to_file_configuration: + log_file: "{{ nomad_logs_dir }}/nomad.log" + log_rotate_duration: 24h + log_rotate_max_files: 30 +``` +Specifies configuration for file-based logging: +- **`log_file`**: Defines the path to the Nomad log file (e.g., `nomad_logs_dir/nomad.log`). See [Nomad log file configuration](https://developer.hashicorp.com/nomad/docs/configuration#log_file) 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 `nomad_enable_log_to_file` set to `true`, these settings provide a default configuration for logging to a file, allowing Nomad to manage log files and rotation automatically. + +### ACL Configuration + +```yaml +nomad_acl_configuration: + enabled: false + token_ttl: "30s" + policy_ttl: "60s" + role_ttl: "60s" +``` +This variable corresponds to the ACL stanza in the Nomad configuration, defining the following settings: +This configuration mirrors the structure outlined in the [Nomad ACL documentation](https://developer.hashicorp.com/nomad/docs/configuration/acl). + +### Internal TLS Configuration + +```yaml +nomad_enable_tls: false +``` +Indicates whether internal TLS should be enabled for the Nomad cluster. + +```yaml +nomad_tls_configuration: + http: true + rpc: true + ca_file: "/etc/ssl/certs/ca-certificates.crt" + cert_file: "{{ nomad_certs_dir }}/cert.pem" + key_file: "{{ nomad_certs_dir }}/key.pem" + verify_server_hostname: true +``` +This block defines the TLS configuration for the Nomad cluster. It includes options for enabling TLS for HTTP and RPC, paths to the CA file, certificate file, key file, and verification settings for the server hostname. For detailed information, refer to the [Nomad TLS documentation](https://developer.hashicorp.com/nomad/docs/configuration/tls). + +```yaml +nomad_certificates_extra_files_dir: [] +``` +A list for additional certificate files that can be added to the `nomad_extra_files_list` variable. If used, `nomad_extra_files` should be set to true to ensure the certificates are copied to the target host. + +### Telemetry Configuration + +```yaml +nomad_telemetry_configuration: + collection_interval: 10s + disable_hostname: false + use_node_name: false + publish_allocation_metrics: false + publish_node_metrics: false + prefix_filter: [] + disable_dispatched_job_summary_metrics: false + prometheus_metrics: false +``` +This block configures telemetry settings for Nomad. Each option adjusts different aspects of telemetry data collection and publication. For more information, refer to the [Nomad Telemetry documentation](https://developer.hashicorp.com/nomad/docs/configuration/telemetry). + +### Consul Integration Configuration + +```yaml +nomad_enable_consul_integration: false +``` +This variable enables the Consul integration for service registration in Nomad. + +```yaml +nomad_consul_integration_configuration: + address: "127.0.0.1:8500" + auto_advertise: true + ssl: false + token: "" + tags: [] +``` +This block represents the **Consul** stanza, which configures the integration with Consul for service registration. For more details, refer to the [Nomad Consul documentation](https://developer.hashicorp.com/nomad/docs/configuration/consul). + +```yaml +nomad_consul_integration_tls_configuration: + ca_file: "/etc/ssl/certs/ca-certificates.crt" +``` +If `nomad_consul_integration_configuration.ssl` is defined and set to `true`, the **TLS configuration** will be merged with the `nomad_consul_integration_configuration` for defining TLS-specific settings. + +```yaml +nomad_consul_integration_server_configuration: + server_auto_join: true +``` +If `nomad_enable_server` is set to `true`, this configuration block will be merged with `nomad_consul_integration_configuration` to provide additional settings for the server's integration with Consul. + +```yaml +nomad_consul_integration_client_configuration: + client_auto_join: true + grpc_address: "127.0.0.1:8502" +``` +If `nomad_enable_client` is set to `true`, this block will be merged with `nomad_consul_integration_configuration` to define the client configuration for the Consul integration. + +```yaml +nomad_consul_integration_client_tls_configuration: + grpc_ca_file: "/etc/ssl/certs/ca-certificates.crt" +``` +If both the client is enabled and SSL is enabled, this configuration will be merged with `nomad_consul_integration_client_configuration` for the gRPC connection to Consul. + +Here's the refined **Nomad Vault Integration Configuration** section with the correct formatting and linking to the documentation: + +### Nomad Vault Integration Configuration + +```yaml +nomad_enable_vault_integration: false +``` +This variable enables the Vault integration in Nomad. + +```yaml +nomad_vault_integration_configuration: {} +``` +This block represents the **Vault** stanza, which configures the integration with HashiCorp Vault for managing secrets and sensitive data. For more details, refer to the [Nomad Vault documentation](https://developer.hashicorp.com/nomad/docs/configuration/vault). + +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.nomad +``` + +License +------- + +MIT / BSD + +Author Information +------------------ + +This role was created by Bertrand Lanson in 2023. diff --git a/roles/vault/.docsible b/roles/vault/.docsible deleted file mode 100644 index 7713e0f..0000000 --- a/roles/vault/.docsible +++ /dev/null @@ -1,13 +0,0 @@ -aap_hub: null -automation_kind: null -category: null -critical: null -description: null -dt_dev: null -dt_prod: null -dt_update: 26/08/2024 -requester: null -subCategory: null -time_saving: null -users: null -version: null diff --git a/roles/vault/README.md b/roles/vault/README.md index e26d2a1..1a6f816 100644 --- a/roles/vault/README.md +++ b/roles/vault/README.md @@ -1,193 +1,266 @@ - +**Vault** +========= -# 📃 Role overview +This role configures [HashiCorp Vault](https://www.hashicorp.com/products/vault) on **Debian-based** distributions. -## vault +**Requirements** +------------ +This role requires that the `unzip` package is installed on the target host. +If using the auto-unseal feature from this role, it also requires the `hvac` Python library to be installed on the target host. +**Role Variables** +-------------- -Description: Install and configure hashicorp vault for debian-based distros. +### Service Configuration +```yaml +vault_version: latest +``` +Specifies the version of Vault to install. Default is `latest`, which installs the latest stable version. It is recommended to pin the vault 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 vault's [release repository](https://releases.hashicorp.com/vault/) (just strip out the leading `vault_`) -| Field | Value | -|--------------------- |-----------------| -| Readme update | 26/08/2024 | +```yaml +vault_start_service: true +``` +Indicates whether the Vault service should start after installation. Defaults to `true`. +```yaml +vault_config_dir: "/etc/vault.d" +``` +Path to the directory where Vault's configuration files are stored. +```yaml +vault_data_dir: "/opt/vault" +``` +Specifies the directory where Vault will store its data. +```yaml +vault_certs_dir: "{{ vault_config_dir }}/tls" +``` +Path to the directory where Vault's TLS certificates should be stored when using internal TLS. +```yaml +vault_logs_dir: "/var/log/vault" +``` +Directory path where Vault's log files will be stored if logging to file is enabled. +```yaml +vault_extra_files: false +``` +If `true`, allows additional files to be copied over to the target host by the role. -### Defaults +```yaml +vault_extra_files_list: [] +``` +A list of additional files to manage with the role if `vault_extra_files` is set to `true`. This is a list of objects like: -**These are static variables with lower priority** +```yaml +- src: /path/on/deploy/machine + dest: /path/to/copy/over +``` -#### File: defaults/main.yml +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. -| Var | Type | Value |Required | Title | -|--------------|--------------|-------------|-------------|-------------| -| [vault_version](defaults/main.yml#L3) | str | `latest` | n/a | n/a | -| [vault_start_service](defaults/main.yml#L4) | bool | `True` | n/a | n/a | -| [vault_config_dir](defaults/main.yml#L5) | str | `/etc/vault.d` | n/a | n/a | -| [vault_data_dir](defaults/main.yml#L6) | str | `/opt/vault` | n/a | n/a | -| [vault_certs_dir](defaults/main.yml#L7) | str | `{{ vault_config_dir }}/tls` | n/a | n/a | -| [vault_logs_dir](defaults/main.yml#L8) | str | `/var/log/vault` | n/a | n/a | -| [vault_extra_files](defaults/main.yml#L10) | bool | `False` | n/a | n/a | -| [vault_extra_files_list](defaults/main.yml#L11) | list | `[]` | n/a | n/a | -| [vault_env_variables](defaults/main.yml#L13) | dict | `{}` | n/a | n/a | -| [vault_extra_configuration](defaults/main.yml#L24) | dict | `{}` | n/a | n/a | -| [vault_cluster_name](defaults/main.yml#L30) | str | `vault` | n/a | n/a | -| [vault_bind_addr](defaults/main.yml#L31) | str | `0.0.0.0` | n/a | n/a | -| [vault_cluster_addr](defaults/main.yml#L32) | str | `{{ ansible_default_ipv4.address }}` | n/a | n/a | -| [vault_enable_ui](defaults/main.yml#L33) | bool | `True` | n/a | n/a | -| [vault_disable_mlock](defaults/main.yml#L34) | bool | `False` | n/a | n/a | -| [vault_disable_cache](defaults/main.yml#L35) | bool | `False` | n/a | n/a | -| [vault_storage_configuration](defaults/main.yml#L41) | dict | `{'file': {'path': '{{ vault_data_dir }}'}}` | n/a | n/a | -| [vault_enable_tls](defaults/main.yml#L49) | bool | `False` | n/a | n/a | -| [vault_listener_configuration](defaults/main.yml#L50) | list | `[{'tcp': {'address': '{{ vault_cluster_addr }}:8200', 'tls_disable': True}}]` | n/a | n/a | -| [vault_tls_listener_configuration](defaults/main.yml#L55) | list | `[{'tcp': {'tls_disable': False, 'tls_cert_file': '{{ vault_certs_dir }}/cert.pem', 'tls_key_file': '{{ vault_certs_dir }}/key.pem', 'tls_disable_client_certs': True}}]` | n/a | n/a | -| [vault_certificates_extra_files_dir](defaults/main.yml#L62) | list | `[]` | n/a | n/a | -| [vault_extra_listener_configuration](defaults/main.yml#L67) | list | `[]` | n/a | n/a | -| [vault_enable_service_registration](defaults/main.yml#L73) | bool | `False` | n/a | n/a | -| [vault_service_registration_configuration](defaults/main.yml#L74) | dict | `{'consul': {'address': '127.0.0.1:8500', 'scheme': 'http', 'token': ''}}` | n/a | n/a | -| [vault_enable_plugins](defaults/main.yml#L84) | bool | `False` | n/a | n/a | -| [vault_plugins_directory](defaults/main.yml#L85) | str | `{{ vault_config_dir }}/plugins` | n/a | n/a | -| [vault_log_level](defaults/main.yml#L91) | str | `info` | n/a | n/a | -| [vault_enable_log_to_file](defaults/main.yml#L92) | bool | `False` | n/a | n/a | -| [vault_log_to_file_configuration](defaults/main.yml#L93) | dict | `{'log_file': '{{ vault_logs_dir }}/vault.log', 'log_rotate_duration': '24h', 'log_rotate_max_files': 30}` | n/a | n/a | +Example: +```yaml +vault_extra_files_list: + - src: /local/path/to/tls/files + dest: "{{ vault_certs_dir }}" + - src: /another/single/file.j2 + dest: /var/lib/file +``` -### Vars +```yaml +vault_env_variables: {} +``` +Environment variables to be set for the Vault service, defined as key-value pairs. -**These are variables with higher priority** -#### File: vars/main.yml +### Extra Configuration -| Var | Type | Value |Required | Title | -|--------------|--------------|-------------|-------------|-------------| -| [vault_user](vars/main.yml#L3) | str | `vault` | n/a | n/a | -| [vault_group](vars/main.yml#L4) | str | `vault` | n/a | n/a | -| [vault_binary_path](vars/main.yml#L5) | str | `/usr/local/bin/vault` | n/a | n/a | -| [vault_deb_architecture_map](vars/main.yml#L6) | dict | `{'x86_64': 'amd64', 'aarch64': 'arm64', 'armv7l': 'arm', 'armv6l': 'arm'}` | n/a | n/a | -| [vault_architecture](vars/main.yml#L11) | str | `{{ vault_deb_architecture_map[ansible_architecture] \| default(ansible_architecture) }}` | n/a | n/a | -| [vault_service_name](vars/main.yml#L12) | str | `vault` | n/a | n/a | -| [vault_github_api](vars/main.yml#L13) | str | `https://api.github.com/repos` | n/a | n/a | -| [vault_github_project](vars/main.yml#L14) | str | `hashicorp/vault` | n/a | n/a | -| [vault_github_url](vars/main.yml#L15) | str | `https://github.com` | n/a | n/a | -| [vault_repository_url](vars/main.yml#L16) | str | `https://releases.hashicorp.com/vault` | n/a | n/a | -| [vault_configuration](vars/main.yml#L18) | dict | `{'cluster_name': '{{ vault_cluster_name }}', 'cluster_addr': "{{ 'https' if vault_enable_tls else 'http'}}://{{ vault_cluster_addr }}:8201", 'api_addr': "{{ 'https' if vault_enable_tls else 'http'}}://{{ vault_cluster_addr }}:8200", 'ui': '{{ vault_enable_ui }}', 'disable_mlock': '{{ vault_disable_mlock }}', 'disable_cache': '{{ vault_disable_cache }}', 'listener': '{{ vault_listener_configuration }}', 'storage': '{{ vault_storage_configuration }}'}` | n/a | n/a | +```yaml +vault_extra_configuration: {} +``` +Dictionary for any additional Vault configuration options not covered by other variables. This should be used only for options not provided by existing variables. +### General -### Tasks +```yaml +vault_cluster_name: vault +``` +Specifies the name of the Vault cluster. Default is `vault`. +```yaml +vault_bind_addr: "0.0.0.0" +``` +Defines the IP address that Vault will bind to for communication. Default is `"0.0.0.0"`, allowing connections from any IP address. -#### File: tasks/recursive_copy_extra_dirs.yml +```yaml +vault_cluster_addr: "{{ ansible_default_ipv4.address }}" +``` +Sets the address for Vault cluster communication, typically the IP of the host running Vault. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Vault \| Ensure destination directory exists | ansible.builtin.file | False | -| Vault \| Create extra directory sources | ansible.builtin.file | True | -| Vault \| Template extra directory sources | ansible.builtin.template | True | +```yaml +vault_enable_ui: true +``` +Enables the Vault web UI if set to `true`. Default is `true`. -#### File: tasks/merge_variables.yml +```yaml +vault_disable_mlock: false +``` +If set to `true`, disables the use of `mlock` syscall, which can prevent Vault from being able to lock its memory. Useful in environments where `mlock` is restricted. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Vault \| Merge listener configuration | block | False | -| Vault \| Merge tls listener configuration | vars | True | -| Vault \| Merge extra listener configuration | vars | False | -| Vault \| Add certificates directory to extra_files_dir | ansible.builtin.set_fact | False | -| Vault \| Merge service registration configuration | vars | True | -| Vault \| Merge plugins configuration | vars | True | -| Vault \| Merge logging configuration | vars | True | -| Vault \| Merge extra configuration settings | vars | True | +```yaml +vault_disable_cache: false +``` +Disables Vault’s cache if set to `true`, forcing Vault to avoid caching data. -#### File: tasks/main.yml +### Storage Configuration -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Vault \| Set reload-check & restart-check variable | ansible.builtin.set_fact | False | -| Vault \| Import merge_variables.yml | ansible.builtin.include_tasks | False | -| Vault \| Import prerequisites.yml | ansible.builtin.include_tasks | False | -| Vault \| Import install.yml | ansible.builtin.include_tasks | False | -| Vault \| Import configure.yml | ansible.builtin.include_tasks | False | -| Vault \| Populate service facts | ansible.builtin.service_facts | False | -| Vault \| Set restart-check variable | ansible.builtin.set_fact | True | -| Vault \| Enable service: {{ vault_service_name }} | ansible.builtin.service | False | -| Vault \| Reload systemd daemon | ansible.builtin.systemd | True | -| Vault \| Start service: {{ vault_service_name }} | ansible.builtin.service | True | +```yaml +vault_storage_configuration: + file: + path: "{{ vault_data_dir }}" +``` +Defines the storage backend configuration for Vault, provided as a dictionary. This configuration should resemble the `storage` stanza from the [Vault documentation](https://developer.hashicorp.com/vault/docs/configuration/storage), allowing users to specify their preferred storage backend and its associated options. Here, `file` storage is configured, with `path` set to `vault_data_dir` for file-based storage. -#### File: tasks/install.yml +### Auto-Unseal Configuration -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Vault \| Get latest release of vault | block | True | -| Vault \| Get latest vault release from github api | ansible.builtin.uri | False | -| Vault \| Set wanted vault version to latest tag | ansible.builtin.set_fact | False | -| Vault \| Set wanted vault version to {{ vault_version }} | ansible.builtin.set_fact | True | -| Vault \| Get current vault version | block | False | -| Vault \| Stat vault version file | ansible.builtin.stat | False | -| Vault \| Get current vault version | ansible.builtin.slurp | True | -| Vault \| Download and install vault binary | block | True | -| Vault \| Set vault package name to download | ansible.builtin.set_fact | False | -| Vault \| Download checksum file for vault archive | ansible.builtin.get_url | False | -| Vault \| Extract correct checksum from checksum file | ansible.builtin.command | False | -| Vault \| Parse the expected checksum | ansible.builtin.set_fact | False | -| Vault \| Download vault binary archive | ansible.builtin.get_url | False | -| Vault \| Create temporary directory for archive decompression | ansible.builtin.file | False | -| Vault \| Unpack vault archive | ansible.builtin.unarchive | False | -| Vault \| Copy vault binary to {{ vault_binary_path }} | ansible.builtin.copy | False | -| Vault \| Update vault version file | ansible.builtin.copy | False | -| Vault \| Set restart-check variable | ansible.builtin.set_fact | False | -| Vault \| Cleanup temporary directory | ansible.builtin.file | False | -| Vault \| Copy systemd service file for vault | ansible.builtin.template | False | -| Vault \| Set reload-check & restart-check variable | ansible.builtin.set_fact | True | -| Vault \| Copy systemd service file for vault | ansible.builtin.template | False | +```yaml +vault_enable_auto_unseal: false +``` +Enables or disables Vault's auto-unseal feature. If set to `true` and `vault_unseal_keys` is not empty, the role will attempt to unseal Vault automatically after it has started or restarted. Requires the `hvac` Python library. -#### File: tasks/prerequisites.yml +```yaml +vault_unseal_url: "https://127.0.0.1:8200" +``` +Specifies the URL of the Vault server used for the unseal operation. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Vault \| Create group {{ vault_group }} | ansible.builtin.group | False | -| Vault \| Create user {{ vault_user }} | ansible.builtin.user | False | -| Vault \| Create directory {{ vault_config_dir }} | ansible.builtin.file | False | -| Vault \| Create directory {{ vault_data_dir}} | ansible.builtin.file | False | -| Vault \| Create directory {{ vault_certs_dir }} | ansible.builtin.file | False | -| Vault \| Create directory {{ vault_logs_dir }} | ansible.builtin.file | True | +```yaml +vault_unseal_tls_verify: true +``` +Determines whether TLS verification is enabled for the unseal process. If `true`, Vault will verify the TLS certificate when connecting to `vault_unseal_url`. -#### File: tasks/configure.yml +```yaml +vault_unseal_keys: [] +``` +A list of unseal keys used to unseal the Vault server. This list should contain valid unseal keys if `vault_enable_auto_unseal` is `true`. -| Name | Module | Has Conditions | -| ---- | ------ | --------- | -| Vault \| Create vault.env | ansible.builtin.template | False | -| Vault \| Copy vault.json template | ansible.builtin.template | False | -| Vault \| Set restart-check variable | ansible.builtin.set_fact | True | -| Vault \| Copy extra configuration files | block | True | -| Vault \| Get extra file types | ansible.builtin.stat | False | -| Vault \| Set list for file sources | vars | True | -| Vault \| Set list for directory sources | vars | True | -| Vault \| Template extra file sources | ansible.builtin.template | True | -| Vault \| Template extra directory sources | ansible.builtin.include_tasks | True | +### Listener Configuration +```yaml +vault_enable_tls: false +``` +Enables TLS for Vault listeners if set to `true`. When enabled, `vault_tls_listener_configuration` settings will take precedence over non-TLS settings. +```yaml +vault_listener_configuration: + - tcp: + address: "{{ vault_cluster_addr }}:8200" + tls_disable: true +``` +Defines the default listener configuration for Vault. Here, it uses TCP with TLS disabled, binding to the `vault_cluster_addr` on port `8200`. +```yaml +vault_tls_listener_configuration: + - tcp: + tls_disable: false + tls_cert_file: "{{ vault_certs_dir }}/cert.pem" + tls_key_file: "{{ vault_certs_dir }}/key.pem" + tls_disable_client_certs: true +``` +Specifies the TLS listener configuration for Vault. When `vault_enable_tls` is `true`, this configuration merges with `vault_listener_configuration`, with TLS settings overriding non-TLS values where applicable. +```yaml +vault_certificates_extra_files_dir: [] +``` +List of directories/files containing additional TLS certificates. These will be appended to `vault_extra_files_list` (with `vault_extra_files` set to `true`), ensuring Vault has access to required certificate files. +```yaml +vault_extra_listener_configuration: [] +``` +Allows adding custom listener configurations to extend the main listener settings. This configuration merges with the combined result of `vault_listener_configuration` and `vault_tls_listener_configuration`. +**Note on Merging Configuration:** -## Author Information -Bertrand Lanson +- If `vault_enable_tls` is set to `true`, `vault_listener_configuration` and `vault_tls_listener_configuration` are merged with priority given to TLS settings. +- The combined listener configurations are further extended by `vault_extra_listener_configuration`, enabling a flexible and layered configuration approach. +- `vault_certificates_extra_files_dir` directories will add entries to `vault_extra_files_list`, ensuring certificate files are available for Vault. To activate this, `vault_extra_files` should be set to `true`. -#### License +### Service Registration -license (BSD, MIT) +```yaml +vault_enable_service_registration: false +``` +Enables or disables service registration for Vault. When set to `true`, Vault will attempt to register itself with the specified service registration provider. -#### Minimum Ansible Version +```yaml +vault_service_registration_configuration: + consul: + address: "127.0.0.1:8500" + scheme: "http" + token: "" +``` +Defines the configuration for service registration, resembling a `service_registration` stanza from the [Vault documentation](https://developer.hashicorp.com/vault/docs/configuration/service-registration). Here, Consul is configured as the service registry with its `address`, `scheme`, and optional `token`. This allows Vault to register with Consul for service discovery if `vault_enable_service_registration` is `true`. -2.10 +### Plugins Configuration -#### Platforms +```yaml +vault_enable_plugins: false +``` +Enables plugin configuration for Vault if set to `true`. This only adds the necessary entries to the Vault configuration file; actual plugin files must be copied to the plugins directory by the user or managed using the `vault_extra_files` variable. -- **Ubuntu**: ['focal', 'jammy', 'noble'] -- **Debian**: ['bullseye', 'bookworm'] +```yaml +vault_plugins_directory: "{{ vault_config_dir }}/plugins" +``` +Specifies the directory where Vault plugins are stored. Plugins should be manually placed in this directory, as enabling plugins within Vault itself is not yet managed by this role. - +### Vault Logging + +```yaml +vault_log_level: info +``` +Sets the logging level for Vault. Accepted values are `trace`, `debug`, `info`, `warn`, and `error`. See [Vault documentation on log levels](https://developer.hashicorp.com/vault/docs/configuration#log_level) for more details. + +```yaml +vault_enable_log_to_file: false +``` +Enables logging to a file if set to `true`. When enabled, the settings in `vault_log_to_file_configuration` will define the log file path, rotation frequency, and retention of logs. + +```yaml +vault_log_to_file_configuration: + log_file: "{{ vault_logs_dir }}/vault.log" + log_rotate_duration: 24h + log_rotate_max_files: 30 +``` +Specifies configuration for file-based logging: +- **`log_file`**: Defines the path to the Vault log file (e.g., `vault_logs_dir/vault.log`). See [Vault log file configuration](https://developer.hashicorp.com/vault/docs/configuration#log_file) 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 `vault_enable_log_to_file` set to `true`, these settings provide a default configuration for logging to a file, allowing Vault 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.vault +``` + +License +------- + +MIT / BSD + +Author Information +------------------ + +This role was created by Bertrand Lanson in 2023. diff --git a/roles/vault/defaults/main.yml b/roles/vault/defaults/main.yml index 6d19658..325199f 100644 --- a/roles/vault/defaults/main.yml +++ b/roles/vault/defaults/main.yml @@ -93,9 +93,9 @@ vault_service_registration_configuration: vault_enable_plugins: false vault_plugins_directory: "{{ vault_config_dir }}/plugins" -################# -# vault logging # -################# +########### +# logging # +########### vault_log_level: info vault_enable_log_to_file: false