Introduction
HashiCorp Nomad supports running on both IPv4 and IPv6 networks. However, by default, Nomad will attempt to bind and advertise on IPv4 addresses unless explicitly configured. If the advertise address is not correctly defined for IPv6, Nomad agents may fail to start with errors related to resolving the Serf advertise address.
This article explains how to configure Nomad to use IPv6, common errors that occur when advertise addresses are not properly set, and the steps to correctly configure Nomad for IPv6 environments.
Expected Outcome
Once you complete the configuration:
Nomad server and clients will successfully start using IPv6 addresses.
Nomad agents will advertise their HTTP, RPC, and Serf endpoints over IPv6.
Integration with Consul and Vault over IPv6 loopback (
[::1]) will work correctly.
Prerequisites
Nomad version: 1.10.2 or later (IPv6-compatible release)
Operating System: Linux (example tested on Ubuntu 20.04/22.04)
-
Network Requirements:
At least one IPv6 interface with a valid IPv6 address.
Ensure IPv6 networking is enabled on the host.
Use Case
An user wants to enable IPv6 for Nomad agents to:
Run Nomad clusters in IPv6-only environments.
Test IPv6 compliance using publicly validated IPv6 implementations.
Ensure Nomad integrates with Consul and Vault over IPv6 endpoints.
A typical failure occurs when IPv6 is enabled at the bind address level (bind_addr = "::") but no advertise address is explicitly configured.
Example error:
nomad[2751]: ==> Loaded configuration from /etc/nomad.d/nomad.hcl
nomad[2751]: ==> Starting Nomad agent...
nomad[2751]: ==> Error starting agent: server config setup failed: Failed to resolve Serf advertise address ":4648": lookup <nil>: no such host
nomad[2751]: 2025-09-30T07:25:52.035Z [ERROR] agent: error starting agent: error="server config setup failed: Failed to resolve Serf advertise address \":4648\": lookup <nil>: no such host"
systemd[1]: nomad.service: Main process exited, code=exited, status=1/FAILUREThis indicates Nomad is unable to determine which IPv6 address to use for advertising to other nodes.
Procedure
Step 1: Verify IPv6 is enabled on your system
Run the following command to ensure IPv6 is enabled and interfaces are assigned IPv6 addresses:
ip -6 addr show
You should see at least one valid IPv6 address (e.g., 2001:db8::1234/64).
Step 2: Configure Nomad with IPv6 bind address
In your nomad configuration (example - nomad.hcl) file, set the bind address to listen on all IPv6 interfaces:
data_dir = "/opt/nomad/data"
bind_addr = "::"This allows Nomad to listen on all IPv6 interfaces for HTTP, RPC, and Serf communications.
Step 3: Define IPv6 advertise addresses (Important Step)
Explicitly configure the advertise addresses for HTTP, RPC, and Serf to ensure Nomad uses IPv6:
advertise {
http = "{{ GetPublicInterfaces | include `type` `IPv6` | limit 1 | attr `address` }}"
rpc = "{{ GetPublicInterfaces | include `type` `IPv6` | limit 1 | attr `address` }}"
serf = "{{ GetPublicInterfaces | include `type` `IPv6` | limit 1 | attr `address` }}"
}This ensures that Nomad picks the correct IPv6 interface and avoids the “lookup <nil>” error.
Note - By default, if you haven't defined anything in your Nomad configuration for advertise section, Nomad will pick IPv4 address available on your network interfaces, which is being used by Nomad.
Step 4: Restart and validate Nomad service
Restart the Nomad service:
sudo systemctl restart nomad
sudo systemctl status nomad
Verify IPv6 bindings:
ss -tulpen | grep nomadYou should see Nomad listening on IPv6 addresses (e.g., [::]:4646, [::]:4647, [::]:4648).
Additional Information
If you see errors such as
lookup <nil>: no such host, it usually means Nomad cannot automatically determine which IPv6 address to use for advertising. Defining theadvertisestanza resolves this.When running in dual-stack (IPv4 + IPv6) environments, you can specify IPv4 or IPv6 addresses in the
advertisestanza depending on your cluster’s needs.