Services

    Complete the Getting Started tutorials to get hands-on experience registering a simple service with a health check on your local machine.

    Configure a service by providing the service definition to the agent. You can either specify the configuration file using the -config-file option, or specify the directory containing the service definition file with the -config-dir option. Consul can load service definitions saved as .json or .hcl files.

    Send a SIGHUP to the running agent or use to check for new service definitions or to update existing services. Alternatively, the service can be registered dynamically using the .

    A service definition contains a set of parameters that specify various aspects of the service, including how it is discovered by other services in the network. All possible parameters are included in the following example, but only the top-level service parameter and its name parameter child are required by default.

    Service Definition

    Service Definition

    HCL

    • HCL
    • JSON
    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. }
    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.       "transparent_proxy": {
    38.         "outbound_listener_port": 22500
    39.       },
    40.       "config": {},
    41.       "upstreams": [],
    42.       "mesh_gateway": {
    43.         "mode": "local"
    44.       },
    45.       "expose": {
    46.         "checks": true,
    47.         "paths": [
    48.           {
    49.             "path": "/healthz",
    50.             "local_path_port": 8080,
    51.             "listener_port": 21500,
    52.             "protocol": "http2"
    53.           }
    54.        ]
    55.       }
    56.     },
    57.     "connect": {
    58.       "native": false,
    59.       "sidecar_service": {}
    60.       "proxy": {  // Deprecated
    61.         "command": [],
    62.         "config": {}
    63.       }
    64.     },
    65.     "weights": {
    66.       "passing": 5,
    67.       "warning": 1
    68.     },
    69.     "token": "233b604b-b92e-48c8-a253-5f11514e4b50",
    71.   }
    72. }

    The following table describes the available parameters for service definitions.

    This is the root-level parameter that defines the service. You can specify the parameters to configure the service.

    Adding Meta Data

    You can add semantic meta data to the service using the meta parameter. This parameter defines a map of max 64 key/value pairs. You can specify the following parameters to define meta data for the service.

    ParameterDescriptionDefaultRequired
    KEYString value that adds semantic metadata to the service.
    Keys can only have 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.    		NoneOptional

    Security Configurations

    If the ACL system is enabled, specify a value for the token parameter to provide an ACL token. This token is used for any interaction with the catalog for the service, including anti-entropy syncs and deregistration.

    Services registered in Consul clusters where both

    Enterprise

    and the ACL system are enabled can be registered to specific namespaces that are associated with ACL tokens scoped to the namespace. Services registered with a service definition will not inherit the namespace associated with the ACL token specified in the token field. The namespace and the 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.

    You can add health checks to your service definition. 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. The health check functionality is strongly integrated into the DNS interface, as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that node from any service query.

    The health check name is automatically generated as service:<service-id>. If there are multiple service checks registered, the ID will be generated as service:<service-id>:<num> where <num> is an incrementing number starting from 1.

    Consul includes several check types with different options. Refer to the health checks documentation for details.

    Proxy

    Service definitions allow for an optional proxy registration. Proxies used with Connect are registered as services in Consul’s catalog. See the Proxy Service Registration reference for the available configuration options.

    Connect

    The kind parameter determines the service’s role. Services can be configured to perform several roles, but you must omit the kind parameter for typical non-proxy instances.

    The following roles are supported for service entries:

    In the service definition example described above, the service is registered as a proxy because the kind property is set to connect-proxy. The proxy parameter is also required for Connect proxy registrations and is only valid if kind is connect-proxy. Refer to the documentation for details about this type.

    When the kind parameter is set to connect-proxy, the only required parameter for the proxy configuration is destination_service_name. Refer to the complete proxy configuration example for additional information.

    The connect field can be specified to configure for a service. This field is available in Consul 1.2.0 and later. The following parameters are available.

    Non-service registration roles: The kind values supported for configuration entries are different than what is supported for service registrations. Refer to the Configuration Entries documentation for information about non-service registration types.

    Deprecated parameters

    ParameterDescriptionConsul versionStatus
    proxy_destinationSpecified the proxy destination in the root level of the definition file.1.2.0 to 1.3.0Deprecated since 1.5.0.
    Use proxy.destination_service_name instead.
    connect.proxySpecified “managed” proxies, which have been deprecated.1.2.0 (beta) to 1.3.0 (beta)Deprecated.

    You can configure how the service responds to DNS SRV requests by specifying a set of states/weights in the weights field.

    weights

    When DNS SRV requests are made, the response will include the weights specified for the given state of the service. This allows some instances to be given higher weight if they have more capacity. It also allows load reduction on services with checks in warning status by giving passing instances a higher weight.

    If a service is critical, it is excluded from DNS responses. Services with warning checks are included in responses by default, but excluded if the optional param only_passing = true is present in the agent DNS configuration or the passing query parameter is used via the API.

    Enable Tag Override and Anti-Entropy

    Services may also contain a token field to provide an ACL token. This token is used for any interaction with the catalog for the service, including and deregistration.

    You can optionally disable the anti-entropy feature for this service using the enable_tag_override flag. External agents can modify tags on services in the catalog, so subsequent sync operations can either maintain tag modifications or revert them. If enable_tag_override is set to TRUE, the next sync cycle may revert some service properties, but the tags would maintain the updated value. If enable_tag_override is set to FALSE, the next sync cycle will revert any updated service properties, including tags, to their original value.

    It’s important to note that this applies only to the locally registered service. If you have multiple nodes all registering the same service their enable_tag_override configuration and all other service configuration items are independent of one another. Updating the tags for the service registered on one node is independent of the same service (by name) registered on another node. If enable_tag_override is not specified the default value is false. See anti-entropy syncs for more info.

    For Consul 0.9.3 and earlier you need to use enableTagOverride. Consul 1.0 supports both enable_tag_override and enableTagOverride but the latter is deprecated and has been removed as of Consul 1.1.

    Tagged Addresses

    Tagged addresses are additional addresses that may be defined for a node or service. Tagged addresses can be used by remote agents and services as alternative addresses for communicating with the given node or service. Multiple tagged addresses may be configured on a node or service.

    The following example describes the syntax for defining a tagged address.

    Tagged address format

    Tagged address format

    HCL

    Register Services - Service Definitions - 图2

    • HCL
    • JSON
    1. service {
    2.   name = "redis"
    3.   port = 80
    4.   tagged_addresses {
    5.     <tag> = {
    6.       address = "<address>"
    7.       port = port
    8.     }
    9.   }
    10. }
    1. service {
    2.   name = "redis"
    3.   port = 80
    4.   tagged_addresses {
    5.     <tag> = {
    6.       address = "<address>"
    7.       port = port
    8.     }
    9.   }
    10. }
    1. {
    2.   "service": {
    3.     "name": "redis",
    4.     "port": 80,
    5.     "tagged_addresses": {
    6.       "<tag>": {
    7.         "address": "<address>",
    8.         "port": port
    9.       }
    10.     }
    11.   }
    12. }
    1. {
    2.   "service": {
    3.     "name": "redis",
    4.     "port": 80,
    5.     "tagged_addresses": {
    6.       "<tag>": {
    7.         "address": "<address>",
    8.         "port": port
    9.       }
    10.     }
    11.   }
    12. }

    The following table provides an overview of the various tagged address types supported by Consul.

    TypeDescriptionTags
    LANLAN addresses are intended to be directly accessible only from services within the same Consul data center. See LAN tags for details.lan
    lan_ipv4
    lan_ipv6
    VirtualVirtual tagged addresses are logical address types that can be configured on -enabled services. The virtual address provides a fixed IP address that can be used by downstream services when connecting to an upstream service. See Virtual tags for details.virtual
    WANDefine a WAN address for the service or node when it should be accessed at an alternate address by services in a remote datacenter. See for details.wan
    wan_ipv4
    wan_ipv6

    LAN tags

    • - The IPv4 LAN address at which the node or service is accessible.
    • lan_ipv4 - The IPv4 LAN address at which the node or service is accessible.
    • - The IPv6 LAN address at which the node or service is accessible.

    Example LAN tagged address configuration

    Example LAN tagged address configuration

    HCL

    • HCL
    • JSON

    Register Services - Service Definitions - 图4

    redis-service.hcl

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

    redis-service.json

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

    Virtual tags

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

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

    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 given logical service. Egress connections from the proxy to an upstream service will be destined to the IP address of an individual service instance, not the virtual address of the logical service.

    Use the following address tag to specify the logical address at which the service can be reached by other services in the mesh.

    • - The virtual IP address at which a logical service is reachable.

    Example virtual tagged address configuration

    Example virtual tagged address configuration

    Register Services - Service Definitions - 图6

    • HCL
    • JSON
    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. }

    redis-service.hcl

    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",
    6.     "tagged_addresses": {
    7.       "virtual": {
    8.         "address": "203.0.113.50",
    9.         "port": 80
    10.       }
    11.     }
    12.   }
    13. }

    Register Services - Service Definitions - 图8

    redis-service.json

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

    WAN tags

    One or more of the following address tags can be configured for a node or service to advertise how it should be accessed over the WAN.

    • - The IPv4 WAN address at which the node or service is accessible when being dialed from a remote data center.
    • wan_ipv4 - The IPv4 WAN address at which the node or service is accessible when being dialed from a remote data center.

    Example WAN tagged address configuration

    Example WAN tagged address configuration

    HCL

    • HCL
    • JSON

    Register Services - Service Definitions - 图10

    redis-service.hcl

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

    redis-service.json

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

    Multiple services definitions can be provided at once when registering services via the agent configuration by using the plural services key (registering multiple services in this manner is not supported using the HTTP API).

    Multiple Service Definitions

    Multiple Service Definitions

    HCL

    Register Services - Service Definitions - 图12

    • HCL
    • JSON
    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. }

    redis-services.hcl

    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.   ]
    38. }

    Register Services - Service Definitions - 图14

    redis-services.json

    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.   ]
    38. }

    Consul exposes service definitions and tags over the interface. DNS queries have a strict set of allowed characters and a well-defined format that Consul cannot override. While it is possible to register services or tags with names that don’t match the conventions, those services and tags will not be discoverable via the DNS interface. It is recommended to always use DNS-compliant service and tag names.

    DNS-compliant service and tag names may contain any alpha-numeric characters, as well as dashes. Dots are not supported because Consul internally uses them to delimit service tags.

    For historical reasons Consul’s API uses CamelCased parameter names in responses, however its configuration file uses snake_case for both HCL and JSON representations. For this reason the registration HTTP APIs accept both name styles for service definition parameters although APIs will return the listings using CamelCase.

    Note though that all config file formats require snake_case fields. We always document service definition examples using and JSON since this format works in both config files and API calls.