diff --git a/website/source/docs/agent/http/catalog.html.markdown b/website/source/docs/agent/http/catalog.html.markdown index 40497c97f5..b35be213f3 100644 --- a/website/source/docs/agent/http/catalog.html.markdown +++ b/website/source/docs/agent/http/catalog.html.markdown @@ -4,13 +4,13 @@ page_title: "Catalog (HTTP)" sidebar_current: "docs-agent-http-catalog" description: > The Catalog is the endpoint used to register and deregister nodes, - services, and checks. It also provides a number of query endpoints. + services, and checks. It also provides query endpoints. --- # Catalog HTTP Endpoint The Catalog is the endpoint used to register and deregister nodes, -services, and checks. It also provides a number of query endpoints. +services, and checks. It also provides query endpoints. The following endpoints are supported: @@ -22,17 +22,17 @@ The following endpoints are supported: * [`/v1/catalog/service/`](#catalog_service) : Lists the nodes in a given service * [`/v1/catalog/node/`](#catalog_nodes) : Lists the services provided by a node -The last 4 endpoints of the catalog support blocking queries and -consistency modes. +The `nodes` and `services` endpoints support blocking queries and +tunable consistency modes. ### /v1/catalog/register -The register endpoint is a low level mechanism for directly registering -or updating entries in the catalog. It is usually recommended to use -the agent local endpoints, as they are simpler and perform anti-entropy. +The register endpoint is a low-level mechanism for registering or updating +entries in the catalog. Note: it is usually preferrable instead to use the +[agent endpoints](agent.html) for registration as they are simpler and perform anti-entropy. The register endpoint expects a JSON request body to be PUT. The request -body must look like: +body must look something like: ```javascript { @@ -61,37 +61,39 @@ body must look like: ``` The behavior of the endpoint depends on what keys are provided. The endpoint -requires `Node` and `Address` to be provided, while `Datacenter` will be defaulted +requires `Node` and `Address` to be provided while `Datacenter` will be defaulted to match that of the agent. If only those are provided, the endpoint will register the node with the catalog. -If the `Service` key is provided, then the service will also be registered. If -`ID` is not provided, it will be defaulted to `Service`. It is mandated that the -ID be node-unique. The `Tags`, `Address` and `Port` fields can be omitted. - -If the `Check` key is provided, then a health check will also be registered. It -is important to remember that this register API is very low level. This manipulates -the health check entry, but does not setup a script or TTL to actually update the -status. For that behavior, an agent local check should be setup. - -The `CheckID` can be omitted, and will default to the `Name`. Like before, the -`CheckID` must be node-unique. The `Notes` is an opaque field that is meant to -hold human readable text. If a `ServiceID` is provided that matches the `ID` -of a service on that node, then the check is treated as a service level health +If the `Service` key is provided, the service will also be registered. If +`ID` is not provided, it will be defaulted to the value of the `Service.Service` property. +Only one service with a given `ID` may be present per node. The service `Tags`, `Address`, +and `Port` fields are all optional. + +If the `Check` key is provided, a health check will also be registered. Note: this +register API manipulates the health check entry in the Catalog, but it does not setup +the script, TTL, or HTTP check to monitor the node's health. To truly enable a new +health check, the check must either be provided in agent configuration or set via +the [agent endpoint](agent.html). + +The `CheckID` can be omitted and will default to the value of `Name`. As with `Service.ID`, +the `CheckID` must be unique on this node. `Notes` is an opaque field that is meant to +hold human-readable text. If a `ServiceID` is provided that matches the `ID` +of a service on that node, the check is treated as a service level health check, instead of a node level health check. The `Status` must be one of -"unknown", "passing", "warning", or "critical". The "unknown" status is used +`unknown`, `passing`, `warning`, or `critical`. The `unknown` status is used to indicate that the initial check has not been performed yet. It is important to note that `Check` does not have to be provided with `Service` -and visa-versa. They can be provided or omitted at will. +and vice versa. A catalog entry can have either, neither, or both. -If the API call succeeds a 200 status code is returned. +If the API call succeeds, a 200 status code is returned. ### /v1/catalog/deregister -The deregister endpoint is a low level mechanism for directly removing -entries in the catalog. It is usually recommended to use the agent local -endpoints, as they are simpler and perform anti-entropy. +The deregister endpoint is a low-level mechanism for directly removing +entries from the Catalog. Note: it is usually preferrable instead to use the +[agent endpoints](agent.html) for deregistration as they are simpler and perform anti-entropy. The deregister endpoint expects a JSON request body to be PUT. The request body must look like one of the following: @@ -120,15 +122,14 @@ body must look like one of the following: ``` The behavior of the endpoint depends on what keys are provided. The endpoint -requires `Node` to be provided, while `Datacenter` will be defaulted -to match that of the agent. If only `Node` is provided, then the node, and +requires `Node` to be provided while `Datacenter` will be defaulted +to match that of the agent. If only `Node` is provided, the node and all associated services and checks are deleted. If `CheckID` is provided, only -that check belonging to the node is removed. If `ServiceID` is provided, then the -service along with its associated health check (if any) is removed. +that check is removed. If `ServiceID` is provided, the +service and its associated health check (if any) are removed. If the API call succeeds a 200 status code is returned. - ### /v1/catalog/datacenters This endpoint is hit with a GET and is used to return all the @@ -140,15 +141,15 @@ It returns a JSON body like this: ["dc1", "dc2"] ``` -This endpoint does not require a cluster leader, and as such -will succeed even during an availability outage. It can thus be -a simple check to see if any Consul servers are routable. +This endpoint does not require a cluster leader and +will succeed even during an availability outage. Therefore, it can be +used as a simple check to see if any Consul servers are routable. ### /v1/catalog/nodes -This endpoint is hit with a GET and returns the nodes known -about in a given DC. By default the datacenter of the agent is queried, -however the dc can be provided using the "?dc=" query parameter. +This endpoint is hit with a GET and returns the nodes registered +in a given DC. By default, the datacenter of the agent is queried; +however, the dc can be provided using the "?dc=" query parameter. It returns a JSON body like this: @@ -169,9 +170,9 @@ This endpoint supports blocking queries and all consistency modes. ### /v1/catalog/services -This endpoint is hit with a GET and returns the services known -about in a given DC. By default the datacenter of the agent is queried, -however the dc can be provided using the "?dc=" query parameter. +This endpoint is hit with a GET and returns the services registered +in a given DC. By default, the datacenter of the agent is queried; +however, the dc can be provided using the "?dc=" query parameter. It returns a JSON body like this: @@ -186,18 +187,18 @@ It returns a JSON body like this: } ``` -The main object keys are the service names, while the array -provides all the known tags for a given service. +The keys are the service names, and the array values provide all known +tags for a given service. This endpoint supports blocking queries and all consistency modes. ### /v1/catalog/service/\ This endpoint is hit with a GET and returns the nodes providing a service -in a given DC. By default the datacenter of the agent is queried, -however the dc can be provided using the "?dc=" query parameter. +in a given DC. By default, the datacenter of the agent is queried; +however, the dc can be provided using the "?dc=" query parameter. -The service being queried must be provided after the slash. By default +The service being queried must be provided on the path. By default all nodes in that service are returned. However, the list can be filtered by tag using the "?tag=" query parameter. @@ -221,10 +222,10 @@ This endpoint supports blocking queries and all consistency modes. ### /v1/catalog/node/\ -This endpoint is hit with a GET and returns the node provided services. -By default the datacenter of the agent is queried, -however the dc can be provided using the "?dc=" query parameter. -The node being queried must be provided after the slash. +This endpoint is hit with a GET and returns the node's registered services. +By default, the datacenter of the agent is queried; +however, the dc can be provided using the "?dc=" query parameter. +The node being queried must be provided on the path. It returns a JSON body like this: