One of the main goals of service discovery is to provide a catalog of available
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
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
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
a health check. A health check associated with a service is considered to be an
associated with a service. A service is defined in a configuration file
application-level check. A service is defined in a configuration file
or added at runtime over the HTTP interface.
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.
Complete 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
## Service Definition
To configure a service, either provide the service definition as a
Configure a service by providing the service definition to the agent. You can
`-config-file` option to the agent or place it inside the `-config-dir` of the
either specify the configuration file using the `-config-file` option, or specify
agent. The file must end in the `.json` or `.hcl` extension to be loaded by
the directory containing the service definition file with the `-config-dir` option.
Consul. Check definitions can be updated by sending a `SIGHUP` to the agent.
Save the service definition as a `.json` or `.hcl` file. so that it can be loaded by Consul.
Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service)
Send a `SIGHUP` to the running agent to check for new service definitions or to
update existing services. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service)
using the [HTTP API](/api).
using the [HTTP API](/api).
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.
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.
@ -112,64 +113,35 @@ The following table describes the available parameters for service definitions.
### `service`
### `service`
This is the root-level parameter that definex the service. You can specify the parameters to configure the service.
This is the root-level parameter that defines the service. You can specify the parameters to configure the service.
| `id` | String value that specifies the service ID. <p>If not specified, the value of the `name` field will be used. </p>Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional |
| `id` | String value that specifies the service ID. <br/>If not specified, the value of the `name` field will be used. <br/>Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional |
| `name` | Specifies the name of the service. <p>The value for this parameter is used as the ID if the `id` parameter is not specified.</p>We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required |
| `name` | Specifies the name of the service. <br/>The value for this parameter is used as the ID if the `id` parameter is not specified.<br/>We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required |
| `tags` | List of string values that can be used to add service-level labels. <p>For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions. </p>We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.<p>Tag values are opaque to Consul.</p> | None | Optional |
| `tags` | List of string values that can be used to add service-level labels. <br/>For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions. <br/>We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.<br/>Tag values are opaque to Consul.<br/> | None | Optional |
| `address` | String value that specifies a service-specific IP address or hostname. <br/>If no value is specified, the IP address of the agent node is used by default. <br/>There is no service-side validation of this parameter. | IP address of the agent node | Optional |
| `address` | String value that specifies a service-specific IP address or hostname. <br/>If no value is specified, the IP address of the agent node is used by default. <br/>There is no service-side validation of this parameter. | IP address of the agent node | Optional |
| `meta` | Object that defines a map of the max 64 key/value pairs. <p>The meta object has the same limitations as the node meta object in the node definition. </p>Meta data can be retrieved per individual instance of the service. All instances of a given service have their own copy of the meta data. <p> See [Adding Meta Data](#adding-meta-data) for supported parameters.</p> | None | Optional |
| `meta` | Object that defines a map of the max 64 key/value pairs. <br/>The meta object has the same limitations as the node meta object in the node definition. <br/>Meta data can be retrieved per individual instance of the service. All instances of a given service have their own copy of the meta data. <br/> See [Adding Meta Data](#adding-meta-data) for supported parameters.<br/> | None | Optional |
| `tagged_addresses` | Tagged addresses are additional addresses that may be defined for a node or service. See [Tagged Addresses](#tagged-addresses) for details. | None | Optional |
| `tagged_addresses` | Tagged addresses are additional addresses that may be defined for a node or service. See [Tagged Addresses](#tagged-addresses) for details. | None | Optional |
| `port` | Integer value that specifies a service-specific port number. The port number should be specified when the `address` parameter is defined to improve service discoverability. | Optional |
| `port` | Integer value that specifies a service-specific port number. The port number should be specified when the `address` parameter is defined to improve service discoverability. | Optional |
| `socket_path` | String value that specifies the path to the service socket. <br/>Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket. | None | Optional |
| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled. <p> If set to `true`, the then external agents can update this service in the catalog and modify the tags.</p> Subsequent local sync operations by this agent will ignore the updated tags. <p> This parameter only applies to the locally-registered service. If multiple nodes register the same service, the `enable_tag_override` configuration, and all other service configuration items, operate independently. </p>Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node. <p> See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.</p> | False | Optional |
| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled. <br/> If set to `true`, the then external agents can update this service in the catalog and modify the tags.<br/> Subsequent local sync operations by this agent will ignore the updated tags. <br/> This parameter only applies to the locally-registered service. If multiple nodes register the same service, the `enable_tag_override` configuration, and all other service configuration items, operate independently. <br/>Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node. <br/> See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.<br/> | False | Optional |
| `checks` | Array of objects that define health checks for the service. See [Health Checks](#health-checks) for details. | None | Optional |
| `checks` | Array of objects that define health checks for the service. See [Health Checks](#health-checks) for details. | None | Optional |
| `kind` | String value that identifies the service as a Connect proxy. See [Connect](#connect) for details. | None | Optional |
| `kind` | String value that identifies the service as a Connect proxy. See [Connect](#connect) for details. | None | Optional |
| `proxy_destination` | String value that specifies the _name_ of the destination service that the service currently being configured proxies to. <p>This parameter is deprecated. Use `proxy.destination_service` instead. </p>See [Connect](#Connect) for additional information. | None | Optional |
| `proxy_destination` | String value that specifies the _name_ of the destination service that the service currently being configured proxies to. <br/>This parameter is deprecated. Use `proxy.destination_service` instead. <br/>See [Connect](#Connect) for additional information. | None | Optional |
| `proxy` | Object that defines the destination services that the service currently being configured proxies to. See [Proxy](#Proxy) for additional information. | None | Optional |
| `proxy` | Object that defines the destination services that the service currently being configured proxies to. See [Proxy](#Proxy) for additional information. | None | Optional |
| `connect` | Object that configures a Consul Connect service mesh connection. See [Connect](#connect) for details. | None | Optional |
| `connect` | Object that configures a Consul Connect service mesh connection. See [Connect](#connect) for details. | None | Optional |
| `weights` | Object that configures the weight of the service in terms of its DNS service (SRV) response. See [DNS SRV Weights](#dns-srv-weights) for details. | None | Optional |
| `weights` | Object that configures the weight of the service in terms of its DNS service (SRV) response. See [DNS SRV Weights](#dns-srv-weights) for details. | None | Optional |
| `token` | String value specifying the ACL token (if the ACL system is enabled). The token is required for the service to interact with the service catalog. See [Security Configurations](#security-configurations) for details. | None | Required if ACLs are enabled |
| `token` | String value specifying the ACL token (if the ACL system is enabled). The token is required for the service to interact with the service catalog. See [Security Configurations](#security-configurations) for details. | None | Required if ACLs are enabled |
| `namespace` | String value specifying the Consul Namespace where the service should be registered. See [Security Configurations](#security-configurations) for details. | None | Optional |
| `namespace` | String value specifying the Consul Namespace where the service should be registered. See [Security Configurations](#security-configurations) for details. | None | Optional |
### Adding Meta Data
### Adding Meta Data
You can add semantic meta data to the service using the `meta` parameter. This parameter defines defines a map of max 64 key/value pairs. You can specify the following parameters to define meta data for the service.
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.
| `KEY` | String value that adds semantic metadata to the service. <p>Keys can only have ASCII characters (`A` - `Z`, `a` - `z`, `0` - `9`, `_`, and `-`). </p>Keys can not have special characters. <p>Keys are limited to 128 characters.</p>Values are limited to 512 characters. | None | Optional |
| `KEY` | String value that adds semantic metadata to the service. <br/>Keys can only have ASCII characters (`A` - `Z`, `a` - `z`, `0` - `9`, `_`, and `-`). <br/>Keys can not have special characters. <br/>Keys are limited to 128 characters.<br/>Values are limited to 512 characters. | None | Optional |
<!--
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. -->
### Security Configurations
### Security Configurations
@ -213,7 +185,7 @@ deprecated and has been removed as of Consul 1.1. -->
### Health Checks
### Health Checks
You can add health checks to your service definition. Health checks perform severaly safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database
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 funcationality 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
to replace a failed secondary. The health check funcationality 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.
node from any service query.
@ -315,7 +287,7 @@ service. Tagged addresses can be used by remote agents and services as alternati
addresses for communicating with the given node or service. Multiple tagged
addresses for communicating with the given node or service. Multiple tagged
addresses may be configured on a node or service.
addresses may be configured on a node or service.
The following example is describes the syntax for defining a tagged address.
The following example describes the syntax for defining a tagged address.
<CodeTabs heading="Tagged address format">
<CodeTabs heading="Tagged address format">
@ -349,15 +321,15 @@ service {
</CodeTabs>
</CodeTabs>
Consul supports several tagged address types. The various types and their use
The following table provides an overview of the various tagged address types supported by Consul.
cases are detailed below.
#### LAN
LAN addresses are intended to be directly accessible only from services within
| LAN | LAN addresses are intended to be directly accessible only from services within the same Consul data center. See [LAN tags](#lan-tags) for details. | `lan` <br/> `lan_ipv4` <br/> `lan_ipv6` |
| Virtual | Virtual tagged addresses are logical address types that 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. See [Virtual tags](#virtual-tags) for details. | `virtual` |
| 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. See [WAN tags](#wan-tags) for details. | `wan` <br/> `wan_ipv4` <br/> `wan_ipv6` |
##### Supported tags
#### LAN tags
- `lan` - The IPv4 LAN address at which the node or service is accessible.
- `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_ipv4` - The IPv4 LAN address at which the node or service is accessible.
@ -420,27 +392,21 @@ service {
</CodeBlockConfig>
</CodeBlockConfig>
</CodeTabs>
</CodeTabs>
#### Virtual
#### Virtual tags
Virtual tagged addresses are logical address types which can be configured on
Connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied:
[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
1. [Transparent proxy](/docs/connect/transparent-proxy) is enabled for the
downstream and upstream services.
downstream and upstream services.
1. The upstream service is not configured for individual instances to be
1. The upstream service is not configured for individual instances to be
trujillo-adam
3 years ago