hcp-ansible/roles/nomad/README.md

Nomad

This role configures HashiCorp nomad on Debian-based distributions.

Requirements

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

Role Variables

Service Configuration

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 (just strip out the leading nomad_)

nomad_start_service: true

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

nomad_config_dir: "/etc/nomad.d"

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

nomad_data_dir: "/opt/nomad"

Specifies the directory where Nomad will store its data.

nomad_certs_dir: "{{ nomad_config_dir }}/tls"

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

nomad_logs_dir: "/var/log/nomad"

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

nomad_extra_files: false

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

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:

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

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

nomad_env_variables: {}

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

Extra Configuration

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

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.

nomad_datacenter: dc1

Defines the datacenter name for the Nomad agent. This is used for grouping nodes and services within a specific datacenter.

Address Configuration

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.

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.

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, including:

• 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.

Autopilot Configuration

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. The Autopilot configuration allows you to enable and configure features like automatic leader elections and health checks for the Nomad cluster.

Example configuration:

nomad_autopilot_configuration:
  cleanup_dead_servers: true
  last_contact_threshold: "200ms"
  max_trailing_logs: 250
  server_stabilization_time: "10s"

Leave Configuration

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.

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

nomad_enable_server: true

Indicates whether the Nomad agent should operate as a server. Defaults to true, enabling the server stanza.

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.

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.

Client Configuration

nomad_enable_client: false

Indicates whether the Nomad agent should operate as a client. Defaults to false, disabling the client stanza.

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.

Refer to the Nomad documentation for more details on the client configuration here.

UI Configuration

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.

Drivers Configuration

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.

nomad_driver_enable_podman: false

Indicates whether the Podman driver should be enabled. Currently, this setting is not functional.

nomad_driver_enable_raw_exec: false

Indicates whether the Raw Exec driver should be enabled. Currently, this setting is not functional.

nomad_driver_enable_java: false

Indicates whether the Java driver should be enabled. Currently, this setting is not functional.

nomad_driver_enable_qemu: false

Indicates whether the QEMU driver should be enabled. Currently, this setting is not functional.

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.

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

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 for more details.

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.

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

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.

Internal TLS Configuration

nomad_enable_tls: false

Indicates whether internal TLS should be enabled for the Nomad cluster.

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.

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

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.

Consul Integration Configuration

nomad_enable_consul_integration: false

This variable enables the Consul integration for service registration in Nomad.

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.

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.

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.

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.

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

nomad_enable_vault_integration: false

This variable enables the Vault integration in Nomad.

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.

Dependencies

None.

Example Playbook

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

License

MIT / BSD

Author Information

This role was created by Bertrand Lanson in 2023.