diff --git a/website/source/docs/agent/services.html.markdown b/website/source/docs/agent/services.html.markdown index 95572986d..ab9c18dac 100644 --- a/website/source/docs/agent/services.html.markdown +++ b/website/source/docs/agent/services.html.markdown @@ -3,16 +3,16 @@ layout: "docs" page_title: "Service Definition" sidebar_current: "docs-agent-services" 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 associated with a service. A service is defined in a configuration file, or added at runtime over the HTTP interface. + 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. --- # 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 +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, +associated with a service. A service is defined in a configuration file or added at runtime over the HTTP interface. ## Service Definition @@ -36,37 +36,40 @@ A service definition that is a script looks like: } ``` -A service definition must include a `name`, and may optionally provide +A service definition must include a `name` and may optionally provide an `id`, `tags`, `address`, `port`, 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 ID's should be provided. +might conflict then unique IDs should be provided. -The `tags` is a list of opaque value to Consul, but can be used to distinguish -between "master" or "slave" nodes, different versions, or any other service level labels. -The `address` 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` can be used as well to make a service oriented architecture -simpler to configure. This way the address and port of a service can +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 be discovered. A service can have an associated health check. This is a powerful feature as -it allows a web balancer to gracefully remove failing nodes, or a database +it allows a web balancer to gracefully remove failing nodes, a database 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 node from any service query. -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 -`interval` must be provided. If it is a HTTP type, `http` and +The check must be of the script, HTTP, or TTL type. If it is a script type, `script` +and `interval` must be provided. If it is a HTTP type, `http` and `interval` must be provided. If it is a TTL type, then only `ttl` must be provided. 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 +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.html). + To configure a service, either provide it as a `-config-file` option to the -agent, or place it inside the `-config-dir` of the agent. The file must +agent or place it inside the `-config-dir` of the agent. The file must 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).