Introduction

Understanding the real-time configuration of a Consul agent is crucial for troubleshooting, verification, and maintaining the health of your service mesh. While configuration files define the intended state, the values held in memory by the running Consul 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 Consul HTTP API's agent/self endpoint to retrieve all active configuration values directly from a running Consul agent.

Expected Outcome

Upon following this guide, you will be able to:

• Retrieve a complete JSON output of all configuration values currently in use by a Consul agent.
• Filter and extract specific configuration parameters, such as Datacenter, NodeName, Version, or port assignments.
• Understand how to apply this knowledge for real-time operational insights into your Consul environment.

Prerequisites

Before proceeding, ensure you have the following:

• Consul Agent Running: A running Consul agent whose configuration you wish to inspect.
• Consul API Access: Network connectivity from your command-line terminal to the Consul agent's HTTP API port (default: 8500).
• Adequate Permissions: If Consul ACLs (Access Control Lists) are enabled, the API token used for the request must have agent:read permissions.
  • Note on ACL Tokens: You can provide the ACL token using the X-Consul-Token HTTP header for security (recommended), or via the ?token= query parameter (deprecated and discouraged due to potential logging of the token).
• curl: A command-line tool for making HTTP requests (commonly pre-installed on Linux/macOS, available for Windows).
• jq (Recommended): A lightweight and flexible command-line JSON processor. While not strictly required, jq significantly enhances the readability and parsing of the JSON output from the Consul API.

Use Case

This procedure is invaluable for:

• Troubleshooting: Quickly diagnose configuration discrepancies that might be causing unexpected behavior in your Consul agent or services.
• Verification: Confirm that configuration changes have been applied correctly and are active in the agent's memory.
• Auditing: Obtain a snapshot of an agent's live configuration for compliance or security reviews.
• Dynamic Insight: Get real-time views of agent values, especially useful in dynamic or auto-scaled environments where configuration might not be strictly static.

Procedure

The following examples demonstrate how to retrieve and filter the Consul agent's in-memory configuration values using curl.

Basic Retrieval of All Configuration Values

This command will output the entire JSON response from the agent/self endpoint.

1. Open your command-line terminal.
2. Execute one of the following commands, depending on whether jq is installed:

   • With jq installed (recommended for readability):

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

     • Explanation:
       • curl -s: Executes curl in silent mode (suppresses progress meter and error messages).
       • http://127.0.0.1:8500/v1/agent/self: The URL for the Consul agent's self API endpoint. Replace 127.0.0.1 with the remote IP address or hostname if executing from a different machine. The default HTTP port is 8500.
       • | jq .: Pipes the raw JSON output from curl to jq, which then pretty-prints it for easier reading. The . tells jq to output the entire input.

   • Without jq installed (basic formatting):

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

     • Explanation: This awk command attempts to add newlines after commas and curly braces to make the raw JSON output slightly more readable, although it's less robust than jq.

Expected Output (Partial Example)

The output will be a comprehensive JSON object containing various sections ("..." in place of output not shown)

{
  "Config": {
    "Datacenter": "dc1",
    "PrimaryDatacenter": "dc1",
    "NodeName": "ip-172-31-6-31",
    "NodeID": "4aee9086-c282-250d-c220-fd91f1d219f8",
    "Revision": "68f81912",
    "Server": true,
    "Version": "1.16.2",
    "BuildDate": "2023-09-19T19:29:18Z"
  },
...
  "Stats": {
...
    "Port": 8503,
    "Ports": {
      "Plaintext": -1,
      "TLS": 8503
    }
  }
}

Getting a Specific Configuration Value

To pinpoint a specific configuration parameter, you can pipe the JSON output to jq and use its powerful filtering capabilities, or use grep for simpler text matching.

• Using jq to extract a specific key (e.g., "Datacenter"):

  curl -s http://127.0.0.1:8500/v1/agent/self | jq .Config.Datacenter

  • Explanation: jq .Config.Datacenter navigates into the Config object and then extracts the value of the Datacenter key. This is much more precise than grep.

  Expected Output:

  "dc1"

• Using jq to extract multiple specific keys (e.g., "NodeName" and "Version"):

  curl -s http://127.0.0.1:8500/v1/agent/self | jq '{NodeName: .Config.NodeName, Version: .Config.Version}'

  Expected Output:

  {
    "NodeName": "ip-172-31-6-31",
    "Version": "1.16.2"
  }

• Using grep to find lines containing a specific string (less precise, but useful if jq is not available or for quick checks):

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

  Expected Output:

      "Datacenter": "dc1",
      "PrimaryDatacenter": "dc1",
        "Datacenter": "dc1",
      "Datacenter": "dc1",
      "PrimaryDatacenter": "dc1",

  • Note: grep will return all lines that contain the string "Datacenter", which might include redundant or unrelated entries if "Datacenter" appears in other parts of the JSON not directly related to the main configuration. jq provides more targeted extraction.

Using an ACL Token with the API Request

If your Consul environment has ACLs enabled, you will need to provide a valid token with agent:read permissions.

curl -s --header "X-Consul-Token: <YOUR_ACL_TOKEN>" http://127.0.0.1:8500/v1/agent/self | jq .

• Replace <YOUR_ACL_TOKEN> with your actual Consul ACL token.
• Security Best Practice: Always use the X-Consul-Token header for passing ACL tokens to avoid exposing them in logs or command history. The ?token= query parameter is deprecated.

Additional Information

• Consul Agent Configuration Reference: For a comprehensive list and explanation of all possible configuration parameters, refer to the official Consul Agent Configuration File Reference.
• Consul Agent HTTP API Documentation: The /v1/agent/self endpoint is part of the broader Consul Agent HTTP API. This documentation provides details on all agent-related API endpoints.
• Consul ACL System: Learn more about securing your Consul environment with ACLs and how to create tokens with specific permissions in the Consul ACL System documentation.
• jq Documentation: To master jq for advanced JSON parsing and manipulation, consult its official documentation.
• awk and grep: These are powerful standard Unix utilities. For more information, you can typically access their man pages via man awk and man grep in your terminal.