HashiCorp Vault

The Vault integration requires CXDOT Collector 1.7.0 or greater. HashiCorp 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:

​

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

​

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.
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:
   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:
   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.
• 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.