Introduction

Understanding the real-time configuration of a Nomad agent is crucial for troubleshooting, verification, and maintaining the health of your cluster. While configuration files define the intended state, the values held in memory by the running Nomad agent can sometimes differ due to dynamic updates, environment variables, or other operational factors. This article provides a clear, step-by-step guide on how to leverage the Nomad HTTP API's agent/self endpoint to retrieve all active configuration values directly from a running Nomad agent.

Expected Outcome

View the real-time configuration and runtime status of a Nomad agent. This includes all its current values, or a subset of values filtered by specific keys.

Prerequisites

Adequate permissions: An Access Control List (ACL) with the node:read policy is required.

Host access: Direct network or local access to the Nomad agent's host.

Command-line tools:

• A terminal or command prompt.
• curl: A tool for making HTTP requests.
• jq (recommended): A lightweight and flexible command-line JSON processor. It simplifies parsing and filtering the JSON output.
• grep or awk: Standard Unix/Linux tools for pattern matching and text processing.

Use Case

This procedure is useful for troubleshooting, verifying configurations, and monitoring a Nomad agent's health and settings. For example, you can quickly check if the agent is in the correct datacenter, if ACLs are enabled, or what its current CPU and memory usage statistics are.

Procedure

The following examples demonstrate how to use curl to query the Nomad agent's /v1/agent/self API endpoint, which provides a comprehensive overview of its state. The examples use 127.0.0.1 (localhost); for remote hosts, replace this IP address with the remote host's IP.

View all configuration and runtime values

To get a full dump of the agent's state, use curl to query the endpoint. Piping the output to jq formats the JSON into a human-readable, color-coded structure.

• With jq (recommended):

  curl -s http://127.0.0.1:4646/v1/agent/self | jq

• Without jq (using awk):

  This command uses awk to manually format the JSON by adding newlines after commas and curly braces.

  curl -s http://172.0.0.1:4646/v1/agent/self | awk '{gsub(/,/,",\n"); gsub(/{/,"{\n"); gsub(/}/,"\n}"); print}'

Example Output  ("..." in place of output not shown):

{
  "config": {
    "ACL": {
      "Enabled": false,
      "PolicyTTL": 30000000000,
      "ReplicationToken": "",
      "RoleTTL": 30000000000,
      "TokenMaxExpirationTTL": 0,
      "TokenMinExpirationTTL": 0,
      "TokenTTL": 30000000000
    },
...
  "stats": {
...
    "runtime": {
      "arch": "amd64",
      "cpu_count": "2",
      "goroutines": "97",
      "kernel.name": "linux",
      "max_procs": "2",
      "version": "go1.24.3"
    }
  }
}

View specific values

To filter the output and get only a specific key, you can use jq or grep. jq is more precise as it understands the JSON structure, while grep is a simple text search.

• Using jq:

  Use jq's dot notation to pinpoint a specific field. For example, to get the Datacenter value:

  curl -s http://127.0.0.1:4646/v1/agent/self | jq .config.Datacenter

  Example Output:

  "dc1"

  Or, to get multiple keys, separate them with a comma:

  curl -s http://127.0.0.1:4646/v1/agent/self | jq '.config.Datacenter, .stats.runtime.goroutines'

• Using grep:

  Pipe the output to grep to search for a key. This is less precise and may return keys within other objects or strings.

  curl -s http://127.0.0.1:4646/v1/agent/self | grep Datacenter

  Example Output:

  "Datacenter": "dc1",

Additional Information

For more detailed information on Nomad agent configurations and API endpoints, refer to the official documentation:

• Nomad Agent Command Reference: Detailed information on the nomad agent command.
• Nomad Agent Configuration: A complete list of all configurable parameters.
• Other commands: For more advanced text processing, consult the documentation for jq, grep, and awk.