Global registry parameters for Consul agent configuration

This page provides reference information for the global_registry block in a Consul agent configuration file. Use this block to configure how Consul servers send cluster data to the global registry in Consul Operations Hub.

Configure the block on your server agents. The leader sends snapshots and updates to the registry. Global registry synchronization is disabled by default.

To install Operations Hub and obtain the cluster ID and ingestion token, refer to Install and set up Consul Operations Hub.

You can reload these settings without restarting the server. Refer to Reloadable configurations for details.

Configuration model

The following list outlines the fields and their data types in HCL and JSON. When you enable synchronization, you must provide an address, a cluster ID, and a token source.

• global_registry: object
  • enabled: boolean | default: false
  • address: string | default: "" | required when enabled
  • cluster_id: string | default: "" | required when enabled
  • token: string | default: ""
  • token_file: string | default: ""
  • ca_file: string | default: ""
  • tls_skip_verify: boolean | default: false
  • snapshot_interval: integer, in nanoseconds | default: 600000000000 (10 minutes)
  • delta_flush_interval: integer, in nanoseconds | default: 120000000000 (2 minutes)

Complete configuration

The following examples show all fields in the global_registry block and set the snapshot interval to 3 minutes and the delta flush interval to 15 seconds. Replace the address and cluster ID with values for your deployment. The HCL example reads the token from a file. The JSON example uses an inline token.

global_registry {
  enabled              = true
  address              = "https://REGISTRY_HOST:REGISTRY_PORT"
  cluster_id           = "CLUSTER_UUID"
  token                = ""
  token_file           = "/PATH/TO/token.txt"
  ca_file              = "/PATH/TO/ca.pem"
  tls_skip_verify      = false
  snapshot_interval    = 180000000000
  delta_flush_interval = 15000000000
}

{
  "global_registry": {
    "enabled": true,
    "address": "https://REGISTRY_HOST:REGISTRY_PORT",
    "cluster_id": "CLUSTER_UUID",
    "token": "GLOBAL_REGISTRY_TOKEN",
    "token_file": "",
    "ca_file": "/PATH/TO/ca.pem",
    "tls_skip_verify": false,
    "snapshot_interval": 180000000000,
    "delta_flush_interval": 15000000000
  }
}

Omit ca_file when the registry certificate uses a certificate authority trusted by the system. Use HTTPS and leave tls_skip_verify set to false in production.

Specification

This section describes the fields you can configure in the global_registry block.

global_registry

Configures the connection, authentication, and synchronization settings for the global registry in Consul Operations Hub.

Values

• Data type: object

global_registry.enabled

Enables synchronization with the global registry. When you set this field to true, Consul requires a non-empty address, a valid cluster_id, and a token source.

Values

• Default: false
• Data type: boolean

global_registry.address

Specifies the base URL of the global registry, including the scheme and port when needed. For example, use https://REGISTRY_HOST:REGISTRY_PORT. Consul appends /api/v1/registry/ingest when sending data, so do not include that path or a trailing slash in the address.

Values

• Default: ""
• Required when enabled is true.
• Data type: string

global_registry.cluster_id

Specifies the cluster identifier Consul sends to the global registry. Provide the universally unique identifier (UUID) for your cluster. Consul rejects an empty or invalid UUID when synchronization is enabled.

Values

• Default: ""
• Required when enabled is true.
• Data type: string

global_registry.token

Specifies an inline bearer token for authenticating requests to the global registry. You can also supply the token with the CONSUL_GLOBAL_REGISTRY_TOKEN environment variable.

Consul selects the first non-empty token source in the following order:

1. The CONSUL_GLOBAL_REGISTRY_TOKEN environment variable.
2. The token configuration field.
3. The file specified by the CONSUL_GLOBAL_REGISTRY_TOKEN_FILE environment variable.
4. The file specified by the token_file configuration field.

Consul trims whitespace from token values. You must provide at least one token source when synchronization is enabled.

Values

• Default: ""
• Data type: string

global_registry.token_file

Specifies the path to a file containing the bearer token. Consul uses this file only when neither CONSUL_GLOBAL_REGISTRY_TOKEN nor token provides a non-empty token. The CONSUL_GLOBAL_REGISTRY_TOKEN_FILE environment variable overrides this path.

The effective token file must be readable by the Consul process and contain a non-empty token after Consul trims whitespace. Consul reads the file for each request, so you can rotate its contents without restarting the server.

Values

• Default: ""
• Data type: string

global_registry.ca_file

Specifies the path to a PEM-encoded certificate authority (CA) certificate file used to verify the registry's Transport Layer Security (TLS) certificate. When you omit this field, Consul uses the system's trusted CA certificates.

When you specify a file, Consul uses the CA certificates in that file instead of the system trust store. The file must be readable and contain valid PEM-encoded CA certificates. Consul reads the file when the server starts and when a reload changes the global_registry configuration. To use updated CA certificates at the same path, restart the server agent.

Values

• Default: ""
• Data type: string

global_registry.tls_skip_verify

Disables verification of the registry's TLS certificate and hostname when set to true.

Values

• Default: false
• Data type: boolean

global_registry.snapshot_interval

Specifies the interval between full cluster snapshots sent to the global registry. Use delta_flush_interval to configure the interval for flushing buffered incremental updates.

Specify a positive integer in nanoseconds. For example, 180000000000 represents 3 minutes. Consul does not accept string values such as "3min" or "3m" for this field. Omitting the field or setting it to 0 selects the 10-minute default.

Values

• Default: 600000000000 (10 minutes)
• Data type: integer, in nanoseconds

global_registry.delta_flush_interval

Specifies the interval for flushing buffered incremental updates to the global registry. This setting does not change the full snapshot interval or the separate interval for refreshing live data.

Specify a positive integer in nanoseconds. For example, 15000000000 represents 15 seconds. Consul does not accept duration strings such as "15s" for this field. Omitting the field or setting it to 0 selects the 2-minute default.

Values

• Default: 120000000000 (2 minutes)
• Data type: integer, in nanoseconds