Configure Consul service registration

Consul Service Registration registers Vault as a service in Consul with a default health check. When Consul is configured as the storage backend, the stanza service_registration is not needed as it will automatically register Vault as a service.

• HashiCorp Supported – Consul Service Registration is officially supported by HashiCorp.

Configuration

service_registration "consul" {
  address      = "127.0.0.1:8500"
}

If Vault is running in HA mode, include the transfer protocol (http:// or https://) in the address:

service_registration "consul" {
  address      = "http://127.0.0.1:8500"
}

Once properly configured, an unsealed Vault installation should be available and accessible at:

active.vault.service.consul

Unsealed Vault instances in standby mode are available at:

standby.vault.service.consul

All unsealed Vault instances are available as healthy at:

vault.service.consul

Sealed Vault instances will mark themselves as unhealthy to avoid being returned at Consul's service discovery layer.

consul parameters

• address (string: "127.0.0.1:8500") – Specifies the address of the Consul agent to communicate with. This can be an IP address, DNS record, or unix socket. It is recommended that you communicate with a local Consul agent; do not communicate directly with a server.

• check_timeout (string: "5s") – Specifies the check interval used to send health check information back to Consul. This is specified using a label suffix like "30s" or "1h".

• disable_registration (string: "false") – Specifies whether Vault should register itself with Consul.

• scheme (string: "http") – Specifies the scheme to use when communicating with Consul. This can be set to "http" or "https". It is highly recommended you communicate with Consul over https over non-local connections. When communicating over a unix socket, this option is ignored.

• service (string: "vault") – Specifies the name of the service to register in Consul.

• service_tags (string: "") – Specifies a comma-separated list of case-sensitive tags to attach to the service registration in Consul.

• service_meta (map[string]string: {}) – Specifies a key-value list of meta tags to attach to the service registration in Consul. See ServiceMeta in the Consul docs for more information.

• service_address (string: nil) – Specifies a service-specific address to set on the service registration in Consul. If unset, Vault will use what it knows to be the HA redirect address - which is usually desirable. Setting this parameter to "" will tell Consul to leverage the configuration of the node the service is registered on dynamically. This could be beneficial if you intend to leverage Consul's translate_wan_addrs parameter.

• token (string: "") – Specifies the Consul ACL token with permission to register the Vault service into Consul's service catalog. This is not a Vault token. See the ACL section below for help.

The following settings apply when communicating with Consul via an encrypted connection. You can read more about encrypting Consul connections on the Consul encryption page.

• tls_ca_file (string: "") – Specifies the path to the CA certificate used for Consul communication. This defaults to system bundle if not specified. This should be set according to the ca_file setting in Consul.

• tls_cert_file (string: "") (optional) – Specifies the path to the certificate for Consul communication. This should be set according to the cert_file setting in Consul.

• tls_key_file (string: "") – Specifies the path to the private key for Consul communication. This should be set according to the key_file setting in Consul.

• tls_min_version (string: "tls12") – Specifies the minimum TLS version to use. Accepted values are "tls10", "tls11", "tls12" or "tls13".

• tls_skip_verify (string: "false") – Disable verification of TLS certificates. Using this option is highly discouraged.

ACLs

If using ACLs in Consul, you'll need appropriate permissions to register the Vault service. The following ACL policy will work for most use-cases, assuming that your service name is vault:

{
  "service": {
    "vault": {
      "policy": "write"
    }
  }
}

consul examples

Local agent

This example shows a sample configuration which communicates with a local Consul agent running on 127.0.0.1:8500.

service_registration "consul" {}

Detailed customization

This example shows communicating with Consul on a custom address with an ACL token.

service_registration "consul" {
  address = "10.5.7.92:8194"
  token   = "abcd1234"
}

Consul via unix socket

This example shows communicating with Consul over a local unix socket.

service_registration "consul" {
  address = "unix:///tmp/.consul.http.sock"
}

Custom TLS

This example shows using a custom CA, certificate, and key file to securely communicate with Consul over TLS.

service_registration "consul" {
  scheme        = "https"
  tls_ca_file   = "/etc/pem/vault.ca"
  tls_cert_file = "/etc/pem/vault.cert"
  tls_key_file  = "/etc/pem/vault.key"
}