1--- 2layout: "docs" 3page_title: "Service Definition" 4sidebar_current: "docs-agent-services" 5description: |- 6 One of the main goals of service discovery is to provide a catalog of available services. To that end, the agent provides a simple service definition format to declare the availability of a service and to potentially associate it with a health check. A health check is considered to be application level if it is associated with a service. A service is defined in a configuration file or added at runtime over the HTTP interface. 7--- 8 9# Services 10 11One of the main goals of service discovery is to provide a catalog of available 12services. To that end, the agent provides a simple service definition format 13to declare the availability of a service and to potentially associate it with 14a health check. A health check is considered to be application level if it is 15associated with a service. A service is defined in a configuration file 16or added at runtime over the HTTP interface. 17 18## Service Definition 19 20To configure a service, either provide the service definition as a 21`-config-file` option to the agent or place it inside the `-config-dir` of the 22agent. The file must end in the `.json` or `.hcl` extension to be loaded by 23Consul. Check definitions can be updated by sending a `SIGHUP` to the agent. 24Alternatively, the service can be registered dynamically using the [HTTP 25API](/api/index.html). 26 27A service definition is a configuration that looks like the following. This 28example shows all possible fields, but note that only a few are required. 29 30```javascript 31{ 32 "service": { 33 "id": "redis", 34 "name": "redis", 35 "tags": ["primary"], 36 "address": "", 37 "meta": { 38 "meta": "for my service" 39 }, 40 "port": 8000, 41 "enable_tag_override": false, 42 "checks": [ 43 { 44 "args": ["/usr/local/bin/check_redis.py"], 45 "interval": "10s" 46 } 47 ], 48 "kind": "connect-proxy", 49 "proxy_destination": "redis", // Deprecated 50 "proxy": { 51 "destination_service_name": "redis", 52 "destination_service_id": "redis1", 53 "local_service_address": "127.0.0.1", 54 "local_service_port": 9090, 55 "config": {}, 56 "upstreams": [] 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 } 71} 72``` 73 74A service definition must include a `name` and may optionally provide an 75`id`, `tags`, `address`, `meta`, `port`, `enable_tag_override`, and `check`. 76The `id` is set to the `name` if not provided. It is required that all 77services have a unique ID per node, so if names might conflict then 78unique IDs should be provided. 79 80The `tags` property is a list of values that are opaque to Consul but 81can be used to distinguish between `primary` or `secondary` nodes, 82different versions, or any other service level labels. 83 84The `address` field can be used to specify a service-specific IP address. By 85default, the IP address of the agent is used, and this does not need to be provided. 86The `port` field can be used as well to make a service-oriented architecture 87simpler to configure; this way, the address and port of a service can 88be discovered. 89 90The `meta` object is a map of max 64 key/values with string semantics. Key can contain 91only ASCII chars and no special characters (`A-Z` `a-z` `0-9` `_` and `-`). 92For performance and security reasons, values as well as keys are limited to 128 93characters for keys, 512 for values. This object has the same limitations as the node 94meta object in node definition. 95All those meta data can be retrieved individually per instance of the service 96and all the instances of a given service have their own copy of it. 97 98Services may also contain a `token` field to provide an ACL token. This token is 99used for any interaction with the catalog for the service, including 100[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. 101 102The `enable_tag_override` can optionally be specified to disable the 103anti-entropy feature for this service. If `enable_tag_override` is set to 104`TRUE` then external agents can update this service in the 105[catalog](/api/catalog.html) and modify the tags. Subsequent 106local sync operations by this agent will ignore the updated tags. For 107example, if an external agent modified both the tags and the port for 108this service and `enable_tag_override` was set to `TRUE` then after the next 109sync cycle the service's port would revert to the original value but the 110tags would maintain the updated value. As a counter example: If an 111external agent modified both the tags and port for this service and 112`enable_tag_override` was set to `FALSE` then after the next sync cycle the 113service's port *and* the tags would revert to the original value and all 114modifications would be lost. 115 116It's important to note that this applies only to the locally registered 117service. If you have multiple nodes all registering the same service 118their `enable_tag_override` configuration and all other service 119configuration items are independent of one another. Updating the tags 120for the service registered on one node is independent of the same 121service (by name) registered on another node. If `enable_tag_override` is 122not specified the default value is false. See [anti-entropy 123syncs](/docs/internals/anti-entropy.html) for more info. 124 125For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0 126supports both `enable_tag_override` and `enableTagOverride` but the latter is 127deprecated and has been removed as of Consul 1.1. 128 129### Connect 130 131The `kind` field is used to optionally identify the service as a [Connect 132proxy](/docs/connect/proxies.html) instance with the value `connect-proxy`. For 133typical non-proxy instances the `kind` field must be omitted. The `proxy` field 134is also required for Connect proxy registrations and is only valid if `kind` is 135`connect-proxy`. The only required `proxy` field is `destination_service_name`. 136For more detail please see [complete proxy configuration 137example](/docs/connect/proxies.html#complete-configuration-example) 138 139-> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was 140specified using `proxy_destination` at the top level. This will continue to work 141until at least 1.5.0 but it's highly recommended to switch to using 142`proxy.destination_service_name`. 143 144The `connect` field can be specified to configure 145[Connect](/docs/connect/index.html) for a service. This field is available in 146Consul 1.2.0 and later. The `native` value can be set to true to advertise the 147service as [Connect-native](/docs/connect/native.html). The `sidecar_service` 148field is an optional nested service definition its behavior and defaults are 149described in [Sidecar Service 150Registration](/docs/connect/proxies/sidecar-service.html). If `native` is true, 151it is an error to also specify a sidecar service registration. 152 153-> **Deprecation Notice:** From version 1.2.0 to 1.3.0 during beta, Connect 154supported "Managed" proxies which are specified with the `connect.proxy` field. 155[Managed Proxies are deprecated](/docs/connect/proxies/managed-deprecated.html) 156and the `connect.proxy` field will be removed in a future major release. 157 158### Checks 159 160A service can have an associated health check. This is a powerful feature as 161it allows a web balancer to gracefully remove failing nodes, a database 162to replace a failed secondary, etc. The health check is strongly integrated in 163the DNS interface as well. If a service is failing its health check or a 164node has any failing system-level check, the DNS interface will omit that 165node from any service query. 166 167There are several check types that have differing required options as 168[documented here](/docs/agent/checks.html). The check name is automatically 169generated as `service:<service-id>`. If there are multiple service checks 170registered, the ID will be generated as `service:<service-id>:<num>` where 171`<num>` is an incrementing number starting from `1`. 172 173-> **Note:** There is more information about [checks here](/docs/agent/checks.html). 174 175### DNS SRV Weights 176 177The `weights` field is an optional field to specify the weight of a service in 178DNS SRV responses. If this field is not specified, its default value is: 179`"weights": {"passing": 1, "warning": 1}`. When a service is `critical`, it is 180excluded from DNS responses. Services with warning checks are included in 181responses by default, but excluded if the optional param `only_passing = true` 182is present in agent DNS configuration or `?passing` is used via the API. 183 184When DNS SRV requests are made, the response will include the weights specified 185given the state of the service. This allows some instances to be given higher 186weight if they have more capacity, and optionally allows reducing load on 187services with checks in `warning` status by giving passing instances a higher 188weight. 189 190### Enable Tag Override and Anti-Entropy 191 192Services may also contain a `token` field to provide an ACL token. This token is 193used for any interaction with the catalog for the service, including 194[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. 195 196You can optionally disable the anti-entropy feature for this service using the 197`enable_tag_override` flag. External agents can modify tags on services in the 198catalog, so subsequent sync operations can either maintain tag modifications or 199revert them. If `enable_tag_override` is set to `TRUE`, the next sync cycle may 200revert some service properties, **but** the tags would maintain the updated value. 201If `enable_tag_override` is set to `FALSE`, the next sync cycle will revert any 202updated service properties, **including** tags, to their original value. 203 204It's important to note that this applies only to the locally registered 205service. If you have multiple nodes all registering the same service 206their `enable_tag_override` configuration and all other service 207configuration items are independent of one another. Updating the tags 208for the service registered on one node is independent of the same 209service (by name) registered on another node. If `enable_tag_override` is 210not specified the default value is false. See [anti-entropy 211syncs](/docs/internals/anti-entropy.html) for more info. 212 213For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0 214supports both `enable_tag_override` and `enableTagOverride` but the latter is 215deprecated and has been removed as of Consul 1.1. 216 217## Multiple Service Definitions 218 219Multiple services definitions can be provided at once using the plural 220`services` key in your configuration file. 221 222```javascript 223{ 224 "services": [ 225 { 226 "id": "red0", 227 "name": "redis", 228 "tags": [ 229 "primary" 230 ], 231 "address": "", 232 "port": 6000, 233 "checks": [ 234 { 235 "args": ["/bin/check_redis", "-p", "6000"], 236 "interval": "5s", 237 "ttl": "20s" 238 } 239 ] 240 }, 241 { 242 "id": "red1", 243 "name": "redis", 244 "tags": [ 245 "delayed", 246 "secondary" 247 ], 248 "address": "", 249 "port": 7000, 250 "checks": [ 251 { 252 "args": ["/bin/check_redis", "-p", "7000"], 253 "interval": "30s", 254 "ttl": "60s" 255 } 256 ] 257 }, 258 ... 259 ] 260} 261``` 262 263## Service and Tag Names with DNS 264 265Consul exposes service definitions and tags over the [DNS](/docs/agent/dns.html) 266interface. DNS queries have a strict set of allowed characters and a 267well-defined format that Consul cannot override. While it is possible to 268register services or tags with names that don't match the conventions, those 269services and tags will not be discoverable via the DNS interface. It is 270recommended to always use DNS-compliant service and tag names. 271 272DNS-compliant service and tag names may contain any alpha-numeric characters, as 273well as dashes. Dots are not supported because Consul internally uses them to 274delimit service tags. 275 276## Service Definition Parameter Case 277 278For historical reasons Consul's API uses `CamelCased` parameter names in 279responses, however it's configuration file uses `snake_case` for both HCL and 280JSON representations. For this reason the registration _HTTP APIs_ accept both 281name styles for service definition parameters although APIs will return the 282listings using `CamelCase`. 283 284Note though that **all config file formats require 285`snake_case` fields**. We always document service definition examples using 286`snake_case` and JSON since this format works in both config files and API 287calls. 288