Catalog HTTP API

The /catalog endpoints register and deregister nodes, services, and checks in Consul. The catalog should not be confused with the agent, since some of the API methods look similar.

Register Entity

This endpoint is a low-level mechanism for registering or updating entries in the catalog. It is usually preferable to instead use the agent endpoints for registration as they are simpler and perform anti-entropy.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Query Parameters

• ns (string: "")
  Enterprise
  - Specifies the namespace of the service and checks you register. You can also specify the namespace through other methods.

JSON Request Body Schema

• ID (string: "") - An optional UUID to assign to the node. This must be a 36-character UUID-formatted string.

• Node (string: <required>) - Specifies the node ID to register.

• Address (string: <required>) - Specifies the address to register.

• Datacenter (string: "") - Specifies the datacenter, which defaults to the agent's datacenter if not provided.

• TaggedAddresses (map<string|string>: nil) - Specifies the tagged addresses.

• NodeMeta (map<string|string>: nil) - Specifies arbitrary KV metadata pairs for filtering purposes.

• Service (Service: nil) - Contains an object the specifies the service to register. The Service.Service field is required. If Service.ID is not provided, the default is the Service.Service. You can only specify one service with a given ID per node. We recommend using valid DNS labels for service definition names. Refer to the Internet Engineering Task Force's RFC 1123 for additional information. Service names that conform to standard usage ensures compatibility with external DNSs. Refer to Services Configuration Reference for additional information. The following fields are optional:

  • Tags
  • Address
  • Meta
  • Port

  For additional information configuring services, refer to Service - Agent API. The /catalog endpoint had different behaviors than the /services endpoint.

• Check (Check: nil) - Specifies to register a check. The 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.

  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 passing, warning, or critical.

  You can provide defaults for TCP and HTTP health checks to the Definition field. Refer to Health Checks for additional information.

  Multiple checks can be provided by replacing Check with Checks and sending an array of Check objects.

• SkipNodeUpdate (bool: false) - Specifies whether to skip updating the node's information in the registration. This is useful in the case where only a health check or service entry on a node needs to be updated or when a register request is intended to update a service entry or health check. In both use cases, node information will not be overwritten, if the node is already registered. Note, if the parameter is enabled for a node that doesn't exist, it will still be created.

• Namespace (string: "")

  Enterprise
  - Specifies the namespace of the service and checks you register. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

It is important to note that Check does not have to be provided with Service and vice versa. A catalog entry can have either, neither, or both.

Sample Payload

{
  "Datacenter": "dc1",
  "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
  "Node": "t2.320",
  "Address": "192.168.10.10",
  "TaggedAddresses": {
    "lan": "192.168.10.10",
    "wan": "10.0.10.10"
  },
  "NodeMeta": {
    "somekey": "somevalue"
  },
  "Service": {
    "ID": "redis1",
    "Service":