From 1027a01a102a7a02a6edfc31062ea0a351314501 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 12 Jul 2018 21:14:36 -0700 Subject: [PATCH] website: document alias check --- website/source/api/agent/check.html.md | 10 +++++++++ website/source/docs/agent/checks.html.md | 28 ++++++++++++++++++++++-- 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/website/source/api/agent/check.html.md b/website/source/api/agent/check.html.md index 052693335a..326811eea9 100644 --- a/website/source/api/agent/check.html.md +++ b/website/source/api/agent/check.html.md @@ -116,6 +116,16 @@ The table below shows this endpoint's support for continue to be accepted in future versions of Consul), and `Args` in Consul 1.0.1 and later. +- `AliasNode` `(string: "")` - Specifies the ID of the node for an alias check. + If no service is specified, the check will alias the health of the node. + If a service is specified, the check will alias the specified service on + this particular node. + +- `AliasService` `(string: "")` - Specifies the ID of a service for an + alias check. If the service is not registered with the same agent, + `AliasNode` must also be specified. Note this is the service _ID_ and + not the service _name_ (though they are very often the same). + - `DockerContainerID` `(string: "")` - Specifies that the check is a Docker check, and Consul will evaluate the script every `Interval` in the given container using the specified `Shell`. Note that `Shell` is currently only diff --git a/website/source/docs/agent/checks.html.md b/website/source/docs/agent/checks.html.md index a563de5778..45d2f7cbd7 100644 --- a/website/source/docs/agent/checks.html.md +++ b/website/source/docs/agent/checks.html.md @@ -101,6 +101,17 @@ There are several different kinds of checks: TLS certificate is expected. Certificate verification can be turned off by setting the `tls_skip_verify` field to `true` in the check definition. +* Alias - These checks alias the health state another Consul + node or service. The state of the check will be updated asynchronously, + but is nearly instant. For aliased services on the same agent, the local + state is monitored and no additional network resources are consumed. For + other services and nodes, the check maintains a blocking query over the + agent's connection with a current server and allows stale requests. If there + are any errors in watching the aliased node or service, the check will be + unhealthy. For the blocking query, the check will use the ACL token set + on the service definition, otherwise falling back to the default ACL + token set with the agent (`acl_token`). + ## Check Definition A script check: @@ -165,7 +176,7 @@ A Docker check: ```javascript { -"check": { + "check": { "id": "mem-util", "name": "Memory utilization", "docker_container_id": "f972c95ebf0e", @@ -180,7 +191,7 @@ A gRPC check: ```javascript { -"check": { + "check": { "id": "mem-util", "name": "Service health status", "grpc": "127.0.0.1:12345", @@ -190,6 +201,17 @@ A gRPC check: } ``` +An alias check for a local service: + +```javascript +{ + "check": { + "id": "web-alias", + "alias_service": "web" + } +} +``` + Each type of definition must include a `name` and may optionally provide an `id` and `notes` field. The `id` must be unique per _agent_ otherwise only the last defined check with that `id` will be registered. If the `id` is not set @@ -205,6 +227,8 @@ a TTL check via the HTTP interface can set the `notes` value. Checks may also contain a `token` field to provide an ACL token. This token is used for any interaction with the catalog for the check, including [anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. +For Alias checks, this token is used if a remote blocking query is necessary +to watch the state of the aliased node or service. Script, TCP, HTTP, Docker, and gRPC checks must include an `interval` field. This field is parsed by Go's `time` package, and has the following