2017-04-04 16:33:22 +00:00
|
|
|
|
---
|
|
|
|
|
layout: api
|
|
|
|
|
page_title: Catalog - HTTP API
|
|
|
|
|
sidebar_current: api-catalog
|
|
|
|
|
description: |-
|
|
|
|
|
The /catalog endpoints register and deregister nodes, services, and checks in
|
|
|
|
|
Consul.
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# 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](/api/agent.html) for registration as they are simpler and
|
|
|
|
|
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `PUT` | `/catalog/register` | `application/json` |
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
|
[blocking queries](/api/index.html#blocking-queries),
|
|
|
|
|
[consistency modes](/api/index.html#consistency-modes), and
|
|
|
|
|
[required ACLs](/api/index.html#acls).
|
|
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | -------------------------- |
|
|
|
|
|
| `NO` | `none` | `node:write,service:write` |
|
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `ID` `(string: "")` - An optional UUID to assign to the service. If not
|
|
|
|
|
provided, one is generated. This must be a 36-character UUID.
|
|
|
|
|
|
|
|
|
|
- `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.
|
|
|
|
|
|
2017-08-01 00:06:07 +00:00
|
|
|
|
- `NodeMeta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
|
2017-04-04 16:33:22 +00:00
|
|
|
|
pairs for filtering purposes.
|
|
|
|
|
|
|
|
|
|
- `Service` `(Service: nil)` - Specifies to register a service. 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
|
website: correct paramater for service meta on catalog register
I believe this may have been missed as part of #3994. Note that the
API _returns_ `ServiceMeta`, but accepts `Meta`.
$ curl -X PUT -d \
'{
"Datacenter": "dc1",
"Node": "example",
"Address": "www.example.com",
"Service": {
"Service": "example-service",
"Port": 80,
"Meta": {"foo": "bar"}
}
}' \
http://localhost:8500/v1/catalog/register
$ curl localhost:8500/v1/catalog/service/example-service
[
{
"ID": "",
"Node": "example",
"Address": "www.example.com",
"Datacenter": "dc1",
"TaggedAddresses": null,
"NodeMeta": null,
"ServiceKind": "",
"ServiceID": "example-service",
"ServiceName": "example-service",
"ServiceTags": [],
"ServiceAddress": "",
"ServiceMeta": {
"foo": "bar"
},
"ServicePort": 80,
"ServiceEnableTagOverride": false,
"ServiceProxyDestination": "",
"ServiceConnect": {
"Native": false,
"Proxy": null
},
"CreateIndex": 11,
"ModifyIndex": 37
}
]
2018-06-26 19:15:23 +00:00
|
|
|
|
`Tags`, `Address`, `Meta`, and `Port` fields are all optional.
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
- `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](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 `passing`, `warning`, or `critical`.
|
|
|
|
|
|
2017-11-01 21:25:46 +00:00
|
|
|
|
The `Definition` field can be provided with details for a TCP or HTTP health
|
|
|
|
|
check. For more information, see the [Health Checks](/docs/agent/checks.html) page.
|
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
Multiple checks can be provided by replacing `Check` with `Checks` and
|
|
|
|
|
sending an array of `Check` objects.
|
|
|
|
|
|
2017-11-01 21:25:46 +00:00
|
|
|
|
- `SkipNodeUpdate` `(bool: false)` - Specifies whether to skip updating the
|
|
|
|
|
node part of the registration. Useful in the case where only a health check
|
|
|
|
|
or service entry on a node needs to be updated.
|
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"Datacenter": "dc1",
|
|
|
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
|
|
|
"Node": "foobar",
|
|
|
|
|
"Address": "192.168.10.10",
|
|
|
|
|
"TaggedAddresses": {
|
|
|
|
|
"lan": "192.168.10.10",
|
|
|
|
|
"wan": "10.0.10.10"
|
|
|
|
|
},
|
|
|
|
|
"NodeMeta": {
|
|
|
|
|
"somekey": "somevalue"
|
|
|
|
|
},
|
|
|
|
|
"Service": {
|
|
|
|
|
"ID": "redis1",
|
|
|
|
|
"Service": "redis",
|
|
|
|
|
"Tags": [
|
|
|
|
|
"primary",
|
|
|
|
|
"v1"
|
|
|
|
|
],
|
|
|
|
|
"Address": "127.0.0.1",
|
2018-03-28 14:04:50 +00:00
|
|
|
|
"Meta": {
|
2018-02-11 13:12:41 +00:00
|
|
|
|
"redis_version": "4.0"
|
|
|
|
|
},
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"Port": 8000
|
|
|
|
|
},
|
|
|
|
|
"Check": {
|
|
|
|
|
"Node": "foobar",
|
|
|
|
|
"CheckID": "service:redis1",
|
|
|
|
|
"Name": "Redis health check",
|
|
|
|
|
"Notes": "Script based health check",
|
|
|
|
|
"Status": "passing",
|
2017-11-01 21:25:46 +00:00
|
|
|
|
"ServiceID": "redis1",
|
|
|
|
|
"Definition": {
|
|
|
|
|
"TCP": "localhost:8888",
|
|
|
|
|
"Interval": "5s",
|
|
|
|
|
"Timeout": "1s",
|
|
|
|
|
"DeregisterCriticalServiceAfter": "30s"
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"SkipNodeUpdate": false
|
2017-04-04 16:33:22 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
$ curl \
|
|
|
|
|
--request PUT \
|
|
|
|
|
--data @payload.json \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/catalog/register
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Deregister Entity
|
|
|
|
|
|
|
|
|
|
This endpoint is a low-level mechanism for directly removing
|
|
|
|
|
entries from the Catalog. It is usually preferable to instead use the
|
|
|
|
|
[agent endpoints](/api/agent.html) for deregistration as they are simpler and
|
|
|
|
|
perform [anti-entropy](/docs/internals/anti-entropy.html).
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `PUT` | `/catalog/deregister` | `application/json` |
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
|
[blocking queries](/api/index.html#blocking-queries),
|
|
|
|
|
[consistency modes](/api/index.html#consistency-modes), and
|
|
|
|
|
[required ACLs](/api/index.html#acls).
|
|
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | -------------------------- |
|
|
|
|
|
| `NO` | `none` | `node:write,service:write` |
|
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
The behavior of the endpoint depends on what keys are provided.
|
|
|
|
|
|
|
|
|
|
- `Node` `(string: <required>)` - Specifies the ID of the node. If no other
|
|
|
|
|
values are provided, this node, all its services, and all its checks are
|
|
|
|
|
removed.
|
|
|
|
|
|
|
|
|
|
- `Datacenter` `(string: "")` - Specifies the datacenter, which defaults to the
|
|
|
|
|
agent's datacenter if not provided.
|
|
|
|
|
|
|
|
|
|
- `CheckID` `(string: "")` - Specifies the ID of the check to remove.
|
|
|
|
|
|
|
|
|
|
- `ServiceID` `(string: "")` - Specifies the ID of the service to remove. The
|
|
|
|
|
service and all associated checks will be removed.
|
|
|
|
|
|
|
|
|
|
### Sample Payloads
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"Datacenter": "dc1",
|
|
|
|
|
"Node": "foobar"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"Datacenter": "dc1",
|
|
|
|
|
"Node": "foobar",
|
|
|
|
|
"CheckID": "service:redis1"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"Datacenter": "dc1",
|
|
|
|
|
"Node": "foobar",
|
|
|
|
|
"ServiceID": "redis1"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
$ curl \
|
|
|
|
|
--request PUT \
|
|
|
|
|
--data @payload.json \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/catalog/deregister
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## List Datacenters
|
|
|
|
|
|
|
|
|
|
This endpoint returns the list of all known datacenters. The datacenters will be
|
|
|
|
|
sorted in ascending order based on the estimated median round trip time from the
|
|
|
|
|
server to the servers in that datacenter.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `GET` | `/catalog/datacenters` | `application/json` |
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
|
[blocking queries](/api/index.html#blocking-queries),
|
|
|
|
|
[consistency modes](/api/index.html#consistency-modes), and
|
|
|
|
|
[required ACLs](/api/index.html#acls).
|
|
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | ------------ |
|
|
|
|
|
| `NO` | `none` | `none` |
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/catalog/datacenters
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
2017-05-19 19:15:27 +00:00
|
|
|
|
### Sample Response
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
["dc1", "dc2"]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## List Nodes
|
|
|
|
|
|
|
|
|
|
This endpoint and returns the nodes registered in a given datacenter.
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `GET` | `/catalog/nodes` | `application/json` |
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
|
[blocking queries](/api/index.html#blocking-queries),
|
|
|
|
|
[consistency modes](/api/index.html#consistency-modes), and
|
|
|
|
|
[required ACLs](/api/index.html#acls).
|
|
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | ------------ |
|
|
|
|
|
| `YES` | `all` | `node:read` |
|
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
|
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
|
|
|
URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `near` `(string: "")` - Specifies a node name to sort the node list in
|
|
|
|
|
ascending order based on the estimated round trip time from that node. Passing
|
|
|
|
|
`?near=_agent` will use the agent's node for the sort. This is specified as
|
|
|
|
|
part of the URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
|
|
|
|
|
of the form `key:value`. This parameter can be specified multiple times, and
|
|
|
|
|
will filter the results to nodes with the specified key/value pairs. This is
|
|
|
|
|
specified as part of the URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/catalog/nodes
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
[
|
|
|
|
|
{
|
|
|
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
|
|
|
"Node": "baz",
|
|
|
|
|
"Address": "10.1.10.11",
|
2017-04-18 12:02:24 +00:00
|
|
|
|
"Datacenter": "dc1",
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"TaggedAddresses": {
|
|
|
|
|
"lan": "10.1.10.11",
|
|
|
|
|
"wan": "10.1.10.11"
|
|
|
|
|
},
|
|
|
|
|
"Meta": {
|
|
|
|
|
"instance_type": "t2.medium"
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
|
|
|
|
"Node": "foobar",
|
|
|
|
|
"Address": "10.1.10.12",
|
2017-04-18 12:02:24 +00:00
|
|
|
|
"Datacenter": "dc2",
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"TaggedAddresses": {
|
|
|
|
|
"lan": "10.1.10.11",
|
|
|
|
|
"wan": "10.1.10.12"
|
|
|
|
|
},
|
|
|
|
|
"Meta": {
|
|
|
|
|
"instance_type": "t2.large"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## List Services
|
|
|
|
|
|
|
|
|
|
This endpoint returns the services registered in a given datacenter.
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `GET` | `/catalog/services` | `application/json` |
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
|
[blocking queries](/api/index.html#blocking-queries),
|
|
|
|
|
[consistency modes](/api/index.html#consistency-modes), and
|
|
|
|
|
[required ACLs](/api/index.html#acls).
|
|
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | -------------- |
|
2017-07-25 05:14:51 +00:00
|
|
|
|
| `YES` | `all` | `service:read` |
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
|
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
|
|
|
URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
|
|
|
|
|
of the form `key:value`. This parameter can be specified multiple times, and
|
|
|
|
|
will filter the results to nodes with the specified key/value pairs. This is
|
|
|
|
|
specified as part of the URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/catalog/services
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"consul": [],
|
|
|
|
|
"redis": [],
|
|
|
|
|
"postgresql": [
|
|
|
|
|
"primary",
|
|
|
|
|
"secondary"
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The keys are the service names, and the array values provide all known tags for
|
|
|
|
|
a given service.
|
|
|
|
|
|
|
|
|
|
## List Nodes for Service
|
|
|
|
|
|
|
|
|
|
This endpoint returns the nodes providing a service in a given datacenter.
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `GET` | `/catalog/service/:service` | `application/json` |
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
|
[blocking queries](/api/index.html#blocking-queries),
|
|
|
|
|
[consistency modes](/api/index.html#consistency-modes), and
|
|
|
|
|
[required ACLs](/api/index.html#acls).
|
|
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | ------------------------ |
|
|
|
|
|
| `YES` | `all` | `node:read,service:read` |
|
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `service` `(string: <required>)` - Specifies the name of the service for which
|
|
|
|
|
to list nodes. This is specified as part of the URL.
|
|
|
|
|
|
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
|
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
|
|
|
URL as a query parameter.
|
|
|
|
|
|
2017-11-17 03:20:30 +00:00
|
|
|
|
- `tag` `(string: "")` - Specifies the tag to filter on.
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
- `near` `(string: "")` - Specifies a node name to sort the node list in
|
|
|
|
|
ascending order based on the estimated round trip time from that node. Passing
|
|
|
|
|
`?near=_agent` will use the agent's node for the sort. This is specified as
|
|
|
|
|
part of the URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
|
|
|
|
|
of the form `key:value`. This parameter can be specified multiple times, and
|
|
|
|
|
will filter the results to nodes with the specified key/value pairs. This is
|
|
|
|
|
specified as part of the URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/catalog/service/my-service
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
[
|
|
|
|
|
{
|
|
|
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
|
|
|
"Node": "foobar",
|
|
|
|
|
"Address": "192.168.10.10",
|
2017-04-18 12:02:24 +00:00
|
|
|
|
"Datacenter": "dc1",
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"TaggedAddresses": {
|
|
|
|
|
"lan": "192.168.10.10",
|
|
|
|
|
"wan": "10.0.10.10"
|
|
|
|
|
},
|
2017-09-11 10:14:47 +00:00
|
|
|
|
"NodeMeta": {
|
2017-09-11 11:01:56 +00:00
|
|
|
|
"somekey": "somevalue"
|
2017-04-04 16:33:22 +00:00
|
|
|
|
},
|
|
|
|
|
"CreateIndex": 51,
|
|
|
|
|
"ModifyIndex": 51,
|
|
|
|
|
"ServiceAddress": "172.17.0.3",
|
|
|
|
|
"ServiceEnableTagOverride": false,
|
|
|
|
|
"ServiceID": "32a2a47f7992:nodea:5000",
|
|
|
|
|
"ServiceName": "foobar",
|
|
|
|
|
"ServicePort": 5000,
|
2018-02-11 13:12:41 +00:00
|
|
|
|
"ServiceMeta": {
|
|
|
|
|
"foobar_meta_value": "baz"
|
|
|
|
|
},
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"ServiceTags": [
|
|
|
|
|
"tacos"
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- `Address` is the IP address of the Consul node on which the service is
|
|
|
|
|
registered.
|
|
|
|
|
|
2017-04-18 12:02:24 +00:00
|
|
|
|
- `Datacenter` is the data center of the Consul node on which the service is
|
|
|
|
|
registered.
|
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
- `TaggedAddresses` is the list of explicit LAN and WAN IP addresses for the
|
|
|
|
|
agent
|
|
|
|
|
|
2017-09-11 10:14:47 +00:00
|
|
|
|
- `NodeMeta` is a list of user-defined metadata key/value pairs for the node
|
2017-04-04 16:33:22 +00:00
|
|
|
|
|
|
|
|
|
- `CreateIndex` is an internal index value representing when the service was
|
|
|
|
|
created
|
|
|
|
|
|
|
|
|
|
- `ModifyIndex` is the last index that modified the service
|
|
|
|
|
|
|
|
|
|
- `Node` is the name of the Consul node on which the service is registered
|
|
|
|
|
|
|
|
|
|
- `ServiceAddress` is the IP address of the service host — if empty, node
|
|
|
|
|
address should be used
|
|
|
|
|
|
|
|
|
|
- `ServiceEnableTagOverride` indicates whether service tags can be overridden on
|
|
|
|
|
this service
|
|
|
|
|
|
|
|
|
|
- `ServiceID` is a unique service instance identifier
|
|
|
|
|
|
|
|
|
|
- `ServiceName` is the name of the service
|
|
|
|
|
|
2018-02-11 13:12:41 +00:00
|
|
|
|
- `ServiceMeta` is a list of user-defined metadata key/value pairs for the service
|
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
- `ServicePort` is the port number of the service
|
|
|
|
|
|
|
|
|
|
- `ServiceTags` is a list of tags for the service
|
|
|
|
|
|
2018-05-29 21:07:40 +00:00
|
|
|
|
- `ServiceKind` is the kind of service, usually "". See the Agent
|
|
|
|
|
registration API for more information.
|
|
|
|
|
|
|
|
|
|
- `ServiceProxyDestination` is the name of the service that is being proxied,
|
|
|
|
|
for "connect-proxy" type services.
|
|
|
|
|
|
2018-06-05 17:51:05 +00:00
|
|
|
|
- `ServiceConnect` are the [Connect](/docs/connect/index.html) settings. The
|
|
|
|
|
value of this struct is equivalent to the `Connect` field for service registration.
|
2018-06-05 16:43:49 +00:00
|
|
|
|
|
2018-05-29 21:07:40 +00:00
|
|
|
|
## List Nodes for Connect-capable Service
|
|
|
|
|
|
|
|
|
|
This endpoint returns the nodes providing a
|
|
|
|
|
[Connect-capable](/docs/connect/index.html) service in a given datacenter.
|
|
|
|
|
This will include both proxies and native integrations. A service may
|
|
|
|
|
register both Connect-capable and incapable services at the same time,
|
|
|
|
|
so this endpoint may be used to filter only the Connect-capable endpoints.
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `GET` | `/catalog/connect/:service` | `application/json` |
|
|
|
|
|
|
2018-07-20 15:50:28 +00:00
|
|
|
|
Parameters and response format are the same as
|
|
|
|
|
[`/catalog/service/:service`](/api/catalog.html#list-nodes-for-service).
|
2018-05-29 21:07:40 +00:00
|
|
|
|
|
2017-04-04 16:33:22 +00:00
|
|
|
|
## List Services for Node
|
|
|
|
|
|
|
|
|
|
This endpoint returns the node's registered services.
|
|
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
|
| ------ | ---------------------------- | -------------------------- |
|
|
|
|
|
| `GET` | `/catalog/node/:node` | `application/json` |
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for blocking queries and
|
|
|
|
|
consistency modes.
|
|
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
|
|
|
|
[blocking queries](/api/index.html#blocking-queries),
|
|
|
|
|
[consistency modes](/api/index.html#consistency-modes), and
|
|
|
|
|
[required ACLs](/api/index.html#acls).
|
|
|
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
|
| ---------------- | ----------------- | ------------------------ |
|
|
|
|
|
| `YES` | `all` | `node:read,service:read` |
|
|
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
|
|
- `node` `(string: <required>)` - Specifies the name of the node for which
|
|
|
|
|
to list services. This is specified as part of the URL.
|
|
|
|
|
|
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
|
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
|
|
|
URL as a query parameter.
|
|
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
$ curl \
|
2018-08-28 16:07:15 +00:00
|
|
|
|
http://127.0.0.1:8500/v1/catalog/node/my-node
|
2017-04-04 16:33:22 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"Node": {
|
|
|
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
|
|
|
"Node": "foobar",
|
|
|
|
|
"Address": "10.1.10.12",
|
2017-04-18 12:02:24 +00:00
|
|
|
|
"Datacenter": "dc1",
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"TaggedAddresses": {
|
|
|
|
|
"lan": "10.1.10.12",
|
|
|
|
|
"wan": "10.1.10.12"
|
|
|
|
|
},
|
|
|
|
|
"Meta": {
|
|
|
|
|
"instance_type": "t2.medium"
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"Services": {
|
|
|
|
|
"consul": {
|
|
|
|
|
"ID": "consul",
|
|
|
|
|
"Service": "consul",
|
|
|
|
|
"Tags": null,
|
2018-03-28 14:04:50 +00:00
|
|
|
|
"Meta": {},
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"Port": 8300
|
|
|
|
|
},
|
|
|
|
|
"redis": {
|
|
|
|
|
"ID": "redis",
|
|
|
|
|
"Service": "redis",
|
|
|
|
|
"Tags": [
|
|
|
|
|
"v1"
|
|
|
|
|
],
|
2018-03-28 14:04:50 +00:00
|
|
|
|
"Meta": {
|
2018-02-11 13:12:41 +00:00
|
|
|
|
"redis_version": "4.0"
|
|
|
|
|
},
|
2017-04-04 16:33:22 +00:00
|
|
|
|
"Port": 8000
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|