luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Clarify enable_tag_override explanation 

In designing a potential UI for a configuration of `enable_tag_override`,
I found the documentation confusing and lengthy. Here, I've made an
attempt at re-writing this section to be more concise and clear.

I also made a few small changes to the organization of this file to map
explanations to the order of the properties listing at the top. I find
it easier to scan docs when explanations appear in the same order they
are listed at the top. For explanations that span multiple paragraphs, I
provided a subheading, which also helps in linking from other pages.

Finally, I removed a duplicated paragraph from the documentation.
This commit is contained in:
Hannah Oppenheimer 2018-10-05 10:53:27 -05:00 committed by Hannah Oppenheimer
parent 9045f77359
commit 29170340b3
2 changed files with 51 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
website/source/docs/agent/services.html.md
View File

@ -62,15 +62,11 @@ example shows all possible fields, but note that only a few are required.
``` ```
A service definition must include a `name` and may optionally provide an A service definition must include a `name` and may optionally provide an
`id`, `tags`, `address`, `port`, `check`, `meta` and `enable_tag_override`. `id`, `tags`, `address`, `meta`, `port`, `enable_tag_override`, and `check`.
The `id` is set to the `name` if not provided. It is required that all The `id` is set to the `name` if not provided. It is required that all
services have a unique ID per node, so if names might conflict then services have a unique ID per node, so if names might conflict then
unique IDs should be provided. unique IDs should be provided.
For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
supports both `enable_tag_override` and `enableTagOverride` but the latter is
deprecated and has been removed in Consul 1.1.
The `tags` property is a list of values that are opaque to Consul but The `tags` property is a list of values that are opaque to Consul but
can be used to distinguish between `primary` or `secondary` nodes, can be used to distinguish between `primary` or `secondary` nodes,
different versions, or any other service level labels. different versions, or any other service level labels.
@ -89,55 +85,6 @@ meta object in node definition.
All those meta data can be retrieved individually per instance of the service All those meta data can be retrieved individually per instance of the service
and all the instances of a given service have their own copy of it. and all the instances of a given service have their own copy of it.
Services may also contain a `token` field to provide an ACL token. This token is
used for any interaction with the catalog for the service, including
[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration.
A service can have an associated health check. This is a powerful feature as
it allows a web balancer to gracefully remove failing nodes, a database
to replace a failed secondary, etc. The health check is strongly integrated in
the DNS interface as well. If a service is failing its health check or a
node has any failing system-level check, the DNS interface will omit that
node from any service query.
The check must be of the script, HTTP, TCP or TTL type. If it is a script type,
`args` and `interval` must be provided. If it is a HTTP type, `http` and
`interval` must be provided. If it is a TCP type, `tcp` and `interval` must be
provided. If it is a TTL type, then only `ttl` must be provided. The check name
is automatically generated as `service:<service-id>`. If there are multiple
service checks registered, the ID will be generated as
`service:<service-id>:<num>` where `<num>` is an incrementing number starting
from `1`.
-> **Note:** There is more information about [checks here](/docs/agent/checks.html).
The `enable_tag_override` can optionally be specified to disable the
anti-entropy feature for this service. If `enable_tag_override` 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
example, if an external agent modified both the tags and the port for
this service and `enable_tag_override` 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
`enable_tag_override` 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's important to note that this applies only to the locally registered
service. If you have multiple nodes all registering the same service
their `enable_tag_override` 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 `enable_tag_override` is
not specified the default value is false. See [anti-entropy
syncs](/docs/internals/anti-entropy.html) for more info.
For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
supports both `enable_tag_override` and `enableTagOverride` but the latter is
deprecated and has been removed as of Consul 1.1.
The `kind` field is used to optionally identify the service as an [unmanaged The `kind` field is used to optionally identify the service as an [unmanaged
Connect proxy](/docs/connect/proxies.html#unmanaged-proxies) instance with the Connect proxy](/docs/connect/proxies.html#unmanaged-proxies) instance with the
value `connect-proxy`. For typical non-proxy instances the `kind` field must be value `connect-proxy`. For typical non-proxy instances the `kind` field must be
@ -168,6 +115,53 @@ This allows some instances to be given higher weight if they have more capacity,
and optionally allows reducing load on services with checks in `warning` status and optionally allows reducing load on services with checks in `warning` status
by giving passing instances a higher weight. by giving passing instances a higher weight.
### Checks
A service can have an associated health check. This is a powerful feature as
it allows a web balancer to gracefully remove failing nodes, a database
to replace a failed secondary, etc. The health check is strongly integrated in
the DNS interface as well. If a service is failing its health check or a
node has any failing system-level check, the DNS interface will omit that
node from any service query.
The check must be of the script, HTTP, TCP or TTL type. If it is a script type,
`args` and `interval` must be provided. If it is a HTTP type, `http` and
`interval` must be provided. If it is a TCP type, `tcp` and `interval` must be
provided. If it is a TTL type, then only `ttl` must be provided. The check name
is automatically generated as `service:<service-id>`. If there are multiple
service checks registered, the ID will be generated as
`service:<service-id>:<num>` where `<num>` is an incrementing number starting
from `1`.
-> **Note:** There is more information about [checks here](/docs/agent/checks.html).
### Enable Tag Override and Anti-Entropy
Services may also contain a `token` field to provide an ACL token. This token is
used for any interaction with the catalog for the service, including
[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration.
You can optionally disable the anti-entropy feature for this service using the
`enable_tag_override` flag. External agents can modify tags on services in the
catalog, so subsequent sync operations can either maintain tag modifications or
revert them. If `enable_tag_override` is set to `TRUE`, the next sync cycle may
revert some service properties, **but** the tags would maintain the updated value.
If `enable_tag_override` is set to `FALSE`, the next sync cycle will revert any
updated service properties, **including** tags, to their original value.
It's important to note that this applies only to the locally registered
service. If you have multiple nodes all registering the same service
their `enable_tag_override` 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 `enable_tag_override` is
not specified the default value is false. See [anti-entropy
syncs](/docs/internals/anti-entropy.html) for more info.
For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
supports both `enable_tag_override` and `enableTagOverride` but the latter is
deprecated and has been removed as of Consul 1.1.
## Multiple Service Definitions ## Multiple Service Definitions
Multiple services definitions can be provided at once using the plural Multiple services definitions can be provided at once using the plural

6
website/source/docs/internals/anti-entropy.html.md
View File

@ -136,7 +136,7 @@ If an error is encountered during an anti-entropy run, the error is logged and
the agent continues to run. The anti-entropy mechanism is run periodically to the agent continues to run. The anti-entropy mechanism is run periodically to
automatically recover from these types of transient failures. automatically recover from these types of transient failures.
### EnableTagOverride ### Enable Tag Override
Synchronization of service registration can be partially modified to Synchronization of service registration can be partially modified to
allow external agents to change the tags for a service. This can be allow external agents to change the tags for a service. This can be
@ -146,7 +146,7 @@ database and its monitoring service Redis Sentinel have this kind of
relationship. Redis instances are responsible for much of their relationship. Redis instances are responsible for much of their
configuration, but Sentinels determine whether the Redis instance is a configuration, but Sentinels determine whether the Redis instance is a
primary or a secondary. Using the Consul service configuration item primary or a secondary. Using the Consul service configuration item
[EnableTagOverride](/docs/agent/services.html) you can instruct the [enable_tag_override](/docs/agent/services.html) you can instruct the
Consul agent on which the Redis database is running to NOT update the Consul agent on which the Redis database is running to NOT update the
tags during anti-entropy synchronization. For more information see tags during anti-entropy synchronization. For more information see
[Services](/docs/agent/services.html) page. [Services](/docs/agent/services.html#enable-tag-override-and-anti-entropy) page.