From 29170340b3d85137a374c594512076e11d08b016 Mon Sep 17 00:00:00 2001 From: Hannah Oppenheimer Date: Fri, 5 Oct 2018 10:53:27 -0500 Subject: [PATCH] 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. --- website/source/docs/agent/services.html.md | 102 +++++++++--------- .../docs/internals/anti-entropy.html.md | 6 +- 2 files changed, 51 insertions(+), 57 deletions(-) diff --git a/website/source/docs/agent/services.html.md b/website/source/docs/agent/services.html.md index 79649bad0..2dcb32f4c 100644 --- a/website/source/docs/agent/services.html.md +++ b/website/source/docs/agent/services.html.md @@ -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 -`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 services have a unique ID per node, so if names might conflict then 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 can be used to distinguish between `primary` or `secondary` nodes, 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 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:`. If there are multiple -service checks registered, the ID will be generated as -`service::` where `` 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 Connect proxy](/docs/connect/proxies.html#unmanaged-proxies) instance with the 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 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:`. If there are multiple +service checks registered, the ID will be generated as +`service::` where `` 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 services definitions can be provided at once using the plural diff --git a/website/source/docs/internals/anti-entropy.html.md b/website/source/docs/internals/anti-entropy.html.md index 80bd10504..bd04681ee 100644 --- a/website/source/docs/internals/anti-entropy.html.md +++ b/website/source/docs/internals/anti-entropy.html.md @@ -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 automatically recover from these types of transient failures. -### EnableTagOverride +### Enable Tag Override Synchronization of service registration can be partially modified to 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 configuration, but Sentinels determine whether the Redis instance is a 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 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.