--- layout: docs page_title: Register Services - Service Definitions description: >- 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. --- # Services 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. Use the [Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery?utm_source=consul.io&utm_medium=docs) to get hands-on experience registering a simple service with a health check on your local machine. ## Service Definition To configure a service, either provide the service definition as a `-config-file` option to the agent or place it inside the `-config-dir` of the agent. The file must end in the `.json` or `.hcl` extension to be loaded by Consul. Check definitions can be updated by sending a `SIGHUP` to the agent. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service) using the [HTTP API](/api). A service definition is a configuration that looks like the following. This example shows all possible fields, but note that only a few are required. ```json { "service": { "id": "redis", "name": "redis", "tags": ["primary"], "address": "", "meta": { "meta": "for my service" }, "tagged_addresses": { "lan": { "address": "192.168.0.55", "port": 8000, }, "wan": { "address": "198.18.0.23", "port": 80 } }, "port": 8000, "socket_path": "/tmp/redis.sock", "enable_tag_override": false, "checks": [ { "args": ["/usr/local/bin/check_redis.py"], "interval": "10s" } ], "kind": "connect-proxy", "proxy_destination": "redis", // Deprecated "proxy": { "destination_service_name": "redis", "destination_service_id": "redis1", "local_service_address": "127.0.0.1", "local_service_port": 9090, "local_service_socket_path": "/tmp/redis.sock", "mode": "transparent", "transparent_proxy": { "outbound_listener_port": 22500 }, "config": {}, "upstreams": [], "mesh_gateway": { "mode": "local" }, "expose": { "checks": true, "paths": [ { "path": "/healthz", "local_path_port": 8080, "listener_port": 21500, "protocol": "http2" } ] } }, "connect": { "native": false, "sidecar_service": {} "proxy": { // Deprecated "command": [], "config": {} } }, "weights": { "passing": 5, "warning": 1 }, "token": "233b604b-b92e-48c8-a253-5f11514e4b50", "namespace": "foo" } } ``` A service definition must include a `name` and may optionally provide an `id`, `tags`, `address`, `meta`, `port`, `enable_tag_override`, and `check`. The `id` is set to the `name` if not provided. It is required that all services have a unique ID per node, so if names might conflict then unique IDs should be provided. The `tags` property is a list of values that are opaque to Consul but can be used to distinguish between `primary` or `secondary` nodes, different versions, or any other service level labels. We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) for service definition names and tags for [compatibility with external DNS](/docs/agent/services#service-and-tag-names-with-dns) The `address` field is optional, and can be used to specify a service-specific IP address or a hostname. There is no server-side validation of this field, and it can be set to any string. When this value is not provided, the IP address of the agent node is used by default. The `port` field can be used as well to make a service-oriented architecture simpler to configure; this way, the address and port of a service can be discovered. The `meta` object is a map of max 64 key/values with string semantics. Key can contain only ASCII chars and no special characters (`A-Z` `a-z` `0-9` `_` and `-`). For performance and security reasons, values as well as keys are limited to 128 characters for keys, 512 for values. This object has the same limitations as the node meta object in node definition. All those meta data can be retrieved individually per instance of the service and all the instances of a given service have their own copy of it. 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 [anti-entropy syncs](/docs/internals/anti-entropy) and deregistration. Services registered in Consul clusters where both [Consul Namespaces](/docs/enterprise/namespaces) and the ACL system are enabled can be registered to specific namespaces that are associated with ACL tokens scoped to that namespace. Services registered with a service definition will not inherit the namespace associated with the ACL token specified in the `token` field. The `namespace` field, in addition to the `token` field, must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to. The `enable_tag_override` can optionally be specified to disable the anti-entropy feature for this service. If `enable_tag_override` is set to `TRUE` then external agents can update this service in the [catalog](/api/catalog) and modify the tags. Subsequent local sync operations by this agent will ignore the updated tags. For example, if an external agent modified both the tags and the port for this service and `enable_tag_override` was set to `TRUE` then after the next sync cycle the service's port would revert to the original value but the tags would maintain the updated value. As a counter example: If an external agent modified both the tags and port for this service and `enable_tag_override` was set to `FALSE` then after the next sync cycle the service's port _and_ the tags would revert to the original value and all modifications would be lost. 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](/docs/internals/anti-entropy) 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. ### Checks A service can have an associated health check. This is a powerful feature as it allows a web balancer to gracefully remove failing nodes, a database to replace a failed secondary, etc. The health check is strongly integrated in 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. There are several check types that have differing required options as [documented here](/docs/agent/checks). The check name is automatically generated as `service:`. If there are multiple service checks registered, the ID will be generated as `service::` where `` is an incrementing number starting from `1`. -> **Note:** There is more information about [checks here](/docs/agent/checks). ### 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](/docs/connect/registration/service-registration) reference for the available configuration options. ### Connect The `kind` field is used to optionally identify the service as a [Connect proxy](/docs/connect/proxies) instance. This value may be "connect-proxy" for [Connect-capable](/docs/connect) proxies representing another service, "mesh-gateway" for instances of a [mesh gateway](/docs/connect/mesh-gateway), "terminating-gateway" for instances of a [terminating gateway](/docs/connect/terminating-gateway), or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/ingress-gateway). For typical non-proxy instances the `kind` field must be omitted. The `proxy` field is also required for Connect proxy registrations and is only valid if `kind` is `connect-proxy`. The only required `proxy` field for a `connect-proxy` is `destination_service_name`. For more detail please see [complete proxy configuration example](/docs/connect/registration/service-registration#complete-configuration-example) -> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was specified using `proxy_destination` at the top level. This will continue to work until at least 1.5.0 but it's highly recommended to switch to using `proxy.destination_service_name`. The `connect` field can be specified to configure [Connect](/docs/connect) for a service. This field is available in Consul 1.2.0 and later. The `native` value can be set to true to advertise the service as [Connect-native](/docs/connect/native). The `sidecar_service` field is an optional nested service definition its behavior and defaults are described in [Sidecar Service Registration](/docs/connect/registration/sidecar-service). If `native` is true, it is an error to also specify a sidecar service registration. -> **Deprecation Notice:** From version 1.2.0 to 1.3.0 during beta, Connect supported "Managed" proxies which are specified with the `connect.proxy` field. [Managed Proxies are deprecated](/docs/connect/proxies/managed-deprecated) and the `connect.proxy` field will be removed in a future major release. ### DNS SRV Weights The `weights` field is an optional field to specify the weight of a service in DNS SRV responses. If this field is not specified, its default value is: `"weights": {"passing": 1, "warning": 1}`. When 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 agent DNS configuration or `?passing` is used via the API. When DNS SRV requests are made, the response will include the weights specified given the state of the service. This allows some instances to be given higher weight if they have more capacity, and optionally allows reducing load on services with checks in `warning` status by giving passing instances a higher weight. ### 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 [anti-entropy syncs](/docs/internals/anti-entropy) 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](/docs/internals/anti-entropy) 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 which 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 syntax for defining a tagged address is as follows. ```hcl service { name = "redis" port = 80 tagged_addresses { = { address = "
" port = port } } } ``` ```json { "service": { "name": "redis", "port": 80, "tagged_addresses": { "": { "address": "
", "port": port } } } } ``` Consul supports several tagged address types. The various types and their use cases are detailed below. #### LAN LAN addresses are intended to be directly accessible only from services within the same Consul data center. ##### Supported tags * `lan` - 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. * `lan_ipv6` - The IPv6 LAN address at which the node or service is accessible. ```hcl service { name = "redis" address = "192.0.2.10" port = 80 tagged_addresses { lan = { address = "192.0.2.10" port = 80 } lan_ipv4 = { address = "192.0.2.10" port = 80 } lan_ipv6 = { address = "2001:db8:1:2:cafe::1337" port = 80 } } } ``` ```json { "service": { "name": "redis", "address": "192.0.2.10", "port": 80, "tagged_addresses": { "lan": { "address": "192.0.2.10", "port": 80 }, "lan_ipv4": { "address": "192.0.2.10", "port": 80 }, "lan_ipv6": { "address": "2001:db8:1:2:cafe::1337", "port": 80 } } } } ``` #### Virtual Virtual tagged addresses are logical address types which can be configured on [Connect](/docs/connect)-enabled services. The virtual address provides a fixed IP address that can be used by downstream services when connecting to an upstream service. Connections to the virtual address are load balanced across available instances of a service, provided the following conditions are satisfied: 1. [Transparent proxy](/docs/connect/transparent-proxy) is enabled for the downstream and upstream services. 1. The upstream service is not configured for individual instances to be [dialed directly](/docs/connect/config-entries/service-defaults#dialeddirectly). -> **Note**: 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. ##### Supported tags Use the following address tag to specify the logical address at which the service can be reached by other services in the mesh. - `virtual` - The virtual IP address at which a logical service is reachable. ```hcl service { name = "redis" address = "192.0.2.10" port = 80 tagged_addresses { virtual = { address = "203.0.113.50" port = 80 } } } ``` ```json { "service": { "name": "redis", "address": "192.0.2.10", "port": 80, "tagged_addresses": { "virtual": { "address": "203.0.113.50", "port": 80 } } } } ``` #### WAN Define a WAN address for the service or node when it should be accessed at an alternate address by services in a remote datacenter. ##### Supported 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. - `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. - `wan_ipv6` - The IPv6 WAN address at which the node or service is accessible when being dialed from a remote data center. ```hcl service { name = "redis" address = "192.0.2.10" port = 80 tagged_addresses { wan = { address = "198.51.100.200" port = 80 } wan_ipv4 = { address = "198.51.100.200" port = 80 } wan_ipv6 = { address = "2001:db8:5:6:1337::1eaf" port = 80 } } } ``` ```json { "service": { "name": "redis", "address": "192.0.2.10", "port": 80, "tagged_addresses": { "wan": { "address": "198.51.100.200", "port": 80 }, "wan_ipv4": { "address": "198.51.100.200", "port": 80 }, "wan_ipv6": { "address": "2001:db8:5:6:1337::1eaf", "port": 80 } } } } ``` ## Multiple Service Definitions 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). ```json { "services": [ { "id": "red0", "name": "redis", "tags": [ "primary" ], "address": "", "port": 6000, "checks": [ { "args": ["/bin/check_redis", "-p", "6000"], "interval": "5s", "timeout": "20s" } ] }, { "id": "red1", "name": "redis", "tags": [ "delayed", "secondary" ], "address": "", "port": 7000, "checks": [ { "args": ["/bin/check_redis", "-p", "7000"], "interval": "30s", "timeout": "60s" } ] }, ... ] } ``` In HCL you can specify the plural `services` key (although not `service`) multiple times: ```hcl services { id = "red0" name = "redis" tags = [ "primary" ] address = "" port = 6000 checks = [ { args = ["/bin/check_redis", "-p", "6000"] interval = "5s" timeout = "20s" } ] } services { id = "red1" name = "redis" tags = [ "delayed", "secondary" ] address = "" port = 7000 checks = [ { args = ["/bin/check_redis", "-p", "7000"] interval = "30s" timeout = "60s" } ] } ``` ## Service and Tag Names with DNS Consul exposes service definitions and tags over the [DNS](/docs/discovery/dns) 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. ## Service Definition Parameter Case 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 `snake_case` and JSON since this format works in both config files and API calls.