Services configuration reference

This topic describes the options you can use to define services for registering them with Consul. Refer to the following topics for usage information:

Configuration model

The following outline shows how to format the configurations in the root service block. Click on a property name to view details about the configuration.

Specification

This topic provides details about the configuration parameters.

name

Required value that specifies a name for the service. We recommend using valid DNS labels for service definition names for compatibility with external DNSs. The value for this parameter is used as the ID if the id parameter is not specified.

  • Type: string
  • Default: none

id

Specifies an ID for the service. Services on the same node must have unique IDs. We recommend specifying unique values if the default name conflicts with other services.

  • Type: string
  • Default: Value of the name field.

address

String value that specifies a service-specific IP address or hostname. If no value is specified, the IP address of the agent node is used by default. There is no service-side validation of this parameter.

  • Type: string
  • Default: IP address of the agent node

port

Specifies a port number for the service. To improve service discoverability, we recommend specifying the port number, as well as an address in the tagged_addresses parameter.

  • Type: integer
  • Default: Port number of the agent

tags

Specifies a list of string values that add service-level labels. Tag values are opaque to Consul. We recommend using valid DNS labels for service definition IDs for compatibility with external DNSs. In the following example, the service is tagged as v2 and primary:

  1. tags = ["v2", "primary"]

Consul uses tags as an anti-entropy mechanism to maintain the state of the cluster. You can disable the anti-entropy feature for a service using the enable_tag_override setting, which enables external agents to modify tags on services in the catalog. Refer to Modify anti-entropy synchronization for additional usage information.

meta

The meta field contains custom key-value pairs that associate semantic metadata with the service. You can specify up to 64 pairs that meet the following requirements:

  • Keys and values must be strings.
  • Keys can only contain ASCII characters (A - Z, a- z, 0 - 9, _, and -).
  • Keys can not have special characters.
  • Keys are limited to 128 characters.
  • Values are limited to 512 characters.

In the following example, the env key is set to prod:

  1. meta = {
  2.   env = "prod"
  3. }
  1. "meta" : {
  2.     "env" : "prod"
  3. }

tagged_addresses

The tagged_address field is an object that configures additional addresses for a node or service. Remote agents and services can communicate with the service using a tagged address as an alternative to the address specified in the address field. You can configure multiple addresses for a node or service. The following tags are supported:

  • lan: IPv4 LAN address where the node or service is accessible.
  • lan_ipv4: IPv4 LAN address where the node or service is accessible.
  • lan_ipv6: IPv6 LAN address where the node or service is accessible.
  • virtual: A fixed address for the instances of a given logical service.
  • wan: IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
  • wan_ipv4: IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
  • wan_ipv6: IPv6 WAN address at which the node or service is accessible when being dialed from a remote data center.

tagged_addresses.lan

Object that specifies either an IPv4 or IPv6 LAN address and port number where the service or node is accessible. You can specify one or more of the following fields:

The field contains the following parameters:

In the following example, the redis service has an IPv4 LAN address of 192.0.2.10:80 and IPv6 LAN address of [2001:db8:1:2:cafe::1337]:80:

  1. service {
  2.   name = "redis"
  3.   address = "192.0.2.10"
  4.   port = 80
  5.   tagged_addresses {
  6.     lan = {
  7.       address = "192.0.2.10"
  8.       port = 80
  9.     }
  10.     lan_ipv4 = {
  11.       address = "192.0.2.10"
  12.       port = 80
  13.     }
  14.     lan_ipv6 = {
  15.       address = "2001:db8:1:2:cafe::1337"
  16.       port = 80
  17.     }
  18.   }
  19. }
  1. {
  2.   "service": {
  3.     "name": "redis",
  4.     "address": "192.0.2.10",
  5.     "port": 80,
  6.     "tagged_addresses": {
  7.       "lan": {
  8.         "address": "192.0.2.10",
  9.         "port": 80
  10.       },
  11.       "lan_ipv4": {
  12.         "address": "192.0.2.10",
  13.         "port": 80
  14.       },
  15.       "lan_ipv6": {
  16.         "address": "2001:db8:1:2:cafe::1337",
  17.         "port": 80
  18.       }
  19.     }
  20.   }
  21. }

tagged_addresses.virtual

Object that specifies a fixed IP address and port number that downstream services in a service mesh can use to connect to the service. The virtual field contains the following parameters:

Virtual addresses are not required to be routable IPs within the network. They are strictly a control plane construct used to provide a fixed address for the instances of a logical service. Egress connections from the proxy to an upstream service go to the IP address of an individual service instance and not the virtual address of the logical service.

If the following conditions are met, connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied:

  1. Transparent proxy is enabled for the downstream and upstream services.
  2. The upstream service is not configured for individual instances to be dialed directly.

In the following example, the downstream services in the mesh can connect to the redis service at 203.0.113.50 on port 80:

  1. service {
  2.   name = "redis"
  3.   address = "192.0.2.10"
  4.   port = 80
  5.   tagged_addresses {
  6.     virtual = {
  7.       address = "203.0.113.50"
  8.       port = 80
  9.     }
  10.   }
  11. }
  1. {
  2.   "service": {
  3.     "name": "redis",
  4.     "address": "192.0.2.10",
  5.     "port": 80,
  6.     "tagged_addresses": {
  7.       "virtual": {
  8.         "address": "203.0.113.50",
  9.         "port": 80
  10.       }
  11.     }
  12.   }
  13. }

tagged_addresses.wan

Object that specifies either an IPv4 or IPv6 WAN address and port number where the service or node is accessible from a remote datacenter. You can specify one or more of the following fields:

The field contains the following parameters:

In the following example, services or nodes in remote datacenters can reach the redis service at 198.51.100.200:80 and [2001:db8:5:6:1337::1eaf]:80:

  1. service {
  2.   name = "redis"
  3.   address = "192.0.2.10"
  4.   port = 80
  5.   tagged_addresses {
  6.     wan = {
  7.       address = "198.51.100.200"
  8.       port = 80
  9.     }
  10.     wan_ipv4 = {
  11.       address = "198.51.100.200"
  12.       port = 80
  13.     }
  14.     wan_ipv6 = {
  15.       address = "2001:db8:5:6:1337::1eaf"
  16.       port = 80
  17.     }
  18.   }
  19. }
  1. {
  2.   "service": {
  3.     "name": "redis",
  4.     "address": "192.0.2.10",
  5.     "port": 80,
  6.     "tagged_addresses": {
  7.       "wan": {
  8.         "address": "198.51.100.200",
  9.         "port": 80
  10.       },
  11.       "wan_ipv4": {
  12.         "address": "198.51.100.200",
  13.         "port": 80
  14.       },
  15.       "wan_ipv6": {
  16.         "address": "2001:db8:5:6:1337::1eaf",
  17.         "port": 80
  18.       }
  19.     }
  20.   }
  21. }

socket_path

String value that specifies the path to the service socket. Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket.

  • Type: string
  • Default: none

enable_tag_override

Boolean value that determines if the anti-entropy feature for the service is enabled. Set to true to allow external Consul agents modify tags on the services in the Consul catalog. The local Consul agent ignores updated tags during subsequent sync operations.

This parameter only applies to the locally-registered service. If multiple nodes register a service with the same name, the enable_tag_override configuration, and all other service configuration items, operate independently.

Refer to Modify anti-entropy synchronization for additional usage information.

  • Type: boolean
  • Default: false

checks

The checks block contains an array of objects that define health checks for the service. Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. Refer to Health Check Configuration Reference for information about configuring health checks.

kind

String value that identifies the service as a proxy and determines its role in the service mesh. Do not configure the kind parameter for non-proxy service instances. Refer to Consul Service Mesh for additional information.

You can specify the following values:

For non-service registration roles, the kind field has a different context when used to define configuration entries, such as service-defaults. Refer to the documentation for the configuration entry you want to implement for additional information.

proxy

Object that specifies proxy configurations when the service is configured to operate as a proxy in a service mesh. Do not configure the proxy parameter for non-proxy service instances. Refer to Register a Service Mesh Proxy Outside of a Service Registration for details about registering your service as a service mesh proxy. Refer to kind for information about the types of proxies you can define. Services that you assign proxy roles to are registered as services in the catalog.

connect

Object that configures a Consul service mesh connection. You should only configure the connect block of parameters if you are using Consul service mesh. Refer to Consul Service Mesh for additional information.

The following table describes the parameters that you can place in the connect block:

ParameterDescriptionDefault
nativeBoolean value that advertises the service as a native service mesh proxy. Use this parameter to integrate your application with the connect API. Refer to Service Mesh Native App Integration Overview for additional information. If set to true, do not configure a sidecar_service.false
sidecar_serviceObject that defines a sidecar proxy for the service. Do not configure if native is set to true. Refer to Register a Service Mesh Proxy in a Service Registration for usage and configuration details.Refer to Register a Service Mesh Proxy in a Service Registration for default configurations.

weights

Object that configures how the service responds to DNS SRV requests based on the service’s health status. Configuring allows service instances with more capacity to respond to DNS SRV requests. It also reduces the load on services with checks in warning status by giving passing instances a higher weight.

You can specify one or more of the following states and configure an integer value indicating its weight:

Larger integer values increase the weight state. Services have the following default weights:

Services in a critical state are excluded from DNS responses by default. Services with warning checks are included in responses by default. Refer to Perform Static DNS Queries for additional information.

In the following example, service instances in a passing state respond to DNS SRV requests, while instances in a critical instance can still respond at a lower frequency:

  1. service {
  2.   ## ...
  3.   weights = {
  4.     passing = 3
  5.     warning = 2
  6.     critical   = 1
  7.   }
  8.   ## ...
  9. }
  1. "service": {
  2.   ## ...
  3.   "weights": {
  4.     "passing": 3,
  5.     "warning": 2,
  6.     "critical": 1
  7.   },
  8.   ## ...
  9. }

token

String value that specifies the ACL token to present when registering the service if ACLs are enabled. The token is required for the service to interact with the service catalog.

If ACLs and namespaces are enabled, you can register services scoped to the specific namespace associated with the ACL token in a Consul cluster.

Services registered with a service definition do not inherit the namespace associated with the ACL token specified in the token field. The namespace and token parameters must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to.

  • Type: string
  • Default: none

namespace

String value that specifies the namespace in which to register the service. Refer Namespaces for additional information.

  • Type: string
  • Default: none

Multiple service definitions

You can define multiple services in a single definition file in the servcies block. This enables you register multiple services in a single command. Note that the HTTP API does not support the services block.

  1. services {
  2.   id = "red0"
  3.   name = "redis"
  4.   tags = [
  5.     "primary"
  6.   ]
  7.   address = ""
  8.   port = 6000
  9.   checks = [
  10.     {
  11.       args = ["/bin/check_redis", "-p", "6000"]
  12.       interval = "5s"
  13.       timeout = "20s"
  14.     }
  15.   ]
  16. }
  17. services {
  18.   id = "red1"
  19.   name = "redis"
  20.   tags = [
  21.     "delayed",
  22.     "secondary"
  23.   ]
  24.   address = ""
  25.   port = 7000
  26.   checks = [
  27.     {
  28.       args = ["/bin/check_redis", "-p", "7000"]
  29.       interval = "30s"
  30.       timeout = "60s"
  31.     }
  32.   ]
  33. }
  1. {
  2.   "services": [
  3.     {
  4.       "id": "red0",
  5.       "name": "redis",
  6.       "tags": [
  7.         "primary"
  8.       ],
  9.       "address": "",
  10.       "port": 6000,
  11.       "checks": [
  12.         {
  13.           "args": ["/bin/check_redis", "-p", "6000"],
  14.           "interval": "5s",
  15.           "timeout": "20s"
  16.         }
  17.       ]
  18.     },
  19.     {
  20.       "id": "red1",
  21.       "name": "redis",
  22.       "tags": [
  23.         "delayed",
  24.         "secondary"
  25.       ],
  26.       "address": "",
  27.       "port": 7000,
  28.       "checks": [
  29.         {
  30.           "args": ["/bin/check_redis", "-p", "7000"],
  31.           "interval": "30s",
  32.           "timeout": "60s"
  33.         }
  34.       ]
  35.     }
  36.   ]
  37. }

Example definition

The following example includes all possible parameters, but only the top-level service parameter and its name parameter are required by default.

  1. service {
  2.   name = "redis"
  3.   id   = "redis"
  4.   port = 80
  5.   tags = ["primary"]
  7.   meta = {
  8.     custom_meta_key = "custom_meta_value"
  9.   }
  11.   tagged_addresses = {
  12.     lan = {
  13.       address = "192.168.0.55"
  14.       port    = 8000
  15.     }
  17.     wan = {
  18.       address = "198.18.0.23"
  19.       port    = 80
  20.     }
  21.   }
  23.   port                = 8000
  24.   socket_path         = "/tmp/redis.sock"
  25.   enable_tag_override = false
  27.   checks = [
  28.     {
  29.       args     = ["/usr/local/bin/check_redis.py"]
  30.       interval = "10s"
  31.     }
  32.   ]
  34.   kind              = "connect-proxy"
  35.   proxy_destination = "redis"
  37.   proxy = {
  38.     destination_service_name  = "redis"
  39.     destination_service_id    = "redis1"
  40.     local_service_address     = "127.0.0.1"
  41.     local_service_port        = 9090
  42.     local_service_socket_path = "/tmp/redis.sock"
  43.     mode                      = "transparent"
  45.     transparent_proxy {
  46.       outbound_listener_port = 22500
  47.     }
  49.     mesh_gateway = {
  50.       mode = "local"
  51.     }
  53.     expose = {
  54.       checks = true
  56.       paths = [
  57.         {
  58.           path            = "/healthz"
  59.           local_path_port = 8080
  60.           listener_port   = 21500
  61.           protocol        = "http2"
  62.         }
  63.       ]
  64.     }
  65.   }
  67.   connect = {
  68.     native = false
  69.   }
  71.   weights = {
  72.     passing = 5
  73.     warning = 1
  74.   }
  76.   token     = "233b604b-b92e-48c8-a253-5f11514e4b50"
  77.   namespace = "foo"
  78. }
  1. {
  2.   "service": {
  3.     "id": "redis",
  4.     "name": "redis",
  5.     "tags": ["primary"],
  6.     "address": "",
  7.     "meta": {
  8.       "meta": "for my service"
  9.     },
  10.     "tagged_addresses": {
  11.       "lan": {
  12.         "address": "192.168.0.55",
  13.         "port": 8000,
  14.       },
  15.       "wan": {
  16.         "address": "198.18.0.23",
  17.         "port": 80
  18.       }
  19.     },
  20.     "port": 8000,
  21.     "socket_path": "/tmp/redis.sock",
  22.     "enable_tag_override": false,
  23.     "checks": [
  24.       {
  25.         "args": ["/usr/local/bin/check_redis.py"],
  26.         "interval": "10s"
  27.       }
  28.     ],
  29.     "kind": "connect-proxy",
  30.     "proxy_destination": "redis", // Deprecated
  31.     "proxy": {
  32.       "destination_service_name": "redis",
  33.       "destination_service_id": "redis1",
  34.       "local_service_address": "127.0.0.1",
  35.       "local_service_port": 9090,
  36.       "local_service_socket_path": "/tmp/redis.sock",
  37.       "mode": "transparent",
  38.       "transparent_proxy": {
  39.         "outbound_listener_port": 22500
  40.       },
  41.       "config": {},
  42.       "upstreams": [],
  43.       "mesh_gateway": {
  44.         "mode": "local"
  45.       },
  46.       "expose": {
  47.         "checks": true,
  48.         "paths": [
  49.           {
  50.             "path": "/healthz",
  51.             "local_path_port": 8080,
  52.             "listener_port": 21500,
  53.             "protocol": "http2"
  54.           }
  55.        ]
  56.       }
  57.     },
  58.     "connect": {
  59.       "native": false,
  60.       "sidecar_service": {}
  61.       "proxy": {  // Deprecated
  62.         "command": [],
  63.         "config": {}
  64.       }
  65.     },
  66.     "weights": {
  67.       "passing": 5,
  68.       "warning": 1
  69.     },
  70.     "token": "233b604b-b92e-48c8-a253-5f11514e4b50",
  71.     "namespace": "foo"
  72.   }
  73. }