open-consul/website/content/api-docs/agent/service.mdx

837 lines
30 KiB
Plaintext
Raw Normal View History

2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Service - Agent - HTTP API
description: |-
The /agent/service endpoints interact with services on the local agent in
Consul.
---
# Service - Agent HTTP API
2018-10-11 17:48:51 +00:00
The `/agent/service` endpoints interact with services on the local agent in
2017-04-04 16:33:22 +00:00
Consul. These should not be confused with services in the catalog.
## List Services
This endpoint returns all the services that are registered with
the local agent. These services were either provided through configuration files
or added dynamically using the HTTP API.
It is important to note that the services known by the agent may be different
from those reported by the catalog. This is usually due to changes being made
while there is no leader elected. The agent performs active
2020-04-09 23:46:54 +00:00
[anti-entropy](/docs/internals/anti-entropy), so in most situations
2017-04-04 16:33:22 +00:00
everything will be in sync within a few seconds.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `GET` | `/agent/services` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `NO` | `none` | `none` | `service:read` |
2017-04-04 16:33:22 +00:00
### Parameters
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which
to list services. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
2017-04-04 16:33:22 +00:00
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/agent/services
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
{
"redis": {
2020-04-06 20:27:35 +00:00
"ID": "redis",
"Service": "redis",
"Tags": [],
"TaggedAddresses": {
"lan": {
"address": "127.0.0.1",
"port": 8000
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
},
2020-04-06 20:27:35 +00:00
"wan": {
"address": "198.51.100.53",
2020-04-06 20:27:35 +00:00
"port": 80
}
2020-04-06 20:27:35 +00:00
},
"Meta": {
"redis_version": "4.0"
},
"Namespace": "default",
2020-04-06 20:27:35 +00:00
"Port": 8000,
"Address": "",
"EnableTagOverride": false,
"Datacenter": "dc1",
2020-04-06 20:27:35 +00:00
"Weights": {
"Passing": 10,
"Warning": 1
}
2017-04-04 16:33:22 +00:00
}
}
```
### Filtering
The filter is executed against each value in the service mapping with the
following selectors and filter operations being 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 |
## Get Service Configuration
This endpoint was added in Consul 1.3.0 and returns the full service definition
for a single service instance registered on the local agent. It is used by
2020-04-09 23:46:54 +00:00
[Connect proxies](/docs/connect/proxies) to discover the embedded proxy
configuration that was registered with the instance.
It is important to note that the services known by the agent may be different
from those reported by the catalog. This is usually due to changes being made
while there is no leader elected. The agent performs active
2020-04-09 23:46:54 +00:00
[anti-entropy](/docs/internals/anti-entropy), so in most situations
everything will be in sync within a few seconds.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ---------------------------- | ------------------ |
| `GET` | `/agent/service/:service_id` | `application/json` |
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ----------------- | ----------------- | ------------- | -------------- |
| `YES`<sup>1</sup> | `none` | `none` | `service:read` |
<sup>
1
</sup> Supports <a href="/api/features/blocking#hash-based-blocking-queries">
hash-based blocking
</a> only.
### Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to
fetch. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the service's configuration. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
$ curl \
http://127.0.0.1:8500/v1/agent/service/web-sidecar-proxy
```
### Sample Response
```json
{
2020-04-06 20:27:35 +00:00
"Kind": "connect-proxy",
"ID": "web-sidecar-proxy",
"Service": "web-sidecar-proxy",
"Tags": null,
"Meta": null,
"Namespace": "default",
2020-04-06 20:27:35 +00:00
"Port": 18080,
"Address": "",
"TaggedAddresses": {
"lan": {
"address": "127.0.0.1",
"port": 8000
},
2020-04-06 20:27:35 +00:00
"wan": {
"address": "198.51.100.53",
2020-04-06 20:27:35 +00:00
"port": 80
}
2020-04-06 20:27:35 +00:00
},
"Weights": {
"Passing": 1,
"Warning": 1
},
"EnableTagOverride": false,
"Datacenter": "dc1",
2020-04-06 20:27:35 +00:00
"ContentHash": "4ecd29c7bc647ca8",
"Proxy": {
"DestinationServiceName": "web",
"DestinationServiceID": "web",
"LocalServiceAddress": "127.0.0.1",
"LocalServicePort": 8080,
"Mode": "transparent",
"TransparentProxy": {
"OutboundListenerPort": 22500
},
2020-04-06 20:27:35 +00:00
"Config": {
"foo": "bar"
},
"Upstreams": [
{
"DestinationType": "service",
"DestinationName": "db",
"LocalBindPort": 9191
}
]
}
}
```
The response has the same structure as the [service
2020-04-09 23:46:54 +00:00
definition](/docs/agent/services) with one extra field `ContentHash` which
contains the [hash-based blocking
2020-04-09 23:46:54 +00:00
query](/api/features/blocking#hash-based-blocking-queries) hash for the result. The
same hash is also present in `X-Consul-ContentHash`.
## Get local service health
Retrieve an aggregated state of service(s) on the local agent by name.
This endpoints support JSON format and text/plain formats, JSON being the
default. In order to get the text format, you can append `?format=text` to
the URL or use Mime Content negotiation by specifying a HTTP Header
`Accept` starting with `text/plain`.
| Method | Path | Produces |
| ------ | ------------------------------------------------------ | ------------------ |
| `GET` | `/agent/health/service/name/:service_name` | `application/json` |
| `GET` | `/agent/health/service/name/:service_name?format=text` | `text/plain` |
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `NO` | `none` | `none` | `service:read` |
### Parameters
- `service_name` `(string: <required>)` - Specifies the name of the service to
retrieve. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace to lookup
the service's health data. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
Those endpoints return the aggregated values of all health checks for the
service instance(s) and will return the corresponding HTTP codes:
| Result | Meaning |
2020-04-06 20:27:35 +00:00
| ------ | --------------------------------------------------------------- |
| `200` | All health checks of every matching service instance are passing |
| `400` | Bad parameter (missing service name of id) |
| `404` | No such service id or name |
| `429` | Some health checks are passing, at least one is warning |
| `503` | At least one of the health checks is critical |
Those endpoints might be useful for the following use-cases:
2020-04-06 20:27:35 +00:00
- a load-balancer wants to check IP connectivity with an agent and retrieve
the aggregated status of given service
- create aliases for a given service (thus, the health check of alias uses
http://localhost:8500/v1/agent/service/id/aliased_service_id health check)
##### Note
2020-04-06 20:27:35 +00:00
If you know the ID of service you want to target, it is recommended to use
[`/v1/agent/health/service/id/:service_id`](/api/agent/service#get-local-service-health-by-id)
so you have the result for the service only. When requesting
`/v1/agent/health/service/name/:service_name`, the caller will receive the
worst state of all services having the given name.
### Sample Requests
Given 2 services with name `web`, with web2 critical and web1 passing:
#### List the worst status across all instances of the `web` service (HTTP 503)
##### By Name, Text
```shell
$ curl http://localhost:8500/v1/agent/health/service/name/web?format=text
critical
```
##### By Name, JSON
For the JSON output, the response is an array containing the details of each
passing, warning, or critical service.
```shell
curl localhost:8500/v1/agent/health/service/name/web
```
```json
[
{
"AggregatedStatus": "passing",
"Service": {
"ID": "web1",
2020-04-06 20:27:35 +00:00
"Service": "web",
"Tags": [
"rails"
],
"Meta": {},
"Port": 80,
2020-04-06 20:27:35 +00:00
"Address": "",
"SocketPath": "",
2020-04-06 20:27:35 +00:00
"TaggedAddresses": {
"lan": {
"Address": "127.0.0.1",
"Port": 8000
2020-04-06 20:27:35 +00:00
},
"wan": {
"Address": "198.51.100.53",
"Port": 80
}
2020-04-06 20:27:35 +00:00
},
"Weights": {
"Passing": 1,
"Warning": 1
2020-04-06 20:27:35 +00:00
},
"EnableTagOverride": false,
"Namespace": "default",
"Datacenter": "dc1"
},
"Checks": []
},
{
"AggregatedStatus": "critical",
"Service": {
"ID": "web2",
2020-04-06 20:27:35 +00:00
"Service": "web",
"Tags": [
"rails"
],
"Meta": {},
"Port": 80,
2020-04-06 20:27:35 +00:00
"Address": "",
"SocketPath": "",
2020-04-06 20:27:35 +00:00
"TaggedAddresses": {
"lan": {
"Address": "127.0.0.1",
"Port": 8000
2020-04-06 20:27:35 +00:00
},
"wan": {
"Address": "198.51.100.54",
"Port": 80
}
2020-04-06 20:27:35 +00:00
},
"Weights": {
"Passing": 1,
"Warning": 1
2020-04-06 20:27:35 +00:00
},
"EnableTagOverride": false,
"Namespace": "default",
"Datacenter": "dc1"
},
"Checks": [
{
"Node": "server1",
"CheckID": "service:web2",
"Name": "Service 'web' check",
"Status": "critical",
"Notes": "",
"Output": "Get \"http://localhost/health\": dial tcp [::1]:80: connect: connection refused",
"ServiceID": "web2",
"ServiceName": "web",
"ServiceTags": [
"rails"
],
"Type": "",
"Namespace": "default",
"Definition": {
"Interval": "0s",
"Timeout": "0s",
"DeregisterCriticalServiceAfter": "0s",
"HTTP": "",
"Header": null,
"Method": "",
"Body": "",
"TLSServerName": "",
"TLSSkipVerify": false,
"TCP": ""
},
"CreateIndex": 0,
"ModifyIndex": 0
}
]
}
]
```
## Get local service health by ID ((#get-local-service-health-by-its-id))
Retrieve the health state of a specific service on the local agent by ID.
| Method | Path | Produces |
| ------ | -------------------------------------------------- | ------------------ |
| `GET` | `/agent/health/service/id/:service_id` | `application/json` |
| `GET` | `/agent/health/service/id/:service_id?format=text` | `text/plain` |
The supported request parameters are the same as
[`/v1/agent/health/service/name/:service_name`](/api/agent/service#get-local-service-health).
### Sample Requests
Query the health status of the service with ID `web2`.
#### List status of web2 (HTTP 503)
##### Failure By ID, Text
```shell
$ curl http://localhost:8500/v1/agent/health/service/id/web2?format=text
critical
```
##### Failure By ID, JSON
In JSON, the output for a query by ID is an object containing only the details
for that service.
```shell
curl localhost:8500/v1/agent/health/service/id/web2
```
```json
{
"AggregatedStatus": "critical",
"Service": {
2020-04-06 20:27:35 +00:00
"ID": "web2",
"Service": "web",
"Tags": [
"rails"
],
"Meta": {},
"Port": 80,
2020-04-06 20:27:35 +00:00
"Address": "",
"SocketPath": "",
2020-04-06 20:27:35 +00:00
"TaggedAddresses": {
"lan": {
"Address": "127.0.0.1",
"Port": 8000
2020-04-06 20:27:35 +00:00
},
"wan": {
"Address": "198.51.100.54",
"Port": 80
2020-04-06 20:27:35 +00:00
}
},
"Weights": {
"Passing": 1,
"Warning": 1
2020-04-06 20:27:35 +00:00
},
"EnableTagOverride": false,
"Namespace": "default",
"Datacenter": "dc1"
},
"Checks": [
{
"Node": "server1",
"CheckID": "service:web2",
"Name": "Service 'web' check",
"Status": "critical",
"Notes": "",
"Output": "Get \"http://localhost/health\": dial tcp [::1]:80: connect: connection refused",
"ServiceID": "web2",
"ServiceName": "web",
"ServiceTags": [
"rails"
],
"Type": "",
"Namespace": "default",
"Definition": {
"Interval": "0s",
"Timeout": "0s",
"DeregisterCriticalServiceAfter": "0s",
"HTTP": "",
"Header": null,
"Method": "",
"Body": "",
"TLSServerName": "",
"TLSSkipVerify": false,
"TCP": ""
},
"CreateIndex": 0,
"ModifyIndex": 0
}
]
}
```
#### List status of web1 (HTTP 200)
##### Success By ID, Text
```shell
$ curl localhost:8500/v1/agent/health/service/id/web1?format=text
passing
```
#### Success By ID, JSON
```shell
curl localhost:8500/v1/agent/health/service/id/web1
```
```json
{
"AggregatedStatus": "passing",
"Service": {
2020-04-06 20:27:35 +00:00
"ID": "web1",
"Service": "web",
"Tags": [
"rails"
],
"Meta": {},
"Port": 80,
2020-04-06 20:27:35 +00:00
"Address": "",
"SocketPath": "",
2020-04-06 20:27:35 +00:00
"TaggedAddresses": {
"lan": {
"Address": "127.0.0.1",
"Port": 8000
2020-04-06 20:27:35 +00:00
},
"wan": {
"Address": "198.51.100.53",
"Port": 80
2020-04-06 20:27:35 +00:00
}
},
"Weights": {
"Passing": 1,
"Warning": 1
2020-04-06 20:27:35 +00:00
},
"EnableTagOverride": false,
"Namespace": "default",
"Datacenter": "dc1"
},
"Checks": []
}
```
2017-04-04 16:33:22 +00:00
## Register Service
This endpoint adds a new service, with optional health checks, to the local
2017-04-04 16:33:22 +00:00
agent.
The agent is responsible for managing the status of its local services, and for
sending updates about its local services to the servers to keep the global
catalog in sync.
For "connect-proxy" kind services, the `service:write` ACL for the
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
`Proxy.DestinationServiceName` value is also required to register the service.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------------- | ------------------ |
| `PUT` | `/agent/service/register` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` |
2017-04-04 16:33:22 +00:00
### Query string parameters
- `replace-existing-checks` - Missing health checks from the request will be deleted from the agent. Using this parameter allows to idempotently register a service and its checks without having to manually deregister checks.
2017-04-04 16:33:22 +00:00
### Parameters
2020-04-09 23:46:54 +00:00
Note that this endpoint, unlike most also [supports `snake_case`](/docs/agent/services#service-definition-parameter-case)
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
service definition keys for compatibility with the config file format.
2017-04-04 16:33:22 +00:00
- `Name` `(string: <required>)` - Specifies the logical name of the service.
Many service instances may share the same logical service name. We recommend using
[valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames)
2020-04-09 23:46:54 +00:00
for [compatibility with external DNS](/docs/agent/services#service-and-tag-names-with-dns).
2017-04-04 16:33:22 +00:00
- `ID` `(string: "")` - Specifies a unique ID for this service. This must be
unique per _agent_. This defaults to the `Name` parameter if not provided.
- `Tags` `(array<string>: nil)` - Specifies a list of tags to assign to the
service. These tags can be used for later filtering and are exposed via the APIs.
We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames)
2020-04-09 23:46:54 +00:00
for [compatibility with external DNS](/docs/agent/services#service-and-tag-names-with-dns)
2017-04-04 16:33:22 +00:00
- `Address` `(string: "")` - Specifies the address of the service. If not
provided, the agent's address is used as the address for the service during
DNS queries.
- `TaggedAddresses` `(map<string|object>: nil)` - Specifies a map of explicit LAN
and WAN addresses for the service instance. Both the address and port can be
specified within the map values.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the service instance.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in
which to register the service. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
- `Port` `(int: 0)` - Specifies the port of the service.
- `Kind` `(string: "")` - The kind of service. Defaults to "" which is a
typical Consul service. This value may also be "connect-proxy" for
[Connect](/docs/connect) proxies representing another service,
"mesh-gateway" for instances of a [mesh gateway](/docs/connect/mesh-gateway),
"terminating-gateway" for instances of a [terminating gateway](/docs/connect/terminating-gateway),
or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/ingress-gateway).
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
- `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a
Connect service proxy instance. This is only valid if `Kind` defines a proxy or gateway.
See the [Proxy documentation](/docs/connect/registration/service-registration)
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
for full details.
- `Connect` `(Connect: nil)` - Specifies the
2020-04-09 23:46:54 +00:00
[configuration for Connect](/docs/connect/configuration). See the
Add Proxy Upstreams to Service Definition (#4639) * Refactor Service Definition ProxyDestination. This includes: - Refactoring all internal structs used - Updated tests for both deprecated and new input for: - Agent Services endpoint response - Agent Service endpoint response - Agent Register endpoint - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Register - Unmanaged deprecated field - Unmanaged new fields - Managed deprecated upstreams - Managed new - Catalog Services endpoint response - Catalog Node endpoint response - Catalog Service endpoint response - Updated API tests for all of the above too (both deprecated and new forms of register) TODO: - config package changes for on-disk service definitions - proxy config endpoint - built-in proxy support for new fields * Agent proxy config endpoint updated with upstreams * Config file changes for upstreams. * Add upstream opaque config and update all tests to ensure it works everywhere. * Built in proxy working with new Upstreams config * Command fixes and deprecations * Fix key translation, upstream type defaults and a spate of other subtele bugs found with ned to end test scripts... TODO: tests still failing on one case that needs a fix. I think it's key translation for upstreams nested in Managed proxy struct. * Fix translated keys in API registration. ≈ * Fixes from docs - omit some empty undocumented fields in API - Bring back ServiceProxyDestination in Catalog responses to not break backwards compat - this was removed assuming it was only used internally. * Documentation updates for Upstreams in service definition * Fixes for tests broken by many refactors. * Enable travis on f-connect branch in this branch too. * Add consistent Deprecation comments to ProxyDestination uses * Update version number on deprecation notices, and correct upstream datacenter field with explanation in docs
2018-09-12 16:07:47 +00:00
[Connect Structure](#connect-structure) section below for supported fields.
2017-04-04 16:33:22 +00:00
- `Check` `(Check: nil)` - Specifies a check. Please see the
2020-04-09 23:46:54 +00:00
[check documentation](/api/agent/check) for more information about the
accepted fields. If you don't provide a name or id for the check then they
will be generated. To provide a custom id and/or name set the `CheckID`
and/or `Name` field.
- `Checks` `(array<Check>: nil)` - Specifies a list of checks. Please see the
2020-04-09 23:46:54 +00:00
[check documentation](/api/agent/check) for more information about the
accepted fields. If you don't provide a name or id for the check then they
will be generated. To provide a custom id and/or name set the `CheckID`
and/or `Name` field. The automatically generated `Name` and `CheckID` depend
on the position of the check within the array, so even though the behavior is
2017-05-17 18:22:00 +00:00
deterministic, it is recommended for all checks to either let consul set the
`CheckID` by leaving the field empty/omitting it or to provide a unique value.
2017-04-04 16:33:22 +00:00
- `EnableTagOverride` `(bool: false)` - Specifies to disable the anti-entropy
feature for this service's tags. If `EnableTagOverride` is set to `true` then
2020-04-09 23:46:54 +00:00
external agents can update this service in the [catalog](/api/catalog)
2017-04-04 16:33:22 +00:00
and modify the tags. Subsequent local sync operations by this agent will
ignore the updated tags. For instance, if an external agent modified both the
tags and the port for this service and `EnableTagOverride` was set to `true`
then after the next sync cycle the service's port would revert to the original
value but the tags would maintain the updated value. As a counter example, if
an external agent modified both the tags and port for this service and
`EnableTagOverride` was set to `false` then after the next sync cycle the
service's port _and_ the tags would revert to the original value and all
modifications would be lost.
- `Weights` `(Weights: nil)` - Specifies weights for the service. Please see the
2020-04-09 23:46:54 +00:00
[service documentation](/docs/agent/services) for more information about
weights. If this field is not provided weights will default to
`{"Passing": 1, "Warning": 1}`.
2020-04-06 20:27:35 +00:00
It is important to note that this applies only to the locally registered
service. If you have multiple nodes all registering the same service their
`EnableTagOverride` configuration and all other service configuration items
are independent of one another. Updating the tags for the service registered
on one node is independent of the same service (by name) registered on
another node. If `EnableTagOverride` is not specified the default value is
2020-04-09 23:46:54 +00:00
`false`. See [anti-entropy syncs](/docs/internals/anti-entropy) for
2020-04-06 20:27:35 +00:00
more info.
2017-04-04 16:33:22 +00:00
#### Connect Structure
For the `Connect` field, the parameters are:
- `Native` `(bool: false)` - Specifies whether this service supports
2020-04-09 23:46:54 +00:00
the [Connect](/docs/connect) protocol [natively](/docs/connect/native).
If this is true, then Connect proxies, DNS queries, etc. will be able to
service discover this service.
- `Proxy` `(Proxy: nil)` -
2020-04-09 23:46:54 +00:00
[**Deprecated**](/docs/connect/proxies/managed-deprecated) Specifies that
a managed Connect proxy should be started for this service instance, and
optionally provides configuration for the proxy. The format is as documented
2020-04-09 23:46:54 +00:00
in [Managed Proxy Deprecation](/docs/connect/proxies/managed-deprecated).
- `SidecarService` `(ServiceDefinition: nil)` - Specifies an optional nested
service definition to register. For more information see
2020-04-09 23:46:54 +00:00
[Sidecar Service Registration](/docs/connect/registration/sidecar-service).
2017-04-04 16:33:22 +00:00
### Sample Payload
```json
{
"ID": "redis1",
"Name": "redis",
2020-04-06 20:27:35 +00:00
"Tags": ["primary", "v1"],
2017-04-04 16:33:22 +00:00
"Address": "127.0.0.1",
"Port": 8000,
"Meta": {
"redis_version": "4.0"
},
2017-04-04 16:33:22 +00:00
"EnableTagOverride": false,
"Check": {
"DeregisterCriticalServiceAfter": "90m",
"Args": ["/usr/local/bin/check_redis.py"],
2017-04-04 16:33:22 +00:00
"Interval": "10s",
"Timeout": "5s"
},
"Weights": {
"Passing": 10,
"Warning": 1
2017-04-04 16:33:22 +00:00
}
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/service/register?replace-existing-checks=true
2017-04-04 16:33:22 +00:00
```
## Deregister Service
This endpoint removes a service from the local agent. If the service does not
exist, no action is taken.
The agent will take care of deregistering the service with the catalog. If there
is an associated check, that is also deregistered.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------------------------------- | ------------------ |
2017-04-04 16:33:22 +00:00
| `PUT` | `/agent/service/deregister/:service_id` | `application/json` |
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` |
2017-04-04 16:33:22 +00:00
### Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to
deregister. This is specified as part of the URL.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace in which
to deregister the service. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
2017-04-04 16:33:22 +00:00
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/service/deregister/my-service-id
2017-04-04 16:33:22 +00:00
```
## Enable Maintenance Mode
This endpoint places a given service into "maintenance mode". During maintenance
mode, the service will be marked as unavailable and will not be present in DNS
or API queries. This API call is idempotent. Maintenance mode is persistent and
will be automatically restored on agent restart.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ---------------------------------------- | ------------------ |
| `PUT` | `/agent/service/maintenance/:service_id` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` |
2017-04-04 16:33:22 +00:00
### Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to put
in maintenance mode. This is specified as part of the URL.
- `enable` `(bool: <required>)` - Specifies whether to enable or disable
maintenance mode. This is specified as part of the URL as a query string
parameter.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace
of the service to place into maintenance mode. This value can be specified as
the `ns` URL query parameter or the `X-Consul-Namespace` header. If not provided
by either, the namespace will be inherited from the request's ACL token or will
default to the `default` namespace. Added in Consul 1.7.0.
2017-04-04 16:33:22 +00:00
- `reason` `(string: "")` - Specifies a text string explaining the reason for
placing the node into maintenance mode. This is simply to aid human operators.
If no reason is provided, a default value will be used instead. This is
specified as part of the URL as a query string parameter, and, as such, must
be URI-encoded.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs
2017-04-04 16:33:22 +00:00
```