2014-02-19 02:05:18 +00:00
---
layout: "docs"
page_title: "Service Definition"
sidebar_current: "docs-agent-services"
2014-10-19 23:40:10 +00:00
description: |-
2015-01-29 00:43:52 +00:00
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 associated with a service. A service is defined in a configuration file or added at runtime over the HTTP interface.
2014-02-19 02:05:18 +00:00
---
# 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
2015-01-29 00:43:52 +00:00
to declare the availability of a service and to potentially associate it with
2014-02-19 02:05:18 +00:00
a health check. A health check is considered to be application level if it
2015-01-29 00:43:52 +00:00
associated with a service. A service is defined in a configuration file
2014-02-19 02:05:18 +00:00
or added at runtime over the HTTP interface.
## Service Definition
A service definition that is a script looks like:
2014-10-19 23:40:10 +00:00
```javascript
{
"service": {
"name": "redis",
"tags": ["master"],
2015-01-08 20:08:29 +00:00
"address": "127.0.0.1",
2014-10-19 23:40:10 +00:00
"port": 8000,
2015-01-14 01:52:17 +00:00
"checks": [
{
"script": "/usr/local/bin/check_redis.py",
"interval": "10s"
}
]
2014-10-19 23:40:10 +00:00
}
}
```
2014-02-19 02:05:18 +00:00
2015-01-29 00:43:52 +00:00
A service definition must include a `name` and may optionally provide
2015-01-08 20:08:29 +00:00
an `id` , `tags` , `address` , `port` , and `check` . The `id` is set to the `name` if not
2014-06-09 00:31:44 +00:00
provided. It is required that all services have a unique ID per node, so if names
2015-01-29 00:43:52 +00:00
might conflict then unique IDs should be provided.
2014-02-19 02:05:18 +00:00
2015-01-29 00:43:52 +00:00
The `tags` property is a list of values that are opaque to Consul but can be used to
distinguish between "master" or "slave" nodes, different versions, or any other service
level labels.
The `address` field can be used to specify a service-specific IP address. By
default, the IP address of the agent is used, and this does not need to be provided.
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
2014-02-19 02:05:18 +00:00
be discovered.
2015-01-09 05:34:16 +00:00
A service can have an associated health check. This is a powerful feature as
2015-01-29 00:43:52 +00:00
it allows a web balancer to gracefully remove failing nodes, a database
2015-01-09 05:34:16 +00:00
to replace a failed slave, 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
2014-02-19 02:05:18 +00:00
node from any service query.
2015-01-29 00:43:52 +00:00
Note: there is more information about [checks here ](/docs/agent/checks.html ). The
check must be of the script, HTTP, or TTL type. If it is a script type, `script` and
2015-01-09 22:43:24 +00:00
`interval` must be provided. If it is a HTTP type, `http` and
2014-02-19 02:05:18 +00:00
`interval` must be provided. If it is a TTL type, then only `ttl` must be
2015-01-14 01:52:17 +00:00
provided. The check name is automatically generated as
`service:<service-id>` . If there are multiple service checks registered, the
2015-01-29 00:43:52 +00:00
ID will be generated as `service:<service-id>:<num>` where `<num>` is an
2015-01-14 01:52:17 +00:00
incrementing number starting from `1` .
2014-02-19 02:05:18 +00:00
2014-02-23 02:53:31 +00:00
To configure a service, either provide it as a `-config-file` option to the
2015-01-29 00:43:52 +00:00
agent or place it inside the `-config-dir` of the agent. The file must
2014-02-23 02:53:31 +00:00
end in the ".json" extension to be loaded by Consul. Check definitions can
also be updated by sending a `SIGHUP` to the agent. Alternatively, the
service can be registered dynamically using the [HTTP API ](/docs/agent/http.html ).
2014-10-24 02:22:25 +00:00
## Multiple Service Definitions
2014-10-26 20:24:23 +00:00
Multiple services definitions can be provided at once using the `services`
(plural) key in your configuration file.
2014-10-24 02:22:25 +00:00
```javascript
{
"services": [
{
"id": "red0",
"name": "redis",
"tags": [
"master"
],
2015-01-08 20:08:29 +00:00
"address": "127.0.0.1",
2014-10-24 02:22:25 +00:00
"port": 6000,
2015-01-14 01:52:17 +00:00
"checks": [
{
"script": "/bin/check_redis -p 6000",
"interval": "5s",
"ttl": "20s"
}
]
2014-10-24 02:22:25 +00:00
},
{
"id": "red1",
"name": "redis",
"tags": [
"delayed",
"slave"
],
2015-01-08 20:08:29 +00:00
"address": "127.0.0.1",
2014-10-24 02:22:25 +00:00
"port": 7000,
2015-01-14 01:52:17 +00:00
"checks": [
{
"script": "/bin/check_redis -p 7000",
"interval": "30s",
"ttl": "60s"
}
]
2014-10-24 02:22:25 +00:00
},
...
]
}
```