status-im/consul
2
0
Fork 0
mirror of https://github.com/status-im/consul.git synced 2025-02-18 16:46:36 +00:00
Code Issues Projects Releases Wiki Activity
consul/website/source/api/agent/service.html.md
Paul Banks 88388d760d Support Agent Caching for Service Discovery Results (#4541) 
* Add cache types for catalog/services and health/services and basic test that caching works

* Support non-blocking cache types with Cache-Control semantics.

* Update API docs to include caching info for every endpoint.

* Comment updates per PR feedback.

* Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear.

* Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-10-10 16:55:34 +01:00

285 lines
11 KiB
Markdown
Raw Blame History

---
layout: api
page_title: Service - Agent - HTTP API
sidebar_current: api-agent-service
description: |-
The /agent/service endpoints interact with services on the local agent in
Consul.
---
# Service - Agent HTTP API
The `/agent/service` endpoints interact with checks on the local agent in
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
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
everything will be in sync within a few seconds.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/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),
[agent caching](/api/index.html#agent-caching), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------- |
| `NO` | `none` | `none` | `service:read` |
### Sample Request
```text
$ curl \
http://127.0.0.1:8500/v1/agent/services
```
### Sample Response
```json
{
"redis": {
"ID": "redis",
"Service": "redis",
"Tags": [],
"Address": "",
"Meta": {
"redis_version": "4.0"
},
"Port": 8000
}
}
```
## Register Service
This endpoint adds a new service, with an optional health check, to the local
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
`ProxyDestination` value is also required to register the service.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/service/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),
[agent caching](/api/index.html#agent-caching), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies the logical name of the service.
Many service instances may share the same logical service name.
- `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.
- `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.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the service instance.
- `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
services that are [Connect-capable](/docs/connect/index.html)
proxies representing another service.
- `ProxyDestination` `(string: "")` - For "connect-proxy" `Kind` services,
this must be set to the name of the service that the proxy represents. This
service doesn't need to be registered, but the caller must have an ACL token
with permissions for this service.
- `Connect` `(Connect: nil)` - Specifies the configuration for
[Connect](/docs/connect/index.html). See the [Connect structure](#connect-structure)
section for supported fields.
- `Check` `(Check: nil)` - Specifies a check. Please see the
[check documentation](/api/agent/check.html) 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
[check documentation](/api/agent/check.html) 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
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.
- `EnableTagOverride` `(bool: false)` - Specifies to disable the anti-entropy
feature for this service's tags. If `EnableTagOverride` is set to `true` then
external agents can update this service in the [catalog](/api/catalog.html)
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.
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
`false`. See [anti-entropy syncs](/docs/internals/anti-entropy.html) for
more info.
#### Connect Structure
For the `Connect` field, the parameters are:
- `Native` `(bool: false)` - Specifies whether this service supports
the [Connect](/docs/connect/index.html) protocol [natively](/docs/connect/native.html).
If this is true, then Connect proxies, DNS queries, etc. will be able to
service discover this service.
### Sample Payload
```json
{
"ID": "redis1",
"Name": "redis",
"Tags": [
"primary",
"v1"
],
"Address": "127.0.0.1",
"Port": 8000,
"Meta": {
"redis_version": "4.0"
},
"EnableTagOverride": false,
"Check": {
"DeregisterCriticalServiceAfter": "90m",
"Args": ["/usr/local/bin/check_redis.py"],
"HTTP": "http://localhost:5000/health",
"Interval": "10s",
"TTL": "15s"
}
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/service/register
```
## 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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/service/deregister/:service_id` | `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),
[agent caching](/api/index.html#agent-caching), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` |
### Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to
deregister. This is specified as part of the URL.
### Sample Request
```text
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/service/deregister/my-service-id
```
## 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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/service/maintenance/:service_id` | `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),
[agent caching](/api/index.html#agent-caching), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | --------------- |
| `NO` | `none` | `none` | `service:write` |
### 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.
- `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
```text
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs
```
Reference in New Issue View Git Blame Copy Permalink