> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consul

> Consul cluster and catalog health metrics from Consul agents.

The Consul integration requires CXDOT Collector 1.4.0 or greater.

[Consul](https://developer.hashicorp.com/consul) is a distributed system for
connecting and configuring applications across dynamic infrastructure. Use the
Consul CXDOT Collector integration to collect cluster and catalog health metrics
from Consul agents in your environment.

## Supported telemetry types

The Consul integration supports these telemetry types:

| Type | Supported |
| - | - |
| Logs | No |
| Metrics | Yes |
| Traces | No |
| Events | No |

## Prerequisites

Meet these requirements before configuring the integration:

* Make each Consul agent HTTP API reachable from the Collector tier that scrapes
  it (node-local agents on the node Collector; static targets on the cluster
  Collector).
* When Consul access control lists are enabled, provide a token with read access
  to the agent, catalog, and health endpoints.

## Configure

To configure the Consul integration, follow these steps:

1. Choose how the CXDOT Collector discovers Consul agents:

   * For agents that expose the HTTP API on port `8500`, add the `app: consul`
     label to the pod template. HashiCorp's official chart sets this label.
   * For agents that need a different URL, ACL token, or TLS settings, use
     discovery annotations on the Pod or Service. For more information, see
     [autodiscovery](https://docs.chronosphere.io/ingest/cxdot-collector/autodiscovery).

   The CXDOT Collector creates and enables an unnamed Consul instance that uses
   discovery by default.

2. Optional: To use static targets instead of discovery, list dialable
   `host:port` values or full URLs in `endpoints`. A nonempty list disables
   discovery for that instance; the Collector scrapes only those agents. When
   ACLs are enabled, set `acl_token`. For example:

   ```yaml theme={null}
   config:
     integrations:
       consul:
         acl_token: "${env:CONSUL_HTTP_TOKEN}"
         endpoints:
           - endpoint: consul.example.com:8500
   ```

3. Optional: To combine discovery and static targets, configure separate
   instances. The unnamed instance uses discovery, and the named instance
   scrapes the static targets:

   ```yaml theme={null}
   config:
     integrations:
       consul: {}
       consul/static:
         acl_token: "${env:CONSUL_HTTP_TOKEN}"
         endpoints:
           - endpoint: consul.example.com:8500
   ```

### Validate

1. In the
   [Live Telemetry Analyzer](https://docs.chronosphere.io/investigate/analyze/telemetry-analyzer),
   add the following label filters:

   * Set **Label** to `__name__` and **Value** to
     `cxdot.integration.target.health`.
   * Set **Label** to `cxdot.integration.name` and **Value** to `consul`.

   Group the results by `cxdot.integration.target`, and confirm that the metric
   reports `1` for each target.

2. In
   [Metrics Explorer](https://docs.chronosphere.io/investigate/querying/metrics/explorer),
   run the following query:

   ```text theme={null}
   count by ("server.address", "server.port", "consul.mode") ({"consul.peers"})
   ```

   Confirm that each agent you expect appears. Only agents where
   `consul.mode="leader"` also emit catalog metrics for the datacenter.

### Troubleshooting

* Consul metrics do not appear and Collector logs report HTTP `403` responses:
  Confirm that the ACL token has read access to the agent, catalog, and health
  endpoints.
* Catalog metrics are missing for an agent, but `consul.peers` appears: Only the
  Raft leader for a datacenter reports catalog metrics; other agents report peer
  count only.

## Disable the Consul integration

Deleting every `consul` block restores the default unnamed instance. To remove
custom settings and stop collection, retain a disabled configuration:

```yaml theme={null}
config:
  integrations:
    consul:
      enabled: false
```

For more information about diagnosing a failing integration, see
[Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/troubleshooting).

## Configuration reference

Configure one Consul integration instance with the following settings. In Helm values, place
these settings under `config.integrations.consul`. In a Collector configuration file, place them
under `cxdot.integrations.consul`.

### Optional settings

* **`enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this Consul integration instance. If true, the Collector runs the instance.
  If false, the Collector doesn't run it.

* **`endpoints`**
  Type: `array of object`. Optional. Default: `[]`.
  Static Consul targets. A nonempty list disables automatic discovery for this integration
  instance, and the Collector collects metrics from only the listed targets. Specify a target as
  `host:port` to use HTTP. Specify a full HTTP or HTTPS URL to control the scheme.

* **`endpoints[].endpoint`**
  Type: `string`. Required.
  Consul target as either `host:port` or a full HTTP or HTTPS URL.

* **`acl_token`**
  Type: `string`. Optional.
  Consul access control list token sent in the `X-Consul-Token` header. Provide a token with
  read access to the agent, catalog, and health endpoints when access control lists are enabled.
  The Collector masks this sensitive value in diagnostic output, logs, and errors. Discovery
  annotations can provide a target-specific token.

* **`collection_interval`**
  Type: `duration`. Optional. Default: `15s`.
  How often the Collector collects metrics from each Consul target.

* **`timeout`**
  Type: `duration`. Optional. Default: `15s`.
  Maximum time allowed to collect metrics from one Consul target. The value must not exceed
  `collection_interval`.

* **`max_services`**
  Type: `integer`. Optional. Default: `50`. Minimum: `1`.
  Cap on how many catalog services one collection interrogates. Each service costs one
  health-endpoint request, so an unbounded catalog would turn a single collection into thousands
  of requests against the agent. Services are taken in name order once the catalog exceeds the
  cap, so the truncated set stays the same between collections rather than shifting with the
  agent's response ordering.

* **`tls`**
  Type: `object`. Optional.
  Transport layer security (TLS) settings for static HTTPS targets. Certificate verification is
  enabled unless `insecure_skip_verify` is true. These settings don't apply to HTTP targets.
  Discovery annotations can provide target-specific TLS settings.

* **`tls.ca_file`**
  Type: `string`. Optional.
  Path to the CA cert. For a client this verifies the server certificate. For a server this
  verifies client certificates. If empty uses system root CA. (optional)

* **`tls.ca_pem`**
  Type: `string`. Optional.
  In memory PEM encoded cert. (optional)

* **`tls.cert_file`**
  Type: `string`. Optional.
  Path to the TLS cert to use for TLS required connections. (optional)

* **`tls.cert_pem`**
  Type: `string`. Optional.
  In memory PEM encoded TLS cert to use for TLS required connections. (optional)

* **`tls.cipher_suites`**
  Type: `array of string`. Optional.
  CipherSuites is a list of TLS cipher suites that the TLS transport can use. If left blank, a
  safe default list is used. See
  [https://go.dev/src/crypto/tls/cipher\_suites.go](https://go.dev/src/crypto/tls/cipher_suites.go)
  for a list of supported cipher suites.

* **`tls.curve_preferences`**
  Type: `array of string`. Optional.
  contains the elliptic curves that will be used in an ECDHE handshake, in preference order
  Defaults to empty list and "crypto/tls" defaults are used, internally.

* **`tls.include_system_ca_certs_pool`**
  Type: `boolean`. Optional.
  If true, load system CA certificates pool in addition to the certificates configured in this
  struct.

* **`tls.insecure`**
  Type: `boolean`. Optional.
  In gRPC and HTTP when set to true, this is used to disable the client transport security. See
  [https://godoc.org/google.golang.org/grpc#WithInsecure](https://godoc.org/google.golang.org/grpc#WithInsecure)
  for gRPC. Please refer to
  [https://godoc.org/crypto/tls#Config](https://godoc.org/crypto/tls#Config) for more
  information. (optional, default false)

* **`tls.insecure_skip_verify`**
  Type: `boolean`. Optional.
  InsecureSkipVerify will enable TLS but not verify the certificate.

* **`tls.key_file`**
  Type: `string`. Optional.
  Path to the TLS key to use for TLS required connections. (optional)

* **`tls.key_pem`**
  Type: `string`. Optional.
  In memory PEM encoded TLS key to use for TLS required connections. (optional)

* **`tls.max_version`**
  Type: `string`. Optional.
  MaxVersion sets the maximum TLS version that is acceptable. If not set, refer to crypto/tls
  for defaults. (optional)

* **`tls.min_version`**
  Type: `string`. Optional.
  MinVersion sets the minimum TLS version that is acceptable. If not set, TLS 1.2 will be used.
  (optional)

* **`tls.reload_interval`**
  Type: `duration`. Optional.
  ReloadInterval specifies the duration after which the certificate will be reloaded If not set,
  it will never be reloaded (optional)

* **`tls.server_name_override`**
  Type: `string`. Optional.
  ServerName requested by client for virtual hosting. This sets the ServerName in the TLSConfig.
  Please refer to [https://godoc.org/crypto/tls#Config](https://godoc.org/crypto/tls#Config) for
  more information. (optional)

* **`tls.tpm`**
  Type: `object`. Optional.
  Trusted platform module configuration

* **`tls.tpm.auth`**
  Type: `string`. Optional.
  Authorization value for the trusted platform module key.

* **`tls.tpm.enabled`**
  Type: `boolean`. Optional.
  Whether to use a trusted platform module for the TLS private key. If true, the Collector loads
  the key from the configured device or socket. If false, the Collector uses the configured key
  file or in-memory key.

* **`tls.tpm.owner_auth`**
  Type: `string`. Optional.
  Owner authorization value for the trusted platform module.

* **`tls.tpm.path`**
  Type: `string`. Optional.
  The path to the TPM device or Unix domain socket. For instance /dev/tpm0 or /dev/tpmrm0.


## Related topics

- [CXDOT Collector integrations](/ingest/xcor/integrations/collector.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.