mirror of https://github.com/hashicorp/consul
1150 lines
48 KiB
Markdown
1150 lines
48 KiB
Markdown
---
|
|
layout: api
|
|
page_title: Catalog - HTTP API
|
|
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](/consul/api-docs/agent) for registration as they are simpler and
|
|
perform [anti-entropy](/consul/docs/architecture/anti-entropy).
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------- | ------------------ |
|
|
| `PUT` | `/catalog/register` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | -------------------------- |
|
|
| `NO` | `none` | `none` | `node:write,service:write` |
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you register.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### 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](https://datatracker.ietf.org/doc/html/rfc1123#page-72) for additional information. Service names that conform to standard usage ensures compatibility with external DNSs. Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference#name) for additional information.
|
|
The following fields are optional:
|
|
- `Tags`
|
|
- `Address`
|
|
- `Meta`
|
|
- `Port`
|
|
|
|
For additional information configuring services, refer to [Service - Agent API](/consul/api-docs/agent/service). 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](https://consul.io/agent).
|
|
|
|
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](/consul/docs/services/usage/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: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-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
|
|
|
|
```json
|
|
{
|
|
"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": "redis",
|
|
"Tags": ["primary", "v1"],
|
|
"Address": "127.0.0.1",
|
|
"TaggedAddresses": {
|
|
"lan": {
|
|
"address": "127.0.0.1",
|
|
"port": 8000
|
|
},
|
|
"wan": {
|
|
"address": "198.18.0.1",
|
|
"port": 80
|
|
}
|
|
},
|
|
"Meta": {
|
|
"redis_version": "4.0"
|
|
},
|
|
"Port": 8000,
|
|
"Namespace": "default"
|
|
},
|
|
"Check": {
|
|
"Node": "t2.320",
|
|
"CheckID": "service:redis1",
|
|
"Name": "Redis health check",
|
|
"Notes": "Script based health check",
|
|
"Status": "passing",
|
|
"ServiceID": "redis1",
|
|
"Definition": {
|
|
"TCP": "localhost:8888",
|
|
"Interval": "5s",
|
|
"Timeout": "1s",
|
|
"DeregisterCriticalServiceAfter": "30s"
|
|
},
|
|
"Namespace": "default"
|
|
},
|
|
"SkipNodeUpdate": false
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
--data @payload.json \
|
|
--header "X-Consul-Namespace: team-1" \
|
|
http://127.0.0.1:8500/v1/catalog/register
|
|
```
|
|
|
|
## 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](/consul/api-docs/agent) for deregistration as they are simpler and
|
|
perform [anti-entropy](/consul/docs/architecture/anti-entropy).
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------- | ------------------ |
|
|
| `PUT` | `/catalog/deregister` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | -------------------------- |
|
|
| `NO` | `none` | `none` | `node:write,service:write` |
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you deregister.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
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.
|
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the service and checks you deregister.
|
|
This field takes precedence over the `ns` query parameter,
|
|
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
|
|
You can also specify the namespace in the `Service` or `Check` fields;
|
|
if namespaces are specified in multiple places, they must all be the same.
|
|
|
|
### Sample Payloads
|
|
|
|
```json
|
|
{
|
|
"Datacenter": "dc1",
|
|
"Node": "t2.320"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Datacenter": "dc1",
|
|
"Node": "t2.320",
|
|
"CheckID": "service:redis1",
|
|
"Namespace": "team-1"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Datacenter": "dc1",
|
|
"Node": "t2.320",
|
|
"ServiceID": "redis1",
|
|
"Namespace": "team-1"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/catalog/deregister
|
|
```
|
|
|
|
## 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](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `simple` | `none` |
|
|
|
|
The corresponding CLI command is [`consul catalog datacenters`](/consul/commands/catalog/datacenters).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/catalog/datacenters
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
["dc1", "dc2"]
|
|
```
|
|
|
|
## List Nodes
|
|
|
|
This endpoint and returns the nodes registered in a given datacenter.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ---------------- | ------------------ |
|
|
| `GET` | `/catalog/nodes` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `YES` | `all` | `none` | `node:read` |
|
|
|
|
The corresponding CLI command is [`consul catalog nodes`](/consul/commands/catalog/nodes).
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query.
|
|
This parameter defaults to the datacenter of the agent being queried.
|
|
|
|
- `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` uses the agent's node for the sort.
|
|
|
|
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Meta` selector instead.
|
|
This parameter will be removed in a future version of Consul.
|
|
Specifies a desired node metadata key/value pair
|
|
of the form `key:value`. This parameter can be specified multiple times, and
|
|
filters the results to nodes with the specified key/value pairs.
|
|
|
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
|
queries results prior to returning the data.
|
|
|
|
@include 'http-api-query-parms-partition.mdx'
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/catalog/nodes
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
"Node": "baz",
|
|
"Address": "10.1.10.11",
|
|
"Datacenter": "dc1",
|
|
"TaggedAddresses": {
|
|
"lan": "10.1.10.11",
|
|
"wan": "10.1.10.11"
|
|
},
|
|
"Meta": {
|
|
"instance_type": "t2.medium"
|
|
}
|
|
},
|
|
{
|
|
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
|
"Node": "t2.320",
|
|
"Address": "10.1.10.12",
|
|
"Datacenter": "dc2",
|
|
"TaggedAddresses": {
|
|
"lan": "10.1.10.11",
|
|
"wan": "10.1.10.12"
|
|
},
|
|
"Meta": {
|
|
"instance_type": "t2.large"
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
### Filtering
|
|
|
|
The filter will be executed against each Node in the result list with
|
|
the following selectors and filter operations being supported:
|
|
|
|
| Selector | Supported Operations |
|
|
| ----------------------- | -------------------------------------------------- |
|
|
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Meta` | Is Empty, Is Not Empty, In, Not In |
|
|
| `Meta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
|
| `TaggedAddresses.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
|
|
## List Services
|
|
|
|
This endpoint returns the services registered in a given datacenter.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------- | ------------------ |
|
|
| `GET` | `/catalog/services` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | -------------------- | -------------- |
|
|
| `YES` | `all` | `background refresh` | `service:read` |
|
|
|
|
The corresponding CLI command is [`consul catalog services`](/consul/commands/catalog/services).
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
the datacenter of the agent being queried.
|
|
|
|
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `NodeMeta` selector instead.
|
|
This parameter will be removed in a future version of Consul.
|
|
Specifies a desired node metadata key/value pair
|
|
of the form `key:value`. This parameter can be specified multiple times, and
|
|
filters the results to nodes with the specified key/value pairs.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
|
queries results prior to returning the data.
|
|
|
|
@include 'http-api-query-parms-partition.mdx'
|
|
|
|
### Filtering
|
|
|
|
The filter will be executed against each Service mapping within the catalog.
|
|
The following selectors and filter operations are supported:
|
|
|
|
| Selector | Supported Operations |
|
|
| ---------------------------------------------------- | -------------------------------------------------- |
|
|
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `NodeMeta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `NodeMeta` | Is Empty, Is Not Empty, In, Not In |
|
|
| `ServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceConnect.Native` | Equal, Not Equal |
|
|
| `ServiceEnableTagOverride` | Equal, Not Equal |
|
|
| `ServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceKind` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceMeta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceMeta` | Is Empty, Is Not Empty, In, Not In |
|
|
| `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServicePort` | Equal, Not Equal |
|
|
| `ServiceProxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.LocalServicePort` | Equal, Not Equal |
|
|
| `ServiceProxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
|
|
| `ServiceProxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.LocalBindPort` | Equal, Not Equal |
|
|
| `ServiceProxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams` | Is Empty, Is Not Empty |
|
|
| `ServiceTaggedAddresses.<any>.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceTaggedAddresses.<any>.Port` | Equal, Not Equal |
|
|
| `ServiceTaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
|
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
|
|
| `ServiceWeights.Passing` | Equal, Not Equal |
|
|
| `ServiceWeights.Warning` | Equal, Not Equal |
|
|
| `TaggedAddresses.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/catalog/services?ns=foo
|
|
```
|
|
|
|
### 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.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------------------- | ------------------ |
|
|
| `GET` | `/catalog/service/:service_name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | -------------------- | ------------------------ |
|
|
| `YES` | `all` | `background refresh` | `node:read,service:read` |
|
|
|
|
### Path Parameters
|
|
|
|
- `service_name` `(string: <required>)` - Specifies the name of the service for which
|
|
to list nodes.
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
the datacenter of the agent being queried.
|
|
|
|
- `tag` `(string: "")` **Deprecated** - Use `filter` with the `ServiceTags` selector instead.
|
|
This parameter will be removed in a future version of Consul.
|
|
Specifies the tag to filter on.
|
|
Can be used multiple times for additional filtering,
|
|
returning only the results that include all of the tag values provided.
|
|
|
|
- `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` uses the agent's node for the sort.
|
|
|
|
- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `NodeMeta` selector instead.
|
|
This parameter will be removed in a future version of Consul.
|
|
Specifies a desired node metadata key/value pair
|
|
of the form `key:value`. This parameter can be specified multiple times, and
|
|
filters the results to nodes with the specified key/value pairs.
|
|
|
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
|
queries results prior to returning the data.
|
|
|
|
- `merge-central-config` - Include this flag in a request for `connect-proxy` kind or `*-gateway` kind
|
|
services to return a fully resolved service definition that includes merged values from the
|
|
[proxy-defaults/global](/consul/docs/connect/config-entries/proxy-defaults) and
|
|
[service-defaults/:service](/consul/docs/connect/config-entries/service-defaults) config entries.
|
|
Returning a fully resolved service definition is useful when a service was registered using the
|
|
[/catalog/register](/consul/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/catalog/service/web?ns=default
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
"Node": "t2.320",
|
|
"Address": "192.168.10.10",
|
|
"Datacenter": "dc1",
|
|
"TaggedAddresses": {
|
|
"lan": "192.168.10.10",
|
|
"wan": "10.0.10.10"
|
|
},
|
|
"NodeMeta": {
|
|
"somekey": "somevalue"
|
|
},
|
|
"CreateIndex": 51,
|
|
"ModifyIndex": 51,
|
|
"ServiceAddress": "172.17.0.3",
|
|
"ServiceEnableTagOverride": false,
|
|
"ServiceID": "32a2a47f7992:nodea:5000",
|
|
"ServiceName": "web",
|
|
"ServicePort": 5000,
|
|
"ServiceMeta": {
|
|
"web_meta_value": "baz"
|
|
},
|
|
"ServiceTaggedAddresses": {
|
|
"lan": {
|
|
"address": "172.17.0.3",
|
|
"port": 5000
|
|
},
|
|
"wan": {
|
|
"address": "198.18.0.1",
|
|
"port": 512
|
|
}
|
|
},
|
|
"ServiceTags": ["prod"],
|
|
"ServiceProxy": {
|
|
"DestinationServiceName": "",
|
|
"DestinationServiceID": "",
|
|
"LocalServiceAddress": "",
|
|
"LocalServicePort": 0,
|
|
"Config": null,
|
|
"Upstreams": null
|
|
},
|
|
"ServiceConnect": {
|
|
"Native": false,
|
|
"Proxy": null
|
|
},
|
|
"Namespace": "default"
|
|
}
|
|
]
|
|
```
|
|
|
|
- `Address` is the IP address of the Consul node on which the service is
|
|
registered.
|
|
|
|
- `Datacenter` is the data center of the Consul node on which the service is
|
|
registered.
|
|
|
|
- `TaggedAddresses` is the list of explicit LAN and WAN IP addresses for the
|
|
agent
|
|
|
|
- `NodeMeta` is a list of user-defined metadata key/value pairs for the node
|
|
|
|
- `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
|
|
|
|
- `ServiceMeta` is a list of user-defined metadata key/value pairs for the service
|
|
|
|
- `ServicePort` is the port number of the service
|
|
|
|
- `ServiceTags` is a list of tags for the service
|
|
|
|
- `ServiceTaggedAddresses` is the map of explicit LAN and WAN addresses for the
|
|
service instance. This includes both the address as well as the port.
|
|
|
|
- `ServiceKind` is the kind of service, usually "". See the Agent
|
|
[service registration API](/consul/api-docs/agent/service#kind) for more information.
|
|
|
|
- `ServiceProxy` is the proxy config as specified in
|
|
[service mesh Proxies](/consul/docs/connect/proxies).
|
|
|
|
- `ServiceConnect` are the [service mesh](/consul/docs/connect) settings. The
|
|
value of this struct is equivalent to the `Connect` field for service
|
|
registration.
|
|
|
|
- `Namespace` is the Consul Enterprise namespace of this service instance
|
|
|
|
### Filtering
|
|
|
|
Filtering is executed against each entry in the top level result list with the
|
|
following selectors and filter operations being supported:
|
|
|
|
| Selector | Supported Operations |
|
|
| ---------------------------------------------------- | -------------------------------------------------- |
|
|
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `NodeMeta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `NodeMeta` | Is Empty, Is Not Empty, In, Not In |
|
|
| `ServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceConnect.Native` | Equal, Not Equal |
|
|
| `ServiceEnableTagOverride` | Equal, Not Equal |
|
|
| `ServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceKind` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceMeta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceMeta` | Is Empty, Is Not Empty, In, Not In |
|
|
| `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServicePort` | Equal, Not Equal |
|
|
| `ServiceProxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.LocalServicePort` | Equal, Not Equal |
|
|
| `ServiceProxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
|
|
| `ServiceProxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams.LocalBindPort` | Equal, Not Equal |
|
|
| `ServiceProxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceProxy.Upstreams` | Is Empty, Is Not Empty |
|
|
| `ServiceTaggedAddresses.<any>.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `ServiceTaggedAddresses.<any>.Port` | Equal, Not Equal |
|
|
| `ServiceTaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
|
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
|
|
| `ServiceWeights.Passing` | Equal, Not Equal |
|
|
| `ServiceWeights.Warning` | Equal, Not Equal |
|
|
| `TaggedAddresses.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
|
|
|
## List Nodes for Mesh-capable Service
|
|
|
|
This endpoint returns the nodes providing a
|
|
[mesh-capable](/consul/docs/connect) service in a given datacenter.
|
|
This will include both proxies and native integrations. A service may
|
|
register both mesh-capable and incapable services at the same time,
|
|
so this endpoint may be used to filter only the mesh-capable endpoints.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------------------- | ------------------ |
|
|
| `GET` | `/catalog/connect/:service` | `application/json` |
|
|
|
|
Parameters and response format are the same as
|
|
[`/catalog/service/:service_name`](/consul/api-docs/catalog#list-nodes-for-service).
|
|
|
|
## Retrieve Map of Services for a Node
|
|
|
|
This endpoint returns the node's registered services.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------------- | ------------------ |
|
|
| `GET` | `/catalog/node/:node_name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------------------ |
|
|
| `YES` | `all` | `none` | `node:read,service:read` |
|
|
|
|
### Path Parameters
|
|
|
|
- `node_name` `(string: <required>)` - Specifies the name of the node to list services for.
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
the datacenter of the agent being queried.
|
|
|
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
|
queries results prior to returning the data.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/catalog/node/my-node
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Node": {
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
"Node": "t2-node",
|
|
"Address": "10.1.10.12",
|
|
"Datacenter": "dc1",
|
|
"TaggedAddresses": {
|
|
"lan": "10.1.10.12",
|
|
"wan": "10.1.10.12"
|
|
},
|
|
"Meta": {
|
|
"instance_type": "t2.medium"
|
|
}
|
|
},
|
|
"Services": {
|
|
"consul": {
|
|
"ID": "consul",
|
|
"Service": "consul",
|
|
"Tags": null,
|
|
"Meta": {},
|
|
"Port": 8300
|
|
},
|
|
"redis": {
|
|
"ID": "redis",
|
|
"Service": "redis",
|
|
"TaggedAddresses": {
|
|
"lan": {
|
|
"address": "10.1.10.12",
|
|
"port": 8000
|
|
},
|
|
"wan": {
|
|
"address": "198.18.1.2",
|
|
"port": 80
|
|
}
|
|
},
|
|
"Tags": ["v1"],
|
|
"Meta": {
|
|
"redis_version": "4.0"
|
|
},
|
|
"Port": 8000,
|
|
"Namespace": "default"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Filtering
|
|
|
|
The filter will be executed against each value in the `Services` mapping within the
|
|
top level Node object. The following selectors and filter operations are supported:
|
|
|
|
| Selector | Supported Operations |
|
|
| --------------------------------------------- | -------------------------------------------------- |
|
|
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Connect.Native` | Equal, Not Equal |
|
|
| `EnableTagOverride` | Equal, Not Equal |
|
|
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Meta` | Is Empty, Is Not Empty, In, Not In |
|
|
| `Meta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Port` | Equal, Not Equal |
|
|
| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.LocalServicePort` | Equal, Not Equal |
|
|
| `Proxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
|
|
| `Proxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams` | Is Empty, Is Not Empty |
|
|
| `Proxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal |
|
|
| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
|
| `TaggedAddresses.<any>.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `TaggedAddresses.<any>.Port` | Equal, Not Equal |
|
|
| `Tags` | In, Not In, Is Empty, Is Not Empty |
|
|
| `Weights.Passing` | Equal, Not Equal |
|
|
| `Weights.Warning` | Equal, Not Equal |
|
|
|
|
## List Services for Node
|
|
|
|
This endpoint returns the node's registered services.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------------------------------- | ------------------ |
|
|
| `GET` | `/catalog/node-services/:node_name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------------------ |
|
|
| `YES` | `all` | `none` | `node:read,service:read` |
|
|
|
|
### Path Parameters
|
|
|
|
- `node_name` `(string: <required>)` - Specifies the name of the node to list services for.
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
the datacenter of the agent being queried.
|
|
|
|
- `filter` `(string: "")` - Specifies the expression used to filter the
|
|
queries results prior to returning the data.
|
|
|
|
- `merge-central-config` - Include this flag in a request for `connect-proxy` kind or `*-gateway` kind
|
|
services to return a fully resolved service definition that includes merged values from the
|
|
[proxy-defaults/global](/consul/docs/connect/config-entries/proxy-defaults) and
|
|
[service-defaults/:service](/consul/docs/connect/config-entries/service-defaults) config entries.
|
|
Returning a fully resolved service definition is useful when a service was registered using the
|
|
[/catalog/register](/consul/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
|
|
The namespace may be specified as '\*' to return results for all namespaces.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/catalog/node-services/t2-node
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Node": {
|
|
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
|
|
"Node": "t2-node",
|
|
"Address": "10.1.10.12",
|
|
"Datacenter": "dc1",
|
|
"TaggedAddresses": {
|
|
"lan": "10.1.10.12",
|
|
"wan": "10.1.10.12"
|
|
},
|
|
"Meta": {
|
|
"instance_type": "t2.medium"
|
|
}
|
|
},
|
|
"Services": [
|
|
{
|
|
"ID": "consul",
|
|
"Service": "consul",
|
|
"Tags": null,
|
|
"Meta": {},
|
|
"Port": 8300
|
|
},
|
|
{
|
|
"ID": "redis",
|
|
"Service": "redis",
|
|
"TaggedAddresses": {
|
|
"lan": {
|
|
"address": "10.1.10.12",
|
|
"port": 8000
|
|
},
|
|
"wan": {
|
|
"address": "198.18.1.2",
|
|
"port": 80
|
|
}
|
|
},
|
|
"Tags": [
|
|
"v1"
|
|
],
|
|
"Meta": {
|
|
"redis_version": "4.0"
|
|
},
|
|
"Port": 8000,
|
|
"Namespace": "default"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Filtering
|
|
|
|
The filter will be executed against each value in the `Services` list within the
|
|
top level object. The following selectors and filter operations are supported:
|
|
|
|
| Selector | Supported Operations |
|
|
| --------------------------------------------- | -------------------------------------------------- |
|
|
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Connect.Native` | Equal, Not Equal |
|
|
| `EnableTagOverride` | Equal, Not Equal |
|
|
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Meta` | Is Empty, Is Not Empty, In, Not In |
|
|
| `Meta.<any>` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Port` | Equal, Not Equal |
|
|
| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.LocalServicePort` | Equal, Not Equal |
|
|
| `Proxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
|
|
| `Proxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams` | Is Empty, Is Not Empty |
|
|
| `Proxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal |
|
|
| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In |
|
|
| `TaggedAddresses.<any>.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
|
|
| `TaggedAddresses.<any>.Port` | Equal, Not Equal |
|
|
| `Tags` | In, Not In, Is Empty, Is Not Empty |
|
|
| `Weights.Passing` | Equal, Not Equal |
|
|
| `Weights.Warning` | Equal, Not Equal |
|
|
|
|
## List Services for Gateway
|
|
|
|
-> **1.8.0+:** This API is available in Consul versions 1.8.0 and later.
|
|
|
|
This endpoint returns the services associated with an ingress gateway or terminating gateway.
|
|
|
|
@include 'http_api_results_filtered_by_acls.mdx'
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------------------ | ------------------ |
|
|
| `GET` | `/catalog/gateway-services/:gateway` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | -------------- |
|
|
| `YES` | `all` | `none` | `service:read` |
|
|
|
|
### Path Parameters
|
|
|
|
- `gateway` `(string: <required>)` - Specifies the name of the node to list services for.
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query.
|
|
This parameter defaults to the datacenter of the agent being queried.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the services you lookup.
|
|
The namespace may be specified as '\*' to return results for all namespaces.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/catalog/gateway-services/my-terminating-gateway
|
|
```
|
|
|
|
### Sample Responses
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Gateway": {
|
|
"Name": "my-terminating-gateway",
|
|
"Namespace": "default"
|
|
},
|
|
"Service": {
|
|
"Name": "api",
|
|
"Namespace": "frontend"
|
|
},
|
|
"GatewayKind": "terminating-gateway",
|
|
"CAFile": "/etc/certs/ca.pem",
|
|
"CertFile": "/etc/certs/api/client.pem",
|
|
"KeyFile": "/etc/certs/api/client.key",
|
|
"SNI": "api.my-domain",
|
|
"CreateIndex": 16,
|
|
"ModifyIndex": 16
|
|
},
|
|
{
|
|
"Gateway": {
|
|
"Name": "my-terminating-gateway",
|
|
"Namespace": "default"
|
|
},
|
|
"Service": {
|
|
"Name": "web",
|
|
"Namespace": "frontend"
|
|
},
|
|
"GatewayKind": "terminating-gateway",
|
|
"CreateIndex": 17,
|
|
"ModifyIndex": 17
|
|
}
|
|
]
|
|
```
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Gateway": {
|
|
"Name": "my-ingress-gateway",
|
|
"Namespace": "default"
|
|
},
|
|
"Service": {
|
|
"Name": "api",
|
|
"Namespace": "frontend"
|
|
},
|
|
"GatewayKind": "ingress-gateway",
|
|
"Port": 8888,
|
|
"Protocol": "http",
|
|
"Hosts": ["api.mydomain.com"],
|
|
"CreateIndex": 15,
|
|
"ModifyIndex": 15
|
|
},
|
|
{
|
|
"Gateway": {
|
|
"Name": "my-ingress-gateway",
|
|
"Namespace": "default"
|
|
},
|
|
"Service": {
|
|
"Name": "redis",
|
|
"Namespace": "ops"
|
|
},
|
|
"GatewayKind": "ingress-gateway",
|
|
"Port": 8443,
|
|
"Protocol": "tcp",
|
|
"CreateIndex": 16,
|
|
"ModifyIndex": 16
|
|
}
|
|
]
|
|
```
|
|
|
|
- `Gateway.Name` is the name of the gateway service of the request
|
|
|
|
- `Gateway.Namespace` is the Consul Enterprise namespace of the gateway
|
|
|
|
- `Service.Name` is the name of a service associated with the gateway
|
|
|
|
- `Service.Namespace` is the Consul Enterprise namespace of a service associated with the gateway
|
|
|
|
- `GatewayKind` is the kind of service, will be one of "ingress-gateway" or "terminating-gateway". See the Agent
|
|
[service registration API](/consul/api-docs/agent/service#kind) for more information.
|
|
|
|
- `CAFile` is the path to a CA file the gateway will use for TLS origination to the associated service
|
|
|
|
- `CertFile` is the path to a client certificate the gateway will use for TLS origination to the associated service
|
|
|
|
- `KeyFile` is the path to a key file the gateway will use for TLS origination to the associated service
|
|
|
|
- `SNI` is a hostname or domain name the gateway will specify during the TLS handshake with the associated service
|
|
|
|
- `Port` is the port the ingress gateway is listening on for the associated service
|
|
|
|
- `Protocol` is the protocol of the ingress gateway's listener for the associated service
|
|
|
|
- `Hosts` list of hosts that specify what requests will match to this associated service
|
|
|
|
- `FromWildcard` determines whether the service was associated with the gateway by providing a wildcard specifier
|
|
in the gateway's configuration entry
|
|
|
|
## Methods to specify namespace <EnterpriseAlert inline />
|
|
|
|
Catalog endpoints
|
|
support several methods for specifying the namespace of resources
|
|
with the following order of precedence:
|
|
1. `Namespace` field of the JSON request body -
|
|
only applies to the [register entity](#register-entity) endpoint
|
|
1. `ns` query parameter
|
|
1. `X-Consul-Namespace` request header
|
|
1. Namespace is inherited from the namespace of the request's ACL token (if any)
|
|
1. The `default` namespace
|