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

# HashiCorp Vault

> Collects cluster health, request performance, token, and storage backend metrics from HashiCorp Vault.

The Vault integration requires CXDOT Collector 1.7.0 or greater.

[HashiCorp Vault](https://developer.hashicorp.com/vault) stores and controls access
to secrets. Use the HashiCorp Vault integration with the CXDOT Collector
to collect health, leadership, runtime, and request metrics from Vault servers
running in your environment.

The HashiCorp Vault integration supports Vault 1.18 or greater.

## Supported telemetry types

The HashiCorp Vault integration supports these telemetry types:

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

## Prerequisites

The HashiCorp Vault integration has the following prerequisites:

* Enable the Vault Prometheus telemetry endpoint. Make sure that
  `prometheus_retention_time` is greater than `0`:

  ```hcl theme={null}
  telemetry {
    prometheus_retention_time = "30s"
  }
  ```

* Make the Vault API root, such as `https://vault.example.com:8200/v1`, reachable
  from the Collector.

* Choose one authentication method for `/v1/sys/metrics`:

  * Create a Vault token in the root namespace with `read` and `list` access to
    `sys/metrics`. Supply the token directly or through a Collector-local file.
  * Enable unauthenticated metrics access in the Vault TCP listener:

    ```hcl theme={null}
    listener "tcp" {
      telemetry {
        unauthenticated_metrics_access = true
      }
    }
    ```

    Configure the target with `no_token: true`. Unauthenticated metrics access is
    also required to collect each standby node's own metrics.

For more information about the endpoint requirements, see
[Vault telemetry configuration](https://developer.hashicorp.com/vault/docs/configuration/telemetry).

## Configure

The HashiCorp Vault integration is enabled by default. To configure it, follow these
steps:

1. For discovered Vault targets, add autodiscovery annotations that provide each
   target's Vault API URL and token or no-token setting. For more information, see
   [autodiscovery](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes).

2. Optional: Configure static instances as an alternative to autodiscovery. The
   Collector scrapes exactly the targets in a non-empty `instances` list and turns
   off discovery for that integration instance. To use both methods, add a named
   integration instance. For example:

   ```yaml theme={null}
   config:
     integrations:
       vault/external:
         instances:
           - endpoint: https://vault-auth.example.com:8200/v1
             client_token: "${env:VAULT_TOKEN}"
           - endpoint: https://vault-public.example.com:8200/v1
             no_token: true
   ```

   The default `vault` integration continues to use autodiscovery. The
   `vault/external` key defines a second integration instance that scrapes only the
   listed targets.

### Validate

To validate the HashiCorp Vault integration, follow these steps:

1. In Live Telemetry Analyzer, filter for
   `__name__=cxdot.integration.target.health` and
   `cxdot.integration.name=vault`. Confirm that each expected target reports `1`.
   A value of `1` means that the Vault API health and leadership requests succeeded.
   A value of `0` means that they failed. Use the `server.address` and `server.port`
   attributes to identify each target.

2. In Metrics Explorer, run the following query while Vault handles requests:

   ```text theme={null}
   count by ("server.address", "server.port", "vault.cluster", "vault.version", "vault.is_leader") ({"vault.core.in_flight_requests"})
   ```

   Confirm that the query returns the expected time series for each target. The
   `vault.cluster`, `vault.version`, and `vault.is_leader` attributes identify the
   Vault cluster, version, and leadership state.

### Troubleshooting

* `cxdot.integration.target.health` reports `1`, but workload metrics don't appear:
  Confirm that the token has `read` and `list` access to `sys/metrics`, or that the
  target enables unauthenticated metrics access and uses `no_token: true`.
* A disaster recovery secondary reports API status metrics but no workload metrics:
  Set `collect_secondary_dr: true` for that target. The integration omits workload
  metrics from disaster recovery secondaries by default.

## Configuration reference

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

### Optional settings

* **`enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this Vault integration instance. If true, the Collector collects metrics
  from configured or discovered targets. If false, the Collector doesn't run this integration
  instance.

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

* **`timeout`**
  Type: `duration`. Optional. Default: `10s`.
  Maximum time the Collector waits for a Vault target to respond during one collection. This
  value must not exceed `collection_interval`. If the deadline expires, that collection fails.

* **`max_samples`**
  Type: `integer`. Optional. Default: `0`. Minimum: `0`.
  Maximum samples accepted from one metrics response. Zero disables the sample-count limit.
  Decompressed responses larger than 16 MiB are always rejected.

* **`follow_redirects`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to follow HTTP redirects. If true, the Collector follows redirects. If false, a
  redirect causes the metric collection to fail.

* **`instances`**
  Type: `array of object`. Optional. Default: `[]`.
  Static Vault API targets used outside annotation discovery.

* **`instances[].endpoint`**
  Type: `uri`. Required.
  Base Vault API URL ending in /v1.

* **`instances[].client_token`**
  Type: `string`. Optional.
  Token with read and list access to the metrics endpoint.

* **`instances[].client_token_path`**
  Type: `string`. Optional.
  Collector-local path containing a Vault token.

* **`instances[].no_token`**
  Type: `boolean`. Optional. Default: `false`.
  Scrape metrics without a token when unauthenticated access is enabled.

* **`instances[].collect_secondary_dr`**
  Type: `boolean`. Optional. Default: `false`.
  Collect metrics when the target reports that it's a disaster-recovery secondary.

* **`instances[].tls`**
  Type: `object`. Optional.
  TLS settings for this target.

* **`instances[].tls.ca_file`**
  Type: `string`. Optional.
  Path to a PEM-encoded certificate authority (CA) certificate file used to verify the Vault
  server certificate. If omitted, the Collector uses the system certificate authority pool.

* **`instances[].tls.ca_pem`**
  Type: `string`. Optional.
  PEM-encoded certificate authority certificate content used to verify the Vault server
  certificate.

* **`instances[].tls.cert_file`**
  Type: `string`. Optional.
  Path to the PEM-encoded client certificate file to present when the Vault target requires
  mutual TLS authentication.

* **`instances[].tls.cert_pem`**
  Type: `string`. Optional.
  PEM-encoded client certificate content to present when the Vault target requires mutual TLS
  authentication.

* **`instances[].tls.cipher_suites`**
  Type: `array of string`. Optional.
  TLS cipher suites that the Collector can use, in preference order. If omitted, the Collector
  uses the secure defaults from the Go TLS library. For supported names, see
  [https://go.dev/src/crypto/tls/cipher\_suites.go](https://go.dev/src/crypto/tls/cipher_suites.go).

* **`instances[].tls.curve_preferences`**
  Type: `array of string`. Optional.
  Elliptic curves that the Collector can use for an elliptic curve Diffie-Hellman ephemeral
  handshake, in preference order. If omitted, the Collector uses the Go TLS library defaults.

* **`instances[].tls.include_system_ca_certs_pool`**
  Type: `boolean`. Optional.
  Whether to add certificates from the system certificate authority pool to the configured
  certificate authorities. If true, the Collector trusts both sources. If false, the Collector
  trusts only the configured certificate authorities.

* **`instances[].tls.insecure`**
  Type: `boolean`. Optional.
  Whether to disable transport security. If true, the Collector uses an unencrypted connection.
  If false, the Collector uses TLS.

* **`instances[].tls.insecure_skip_verify`**
  Type: `boolean`. Optional.
  Whether to skip verification of the Vault server certificate. If true, the connection is
  encrypted but isn't authenticated and is vulnerable to man-in-the-middle attacks. If false,
  the Collector verifies the certificate.

* **`instances[].tls.key_file`**
  Type: `string`. Optional.
  Path to the PEM-encoded client private key file used with `cert_file` for mutual TLS
  authentication.

* **`instances[].tls.key_pem`**
  Type: `string`. Optional.
  PEM-encoded client private key content used with `cert_pem` for mutual TLS authentication.

* **`instances[].tls.max_version`**
  Type: `string`. Optional.
  Maximum TLS protocol version the Collector can use. If omitted, the Collector uses the maximum
  version supported by the Go TLS library.

* **`instances[].tls.min_version`**
  Type: `string`. Optional.
  Minimum TLS protocol version the Collector can use. If omitted, the minimum version is TLS
  1.2.

* **`instances[].tls.reload_interval`**
  Type: `duration`. Optional.
  How often the Collector reloads certificate and key files. If omitted, the Collector doesn't
  reload the files.

* **`instances[].tls.server_name_override`**
  Type: `string`. Optional.
  Server name to verify in the Vault certificate instead of the endpoint hostname. Use this
  setting when the certificate name differs from the endpoint hostname.

* **`instances[].tls.tpm`**
  Type: `object`. Optional.
  Trusted platform module settings for the TLS private key.

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

* **`instances[].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.

* **`instances[].tls.tpm.owner_auth`**
  Type: `string`. Optional.
  Authorization value for the trusted platform module owner.

* **`instances[].tls.tpm.path`**
  Type: `string`. Optional.
  Path to the trusted platform module device or Unix domain socket, such as `/dev/tpm0` or
  `/dev/tpmrm0`.


## Related topics

- [CXDOT Collector integrations](/ingest/xcor/integrations/collector.md)
- [HTTP API collector source plugin](/ingest/pipeline/plugins/source-plugins/http-collector.md)
- [Install the Cortex XCOR Terraform provider](/tooling/infrastructure/terraform/install.md)
- [Consul](/ingest/xcor/integrations/collector/consul.md)
- [Terraform provider release notes](/tooling/infrastructure/terraform/release-notes.md)


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