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

Docs/services refactor docs day 122022 (#16103) 

* converted main services page to services overview page

* set up services usage dirs

* added Define Services usage page

* converted health checks everything page to Define Health Checks usage page

* added Register Services and Nodes usage page

* converted Query with DNS to Discover Services and Nodes Overview page

* added Configure DNS Behavior usage page

* added Enable Static DNS Lookups usage page

* added the Enable Dynamic Queries DNS Queries usage page

* added the Configuration dir and overview page - may not need the overview, tho

* fixed the nav from previous commit

* added the Services Configuration Reference page

* added Health Checks Configuration Reference page

* updated service defaults configuraiton entry to new configuration ref format

* fixed some bad links found by checker

* more bad links found by checker

* another bad link found by checker

* converted main services page to services overview page

* set up services usage dirs

* added Define Services usage page

* converted health checks everything page to Define Health Checks usage page

* added Register Services and Nodes usage page

* converted Query with DNS to Discover Services and Nodes Overview page

* added Configure DNS Behavior usage page

* added Enable Static DNS Lookups usage page

* added the Enable Dynamic Queries DNS Queries usage page

* added the Configuration dir and overview page - may not need the overview, tho

* fixed the nav from previous commit

* added the Services Configuration Reference page

* added Health Checks Configuration Reference page

* updated service defaults configuraiton entry to new configuration ref format

* fixed some bad links found by checker

* more bad links found by checker

* another bad link found by checker

* fixed cross-links between new topics

* updated links to the new services pages

* fixed bad links in scale file

* tweaks to titles and phrasing

* fixed typo in checks.mdx

* started updating the conf ref to latest template

* update SD conf ref to match latest CT standard

* Apply suggestions from code review

Co-authored-by: Eddie Rowe <74205376+eddie-rowe@users.noreply.github.com>

* remove previous version of the checks page

* fixed cross-links

* Apply suggestions from code review

Co-authored-by: Eddie Rowe <74205376+eddie-rowe@users.noreply.github.com>

---------

Co-authored-by: Eddie Rowe <74205376+eddie-rowe@users.noreply.github.com>
This commit is contained in:
trujillo-adam 2023-02-28 14:09:56 -08:00 committed by GitHub
parent 531fc8045d
commit c0780ef3e9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
55 changed files with 3767 additions and 2709 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
website/content/api-docs/agent/check.mdx
View File

@ -6,8 +6,7 @@ description: The /agent/check endpoints interact with checks on the local agent
# Check - Agent HTTP API
Consul's health check capabilities are described in the
[health checks overview](/consul/docs/discovery/checks).
Refer to [Define Health Checks](/consul/docs/services/usage/checks) for information about Consul health check capabilities.
The `/agent/check` endpoints interact with health checks
managed by the local agent in Consul.
These should not be confused with checks in the catalog.

40
website/content/api-docs/agent/service.mdx
View File

@ -170,6 +170,8 @@ The table below shows this endpoint's support for
### Sample Request
The following example request calls the `web-sidecar-proxy` service:
```shell-session
$ curl \
http://127.0.0.1:8500/v1/agent/service/web-sidecar-proxy
@ -177,6 +179,11 @@ $ curl \
### Sample Response
The response contains the fields specified in the [service
definition](/consul/docs/services/configuration/services-configuration-reference), but it includes an extra `ContentHash` field that contains the [hash-based blocking
query](/consul/api-docs/features/blocking#hash-based-blocking-queries) hash for the result. The
same hash is also present in `X-Consul-ContentHash`.
```json
{
"Kind": "connect-proxy",
@ -227,12 +234,6 @@ $ curl \
}
```
The response has the same structure as the [service
definition](/consul/docs/discovery/services) with one extra field `ContentHash` which
contains the [hash-based blocking
query](/consul/api-docs/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.
@ -599,21 +600,18 @@ The corresponding CLI command is [`consul services register`](/consul/commands/s
### JSON Request Body Schema
Note that this endpoint, unlike most also [supports `snake_case`](/consul/docs/discovery/services#service-definition-parameter-case)
service definition keys for compatibility with the config file format.
The `/agent/service/register` endpoint supports camel case and _snake case_ for service definition keys. Snake case is a convention in which keys with two or more words have underscores between them. Snake case ensures compatibility with the agent configuration file format.
- `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)
for [compatibility with external DNS](/consul/docs/discovery/services#service-and-tag-names-with-dns).
valid DNS labels for service definition names. Refer to the Internet Engineering Task Force's [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123#page-72) for additional information. Service names that conform to standard usage ensures compatibility with external DNSs. Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference#name) for additional information.
- `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)
for [compatibility with external DNS](/consul/docs/discovery/services#service-and-tag-names-with-dns)
service. Tags enable you to filter when querying for the services and are exposed in Consul APIs. We recommend using
valid DNS labels for tags. Refer to the Internet Engineering Task Force's [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123#page-72) for additional information. Tags that conform to standard usage ensures compatibility with external DNSs. Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference#tags) for additional information.
- `Address` `(string: "")` - Specifies the address of the service. If not
provided, the agent's address is used as the address for the service during
@ -676,19 +674,15 @@ service definition keys for compatibility with the config file format.
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
[service documentation](/consul/docs/discovery/services) for more information about
weights. If this field is not provided weights will default to
- `Weights` `(Weights: nil)` - Specifies weights for the service. Refer to
[Services Configuration Reference](/consul/docs/services/configuraiton/services-configuration-reference#weights) for additional information. Default is
`{"Passing": 1, "Warning": 1}`.
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
Weights only apply to the locally registered service.
If multiple nodes register the same service, each node implements `EnableTagOverride` and other service configuration items independently. Updating the tags for the service registered
on one node does not necessarily update the same tags on services with the same name registered on another node. If `EnableTagOverride` is not specified the default value is
`false`. See [anti-entropy syncs](/consul/docs/architecture/anti-entropy) for
more info.
additional information.
#### Connect Structure

2
website/content/api-docs/api-structure.mdx
View File

@ -89,7 +89,7 @@ However, we generally recommend using resource names that don't require URL-enco
Depending on the validation that Consul applies to a resource name,
Consul may still reject a request if it considers the resource name invalid for that endpoint.
And even if Consul considers the resource name valid, it may degrade other functionality,
such as failed [DNS lookups](/consul/docs/discovery/dns)
such as failed [DNS lookups](/consul/docs/services/discovery/dns-overview)
for nodes or services with names containing invalid DNS characters.
This HTTP API capability also allows the

22
website/content/api-docs/catalog.mdx
View File

@ -55,15 +55,16 @@ The table below shows this endpoint's support for
- `NodeMeta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
pairs for filtering purposes.
- `Service` `(Service: nil)` - Specifies to register a service. If `ID` is not
provided, it will be defaulted to the value of the `Service.Service` property.
Only one service with a given `ID` may be present per node. We recommend using
[valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames)
for service definition names for [compatibility with external DNS](/consul/docs/discovery/services#service-and-tag-names-with-dns).
The service `Tags`, `Address`, `Meta`, and `Port` fields are all optional. For more
information about these fields and the implications of setting them,
see the [Service - Agent API](/consul/api-docs/agent/service) page
as registering services differs between using this or the Services Agent endpoint.
- `Service` `(Service: nil)` - Contains an object the specifies the service to register. The the `Service.Service` field is required. If `Service.ID` is not provided, the default is the `Service.Service`.
You can only specify one service with a given `ID` per node. We recommend using
valid DNS labels for service definition names. Refer to the Internet Engineering Task Force's [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123#page-72) for additional information. Service names that conform to standard usage ensures compatibility with external DNSs. Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference#name) for additional information.
The following fields are optional:
- `Tags`
- `Address`
- `Meta`
- `Port`
For additional information configuring services, refer to [Service - Agent API](/consul/api-docs/agent/service). The `/catalog` endpoint had different behaviors than the `/services` endpoint.
- `Check` `(Check: nil)` - Specifies to register a check. The register API
manipulates the health check entry in the Catalog, but it does not setup the
@ -78,8 +79,7 @@ The table below shows this endpoint's support for
treated as a service level health check, instead of a node level health
check. The `Status` must be one of `passing`, `warning`, or `critical`.
The `Definition` field can be provided with details for a TCP or HTTP health
check. For more information, see the [Health Checks](/consul/docs/discovery/checks) page.
You can provide defaults for TCP and HTTP health checks to the `Definition` field. Refer to [Health Checks](/consul/docs/services/usage/checks) for additional information.
Multiple checks can be provided by replacing `Check` with `Checks` and
sending an array of `Check` objects.

2
website/content/api-docs/features/consistency.mdx
View File

@ -131,7 +131,7 @@ The following diagrams show the cross-datacenter request paths when Consul serve
### Consul DNS Queries
When DNS queries are issued to [Consul's DNS interface](/consul/docs/discovery/dns),
When DNS queries are issued to [Consul's DNS interface](/consul/docs/services/discovery/dns-overview),
Consul uses the `stale` consistency mode by default when interfacing with its
underlying Consul service discovery HTTP APIs
([Catalog](/consul/api-docs/catalog), [Health](/consul/api-docs/health), and [Prepared Query](/consul/api-docs/query)).

7
website/content/api-docs/query.mdx
View File

@ -9,10 +9,9 @@ description: The /query endpoints manage and execute prepared queries in Consul.
The `/query` endpoints create, update, destroy, and execute prepared queries.
Prepared queries allow you to register a complex service query and then execute
it later via its ID or name to get a set of healthy nodes that provide a given
service. This is particularly useful in combination with Consul's
[DNS Interface](/consul/docs/discovery/dns#prepared-query-lookups) as it allows for much richer queries than
would be possible given the limited entry points exposed by DNS.
it later by specifying the query ID or name. Consul returns a set of healthy nodes that provide a given
service. Refer to
[Enable Dynamic DNS Queries](/consul/docs/services/discovery/dns-dynamic-lookups) for additional information.
Check the [Geo Failover tutorial](/consul/tutorials/developer-discovery/automate-geo-failover) for details and
examples for using prepared queries to implement geo failover for services.

16
website/content/commands/services/deregister.mdx
View File

@ -13,23 +13,19 @@ Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/deregister/:service_
The `services deregister` command deregisters a service with the local agent.
Note that this command can only deregister services that were registered
with the agent specified (defaults to the local agent) and is meant to
be paired with `services register`.
with the agent specified and is intended to be paired with `services register`.
By default, the command deregisters services on the local agent.
This is just one method for service deregistration. If the service was
registered with a configuration file, then deleting that file and
[reloading](/consul/commands/reload) Consul is the correct method to
deregister. See [Service Definition](/consul/docs/discovery/services) for more
information about registering services generally.
We recommend deregistering services registered with a configuration file by deleting the file and [reloading](/consul/commands/reload) Consul. Refer to [Services Overview](/consul/docs/services/services) for additional information about services.
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.
The following table shows the [ACLs](/consul/api-docs/api-structure#authentication) required to run the `consul services deregister` command:
| ACL Required |
| --------------- |
| `service:write` |
You cannot use the Consul command line to configure [blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching), you can configure them from the corresponding HTTP endpoint.
## Usage
Usage: `consul services deregister [options] [FILE...]`

20
website/content/commands/services/register.mdx
View File

@ -14,24 +14,16 @@ Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/register](/consul/ap
The `services register` command registers a service with the local agent.
This command returns after registration and must be paired with explicit
service deregistration. This command simplifies service registration from
scripts, in dev mode, etc.
scripts. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for information about other service registeration methods.
This is just one method of service registration. Services can also be
registered by placing a [service definition](/consul/docs/discovery/services)
in the Consul agent configuration directory and issuing a
[reload](/consul/commands/reload). This approach is easiest for
configuration management systems that other systems that have access to
the configuration directory. Clients may also use the
[HTTP API](/consul/api-docs/agent/service) directly.
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.
The following table shows the [ACLs](/consul/api-docs/api-structure#authentication) required to use the `consul services register` command:
| ACL Required |
| --------------- |
| `service:write` |
You cannot use the Consul command line to configure [blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching), you can configure them from the corresponding HTTP endpoint.
## Usage
Usage: `consul services register [options] [FILE...]`
@ -65,9 +57,7 @@ The flags below should only be set if _no arguments_ are given. If no
arguments are given, the flags below can be used to register a single
service.
Note that the behavior of each of the fields below is exactly the same
as when constructing a standard [service definition](/consul/docs/discovery/services).
Please refer to that documentation for full details.
The following fields specify identical parameters in a standard service definition file. Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference) for details about each configuration option.
- `-id` - The ID of the service. This will default to `-name` if not set.

2
website/content/docs/agent/config/cli-flags.mdx
View File

@ -92,7 +92,7 @@ information.
only the given `-encrypt` key will be available on startup. This defaults to false.
- `-enable-script-checks` ((#\_enable_script_checks)) This controls whether
[health checks that execute scripts](/consul/docs/discovery/checks) are enabled on this
[health checks that execute scripts](/consul/docs/services/usage/checks) are enabled on this
agent, and defaults to `false` so operators must opt-in to allowing these. This
was added in Consul 0.9.0.

46
website/content/docs/agent/config/config-files.mdx
View File

@ -7,6 +7,10 @@ description: >-
# Agents Configuration File Reference ((#configuration_files))
This topic describes the parameters for configuring Consul agents. For information about how to start Consul agents, refer to [Starting the Consul Agent](/consul/docs/agent#starting-the-consul-agent).
## Overview
You can create one or more files to configure the Consul agent on startup. We recommend
grouping similar configurations into separate files, such as ACL parameters, to make it
easier to manage configuration changes. Using external files may be easier than
@ -18,13 +22,6 @@ easily readable and editable by both humans and computers. JSON formatted
configuration consists of a single JSON object with multiple configuration keys
specified within it.
Configuration files are used for more than just setting up the agent.
They are also used to provide check and service definitions that
announce the availability of system servers to the rest of the cluster.
These definitions are documented separately under [check configuration](/consul/docs/discovery/checks) and
[service configuration](/consul/docs/discovery/services) respectively. Service and check
definitions support being updated during a reload.
<CodeTabs heading="Example Configuration File">
```hcl
@ -66,15 +63,27 @@ telemetry {
</CodeTabs>
# Configuration Key Reference ((#config_key_reference))
### Time-to-live values
-> **Note:** All the TTL values described below are parsed by Go's `time` package, and have the following
[formatting specification](https://golang.org/pkg/time/#ParseDuration): "A
duration string is a possibly signed sequence of decimal numbers, each with
optional fraction and a unit suffix, such as '300ms', '-1.5h' or '2h45m'.
Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
Consul uses the Go `time` package to parse all time-to-live (TTL) values used in Consul agent configuration files. Specify integer and float values as a string and include one or more of the following units of time:
## General
- `ns`
- `us`
- `µs`
- `ms`
- `s`
- `m`
- `h`
Examples:
- `'300ms'`
- `'1.5h'`
- `'2h45m'`
Refer to the [formatting specification](https://golang.org/pkg/time/#ParseDuration) for additional information.
## General parameters
- `addresses` - This is a nested object that allows setting
bind addresses. In Consul 1.0 and later these can be set to a space-separated list
@ -914,10 +923,9 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `agent_master` ((#acl_tokens_agent_master)) **Renamed in Consul 1.11 to
[`acl.tokens.agent_recovery`](#acl_tokens_agent_recovery).**
- `config_file_service_registration` ((#acl_tokens_config_file_service_registration)) - The ACL
token this agent uses to register services and checks from [service
definitions](/consul/docs/discovery/services) and [check definitions](/consul/docs/discovery/checks) found
in configuration files or in configuration fragments passed to the agent using the `-hcl`
- `config_file_service_registration` ((#acl_tokens_config_file_service_registration)) - Specifies the ACL
token the agent uses to register services and checks from [service](/consul/docs/services/usage/define-services) and [check](/consul/docs/usage/checks) definitions
specified in configuration files or fragments passed to the agent using the `-hcl`
flag.
If the `token` field is defined in the service or check definition, then that token is used to
@ -1367,7 +1375,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
of `1ns` instead of 0.
- `prefer_namespace` ((#dns_prefer_namespace)) <EnterpriseAlert inline /> **Deprecated in Consul 1.11.
Use the [canonical DNS format for enterprise service lookups](/consul/docs/discovery/dns#service-lookups-for-consul-enterprise) instead.** -
Use the [canonical DNS format for enterprise service lookups](/consul/docs/services/discovery/dns-static-lookups#service-lookups-for-consul-enterprise) instead.** -
When set to `true`, in a DNS query for a service, a single label between the domain
and the `service` label is treated as a namespace name instead of a datacenter.
When set to `false`, the default, the behavior is the same as non-Enterprise

2
website/content/docs/agent/index.mdx
View File

@ -319,7 +319,7 @@ tls {
### Client node registering a service
Using Consul as a central service registry is a common use case.
The following example configuration includes common settings to register a service with a Consul agent and enable health checks (see [Checks](/consul/docs/discovery/checks) to learn more about health checks):
The following example configuration includes common settings to register a service with a Consul agent and enable health checks. Refer to [Define Health Checks](/consul/docs/services/usage/checks) to learn more about health checks.
<CodeTabs>

11
website/content/docs/architecture/anti-entropy.mdx
View File

@ -26,7 +26,7 @@ health checks and updating their local state.
Services and checks within the context of an agent have a rich set of
configuration options available. This is because the agent is responsible for
generating information about its services and their health through the use of
[health checks](/consul/docs/discovery/checks).
[health checks](/consul/docs/services/usage/checks).
#### Catalog
@ -117,8 +117,7 @@ the source of truth for tag information. For example, the Redis
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
[enable_tag_override](/consul/docs/discovery/services) 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](/consul/docs/discovery/services#enable-tag-override-and-anti-entropy) page.
primary or a secondary. Enable the
[`enable_tag_override`](/consul/docs/services/configuration/services-configuration-reference#enable_tag_override) parameter in your service definition file to tell the Consul agent where the Redis database is running to bypass
tags during anti-entropy synchronization. Refer to
[Modify anti-entropy synchronozation](/consul/docs/services/usage/define-services#modify-anti-entropy-synchronization) for additional information.

2
website/content/docs/architecture/index.mdx
View File

@ -55,7 +55,7 @@ You can also run Consul with an alternate service mesh configuration that deploy
## LAN gossip pool
Client and server agents participate in a LAN gossip pool so that they can distribute and perform node [health checks](/consul/docs/discovery/checks). Agents in the pool propagate the health check information across the cluster. Agent gossip communication occurs on port `8301` using UDP. Agent gossip falls back to TCP if UDP is not available. Refer to [Gossip Protocol](/consul/docs/architecture/gossip) for additional information.
Client and server agents participate in a LAN gossip pool so that they can distribute and perform node [health checks](/consul/docs/services/usage/checks). Agents in the pool propagate the health check information across the cluster. Agent gossip communication occurs on port `8301` using UDP. Agent gossip falls back to TCP if UDP is not available. Refer to [Gossip Protocol](/consul/docs/architecture/gossip) for additional information.
The following simplified diagram shows the interactions between servers and clients.

6
website/content/docs/architecture/scale.mdx
View File

@ -236,7 +236,7 @@ Several factors influence Consul performance at scale when used primarily for it
- Rate of catalog updates, which is affected by the following events:
- A service instance’s health check status changes
- A service instance’s node loses connectivity to Consul servers
- The contents of the [service definition file](/consul/docs/discovery/services#service-definition) changes
- The contents of the [service definition file](/consul/docs/services/configuration/services-configuration-reference) changes
- Service instances are registered or deregistered
- Orchestrators such as Kubernetes or Nomad move a service to a new node
@ -280,4 +280,8 @@ At scale, using Consul as a backend for Vault results in increased memory and CP
In situations where Consul handles large amounts of data and has high write throughput, we recommend adding monitoring for the [capacity and health of raft replication on servers](/consul/docs/agent/telemetry#raft-replication-capacity-issues). If the server experiences heavy load when the size of its stored data is large enough, a follower may be unable to catch up on replication and become a voter after restarting. This situation occurs when the time it takes for a server to restore from disk takes longer than it takes for the leader to write a new snapshot and truncate its logs. Refer to [Raft snapshots](#raft-snapshots) for more information.
<<<<<<< HEAD
Vault v1.4 and higher provides [integrated storage](/vault/docs/concepts/integrated-storage) as its recommended storage option. If you currently use Consul as a storage backend for Vault, we recommend switching to integrated storage. For a comparison between Vault's integrated storage and Consul as a backend for Vault, refer to [storage backends in the Vault documentation](/vault/docs/configuration/storage#integrated-storage-vs-consul-as-vault-storage). For detailed guidance on migrating the Vault backend from Consul to Vault's integrated storage, refer to the [storage migration tutorial](/vault/docs/configuration/storage#integrated-storage-vs-consul-as-vault-storage). Integrated storage improves resiliency by preventing a Consul outage from also affecting Vault functionality.
=======
Vault v1.4 and higher provides [integrated storage](/vault/docs/concepts/integrated-storage) as its recommended storage option. If you currently use Consul as a storage backend for Vault, we recommend switching to integrated storage. For a comparison between Vault's integrated storage and Consul as a backend for Vault, refer to [storage backends in the Vault documentation](/vault/docs/configuration/storage#integrated-storage-vs-consul-as-vault-storage). For detailed guidance on migrating the Vault backend from Consul to Vault's integrated storage, refer to the [storage migration tutorial](/vault/docs/configuration/storage#integrated-storage-vs-consul-as-vault-storage). Integrated storage improves resiliency by preventing a Consul outage from also affecting Vault functionality.
>>>>>>> main

2
website/content/docs/connect/cluster-peering/tech-specs.mdx
View File

@ -45,7 +45,7 @@ Refer to [mesh gateway modes](/consul/docs/connect/gateways/mesh-gateway#modes)
## Sidecar proxy requirements
The Envoy proxies that function as sidecars in your service mesh require configuration in order to properly route traffic to peers. Sidecar proxies are defined in the [service definition](/consul/docs/discovery/services).
The Envoy proxies that function as sidecars in your service mesh require configuration in order to properly route traffic to peers. Sidecar proxies are defined in the [service definition](/consul/docs/services/usage/defin-services).
- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams`](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) documentation for details.
- The `proxy.upstreams.destination_name` parameter is always required.

7
website/content/docs/connect/config-entries/ingress-gateway.mdx
View File

@ -172,10 +172,9 @@ gateway:
- All services with the same
[protocol](/consul/docs/connect/config-entries/ingress-gateway#protocol) as the
listener will be routable.
- The ingress gateway will route traffic based on the host/authority header,
expecting a value matching `<service-name>.ingress.*`, or if using namespaces,
`<service-name>.ingress.<namespace>.*`. This matches the [Consul DNS
ingress subdomain](/consul/docs/discovery/dns#ingress-service-lookups).
- The ingress gateway routes traffic based on the host or authority header and expects a value matching either `<service-name>.ingress.*` or
`<service-name>.ingress.<namespace>.*`. The query matches the [Consul DNS
ingress subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups).
A wildcard specifier cannot be set on a listener of protocol `tcp`.

1194
website/content/docs/connect/config-entries/service-defaults.mdx
View File

File diff suppressed because it is too large Load Diff

21
website/content/docs/connect/configuration.mdx
View File

@ -9,14 +9,11 @@ description: >-
There are many configuration options exposed for Consul service mesh. The only option
that must be set is the `connect.enabled` option on Consul servers to enable Consul service mesh.
All other configurations are optional and have reasonable defaults.
All other configurations are optional and have defaults suitable for many environments.
Consul Connect is the component shipped with Consul that enables service mesh functionality. The terms _Consul Connect_ and _Consul service mesh_ are used interchangeably throughout this documentation.
The terms _Consul Connect_ and _Consul service mesh_ are used interchangeably throughout this documentation.
-> **Tip:** Service mesh is enabled by default when running Consul in
dev mode with `consul agent -dev`.
## Agent Configuration
## Agent configuration
Begin by enabling Connect for your Consul
cluster. By default, Connect is disabled. Enabling Connect requires changing
@ -75,18 +72,12 @@ automatically ensure complete security. Please read the [Connect production
tutorial](/consul/tutorials/developer-mesh/service-mesh-production-checklist) to understand the additional steps
needed for a secure deployment.
## Centralized Proxy and Service Configuration
## Centralized proxy and service configuration
To account for common Connect use cases where you have many instances of the
same service, and many colocated sidecar proxies, Consul allows you to customize
the settings for all of your proxies or all the instances of a given service at
once using [Configuration Entries](/consul/docs/agent/config-entries).
You can override centralized configurations for individual proxy instances in
their
If your network contains many instances of the same service and many colocated sidecar proxies, you can specify global settings for proxies or services in [Configuration Entries](/consul/docs/agent/config-entries). You can override the centralized configurations for individual proxy instances in their
[sidecar service definitions](/consul/docs/connect/registration/sidecar-service),
and the default protocols for service instances in their [service
registrations](/consul/docs/discovery/services).
definitions](/consul/docs/services/usage/define-services).
## Schedulers

4
website/content/docs/connect/gateways/ingress-gateway.mdx
View File

@ -20,7 +20,7 @@ to a set of backing
[services](/consul/docs/connect/config-entries/ingress-gateway#services).
To enable easier service discovery, a new Consul [DNS
subdomain](/consul/docs/discovery/dns#ingress-service-lookups) is provided, on
subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups) is provided, on
`<service>.ingress.<domain>`.
For listeners with a
@ -29,7 +29,7 @@ For listeners with a
case, the ingress gateway relies on host/authority headers to decide the
service that should receive the traffic. The host used to match traffic
defaults to the [Consul DNS ingress
subdomain](/consul/docs/discovery/dns#ingress-service-lookups), but can be changed using
subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups), but can be changed using
the [hosts](/consul/docs/connect/config-entries/ingress-gateway#hosts) field.
![Ingress Gateway Architecture](/img/ingress-gateways.png)

10
website/content/docs/connect/native/index.mdx
View File

@ -54,7 +54,7 @@ Details on the steps are below:
- **Service discovery** - This is normal service discovery using Consul,
a static IP, or any other mechanism. If you're using Consul DNS, the
[`<service>.connect`](/consul/docs/discovery/dns#connect-capable-service-lookups)
[`<service>.connect`](/consul/docs/services/discovery/dns-static-lookups#service-mesh-enabled-service-lookups)
syntax to find Connect-capable endpoints for a service. After service
discovery, choose one address from the list of **service addresses**.
@ -94,7 +94,7 @@ Details on the steps are below:
HTTP) aware it can safely enforce intentions per _request_ instead of the
coarser per _connection_ model.
## Updating Certificates and Certificate Roots
## Update certificates and certificate roots
The leaf certificate and CA roots can be updated at any time and the
natively integrated application must react to this relatively quickly
@ -129,14 +129,14 @@ Some language libraries such as the
[Go library](/consul/docs/connect/native/go) automatically handle updating
and locally caching the certificates.
## Service Registration
## Service registration
Connect-native applications must tell Consul that they support Connect
natively. This enables the service to be returned as part of service
discovery for Connect-capable services, used by other Connect-native applications
discovery for service mesh-capable services used by other Connect-native applications
and client [proxies](/consul/docs/connect/proxies).
This can be specified directly in the [service definition](/consul/docs/discovery/services):
You can enable native service mesh support directly in the [service definition](/consul/docs/services/configuration/services-configuration-reference#connect) by configuring the `connect` block. In the following example, the `redis` service is configured to support service mesh natively:
```json
{

20
website/content/docs/connect/observability/index.mdx
View File

@ -26,7 +26,7 @@ configuration](/consul/docs/agent/config/config-files#enable_central_service_con
If you are using Kubernetes, the Helm chart can simplify much of the configuration needed to enable observability. See
our [Kubernetes observability docs](/consul/docs/k8s/connect/observability/metrics) for more information.
### Metrics Destination
### Metrics destination
For Envoy the metrics destination can be configured in the proxy configuration
entry's `config` section.
@ -41,18 +41,18 @@ config {
Find other possible metrics syncs in the [Connect Envoy documentation](/consul/docs/connect/proxies/envoy#bootstrap-configuration).
### Service Protocol
### Service protocol
You can specify the [service protocol](/consul/docs/connect/config-entries/service-defaults#protocol)
in the `service-defaults` configuration entry. You can override it in the
[service registration](/consul/docs/discovery/services). By default, proxies only give
you L4 metrics. This protocol allows proxies to handle requests at the right L7
protocol and emit richer L7 metrics. It also allows proxies to make per-request
You can specify the [`protocol`](/consul/docs/connect/config-entries/service-defaults#protocol)
for all service instances in the `service-defaults` configuration entry. You can also override the default protocol when defining and registering proxies in a service definition file. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) for additional information.
By default, proxies only provide L4 metrics.
Defining the protocol allows proxies to handle requests at the L7
protocol and emit L7 metrics. It also allows proxies to make per-request
load balancing and routing decisions.
### Service Upstreams
### Service upstreams
You can set the upstream for each service using the proxy's
[`upstreams`](/consul/docs/connect/registration/service-registration#upstreams)
sidecar parameter, which can be defined in a service's [sidecar
registration](/consul/docs/connect/registration/sidecar-service).
sidecar parameter, which can be defined in a service's [sidecar registration](/consul/docs/connect/registration/sidecar-service).

28
website/content/docs/connect/proxies/index.mdx
View File

@ -7,29 +7,23 @@ description: >-
# Service Mesh Proxy Overview
A Connect-aware proxy enables unmodified applications to use Connect. A
Proxies enable unmodified applications to connect to other services in the service mesh. A
per-service proxy sidecar transparently handles inbound and outbound service
connections, automatically wrapping and verifying TLS connections. Consul
includes its own built-in L4 proxy and has first class support for Envoy. You
can choose other proxies to plug in as well. This section describes how to
ships with a built-in L4 proxy and has first class support for Envoy. You
can plug other proxies into your environment as well. This section describes how to
configure Envoy or the built-in proxy using Connect, and how to integrate the
proxy of your choice.
To ensure that services only allow external connections established via
the Connect protocol, you should configure all services to only accept connections on a loopback address.
To ensure that services only allow external connections established through
the service mesh protocol, you should configure all services to only accept connections on a loopback address.
~> **Deprecation Note:** Managed Proxies are a deprecated method for deploying
sidecar proxies, and have been removed in Consul 1.6. See [managed proxy
deprecation](/consul/docs/connect/proxies/managed-deprecated) for more
information. If you are using managed proxies we strongly recommend that you
switch service definitions for registering proxies.
## Dynamic upstreams require native integration
## Dynamic Upstreams Require Native Integration
Service mesh proxies do not support dynamic upstreams.
If an application requires dynamic dependencies that are only available
at runtime, it must [natively integrate](/consul/docs/connect/native)
with Connect. After natively integrating, the HTTP API or
[DNS interface](/consul/docs/discovery/dns#connect-capable-service-lookups)
can be used.
!> Connect proxies do not currently support dynamic upstreams.
at runtime, you must [natively integrate](/consul/docs/connect/native)
the application with Consul service mesh. After natively integrating, the HTTP API or
[DNS interface](/consul/docs/services/discovery/dns-static-lookups#service-mesh-enabled-service-lookups)
can be used.

278
website/content/docs/connect/proxies/managed-deprecated.mdx
View File

@ -1,278 +0,0 @@
---
layout: docs
page_title: Managed Proxy for Connect (Legacy)
description: >-
Consul's service mesh originally included a proxy manager that was deprecated in version 1.6. Learn about the reasons for its deprecation and how it worked with this legacy documentation.
---
# Managed Proxy for Connect Legacy Documentation
Consul Connect was first released as a beta feature in Consul 1.2.0. The initial
release included a feature called "Managed Proxies". Managed proxies were
Connect proxies where the proxy process was started, configured, and stopped by
Consul. They were enabled via basic configurations within the service
definition.
!> **Consul 1.6.0 removes Managed Proxies completely.**
This documentation is provided for prior versions only. You may consider using
[sidecar service
registrations](/consul/docs/connect/registration/sidecar-service) instead.
Managed proxies have been deprecated since Consul 1.3 and have been fully removed
in Consul 1.6. Anyone using Managed Proxies should aim to change their workflow
as soon as possible to avoid issues with a later upgrade.
After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/consul/docs/agent/config/cli-flags#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space.
**new and known issues will not be fixed**.
## Deprecation Rationale
Originally managed proxies traded higher implementation complexity for an easier
"getting started" user experience. After seeing how Connect was investigated and
adopted during beta it became obvious that they were not the best trade off.
Managed proxies only really helped in local testing or VM-per-service based
models whereas a lot of users jumped straight to containers where they are not
helpful. They also add only targeted fairly basic supervisor features which
meant most people would want to use something else in production for consistency
with other workloads. So the high implementation cost of building robust process
supervision didn't actually benefit most real use-cases.
Instead of this Connect 1.3.0 introduces the concept of [sidecar service
registrations](/consul/docs/connect/registration/sidecar-service) which
have almost all of the benefits of simpler configuration but without any of the
additional process management complexity. As a result they can be used to
simplify configuration in both container-based and realistic production
supervisor settings.
## Managed Proxy Documentation
As the managed proxy features continue to be supported for now, the rest of this
page will document how they work in the interim.
-> **Deprecation Note:** It's _strongly_ recommended you do not build anything
using Managed proxies and consider using [sidecar service
registrations](/consul/docs/connect/registration/sidecar-service) instead.
Managed proxies are given
a unique proxy-specific ACL token that allows read-only access to Connect
information for the specific service the proxy is representing. This ACL
token is more restrictive than can be currently expressed manually in
an ACL policy.
The default managed proxy is a basic proxy built-in to Consul and written
in Go. Having a basic built-in proxy allows Consul to have a reasonable default
with performance that is good enough for most workloads. In some basic
benchmarks, the service-to-service communication over the built-in proxy
could sustain 5 Gbps with sub-millisecond latency. Therefore,
the performance impact of even the basic built-in proxy is minimal.
Consul will be integrating with advanced proxies in the near future to support
more complex configurations and higher performance. The configuration below is
all for the built-in proxy.
-> **Security Note:** 1.) Managed proxies can only be configured
via agent configuration files. They _cannot_ be registered via the HTTP API.
And 2.) Managed proxies are not started at all if Consul is running as root.
Both of these default configurations help prevent arbitrary process
execution or privilege escalation. This behavior can be configured
[per-agent](/consul/docs/agent/config).
### Lifecycle
The Consul agent starts managed proxies on demand and supervises them,
restarting them if they crash. The lifecycle of the proxy process is decoupled
from the agent so if the agent crashes or is restarted for an upgrade, the
managed proxy instances will _not_ be stopped.
Note that this behavior while desirable in production might leave proxy
processes running indefinitely if you manually stop the agent and clear its
data dir during testing.
To terminate a managed proxy cleanly you need to deregister the service that
requested it. If the agent is already stopped and will not be restarted again,
you may choose to locate the proxy processes and kill them manually.
While in `-dev` mode, unless a `-data-dir` is explicitly set, managed proxies
switch to being killed when the agent exits since it can't store state in order
to re-adopt them on restart.
### Minimal Configuration
Managed proxies are configured within a
[service definition](/consul/docs/discovery/services). The simplest possible
managed proxy configuration is an empty configuration. This enables the
default managed proxy and starts a listener for that service:
```json
{
"service": {
"name": "redis",
"port": 6379,
"connect": { "proxy": {} }
}
}
```
The listener is started on random port within the configured Connect
port range. It can be discovered using the
[DNS interface](/consul/docs/discovery/dns#connect-capable-service-lookups)
or
[Catalog API](#).
In most cases, service-to-service communication is established by
a proxy configured with upstreams (described below), which handle the
discovery transparently.
### Upstream Configuration
To transparently discover and establish Connect-based connections to
dependencies, they must be configured with a static port on the managed
proxy configuration:
```json
{
"service": {
"name": "web",
"port": 8080,
"connect": {
"proxy": {
"upstreams": [
{
"destination_name": "redis",
"local_bind_port": 1234
}
]
}
}
}
}
```
In the example above,
"redis" is configured as an upstream with static port 1234 for service "web".
When a TCP connection is established on port 1234, the proxy
will find Connect-compatible "redis" services via Consul service discovery
and establish a TLS connection identifying as "web".
~> **Security:** Any application that can communicate to the configured
static port will be able to masquerade as the source service ("web" in the
example above). You must either trust any loopback access on that port or
use namespacing techniques provided by your operating system.
-> **Deprecation Note:** versions 1.2.0 to 1.3.0 required specifying `upstreams`
as part of the opaque `config` that is passed to the proxy. However, since
1.3.0, the `upstreams` configuration is now specified directly under the
`proxy` key. Old service definitions using the nested config will continue to
work and have the values copied into the new location. This allows the upstreams
to be registered centrally rather than being part of the local-only config
passed to the proxy instance.
For full details of the additional configurable options available when using the
built-in proxy see the [built-in proxy configuration
reference](/consul/docs/connect/configuration).
### Prepared Query Upstreams
The upstream destination may also be a
[prepared query](/consul/api-docs/query).
This allows complex service discovery behavior such as connecting to
the nearest neighbor or filtering by tags.
For example, given a prepared query named "nearest-redis" that is
configured to route to the nearest Redis instance, an upstream can be
configured to route to this query. In the example below, any TCP connection
to port 1234 will attempt a Connect-based connection to the nearest Redis
service.
```json
{
"service": {
"name": "web",
"port": 8080,
"connect": {
"proxy": {
"upstreams": [
{
"destination_name": "redis",
"destination_type": "prepared_query",
"local_bind_port": 1234
}
]
}
}
}
}
```
For full details of the additional configurable options available when using the
built-in proxy see the [built-in proxy configuration
reference](/consul/docs/connect/configuration).
### Custom Managed Proxy
[Custom proxies](/consul/docs/connect/proxies/integrate) can also be
configured to run as a managed proxy. To configure custom proxies, specify
an alternate command to execute for the proxy:
```json
{
"service": {
"name": "web",
"port": 8080,
"connect": {
"proxy": {
"exec_mode": "daemon",
"command": ["/usr/bin/my-proxy", "-flag-example"],
"config": {
"foo": "bar"
}
}
}
}
}
```
The `exec_mode` value specifies how the proxy is executed. The only
supported value at this time is "daemon". The command is the binary and
any arguments to execute.
The "daemon" mode expects a proxy to run as a long-running, blocking
process. It should not double-fork into the background. The custom
proxy should retrieve its configuration (such as the port to run on)
via the [custom proxy integration APIs](/consul/docs/connect/proxies/integrate).
The default proxy command can be changed at an agent-global level
in the agent configuration. An example in HCL format is shown below.
```
connect {
proxy_defaults {
command = ["/usr/bin/my-proxy"]
}
}
```
With this configuration, all services registered without an explicit
proxy command will use `my-proxy` instead of the default built-in proxy.
The `config` key is an optional opaque JSON object which will be passed through
to the proxy via the proxy configuration endpoint to allow any configuration
options the proxy needs to be specified. See the [built-in proxy
configuration reference](/consul/docs/connect/configuration)
for details of config options that can be passed when using the built-in proxy.
### Managed Proxy Logs
Managed proxies have both stdout and stderr captured in log files in the agent's
`data_dir`. They can be found in
`<data_dir>/proxy/logs/<proxy_service_id>-std{err,out}.log`.
The built-in proxy will inherit its log level from the agent so if the agent is
configured with `log_level = DEBUG`, a proxy it starts will also output `DEBUG`
level logs showing service discovery, certificate and authorization information.
~> **Note:** In `-dev` mode there is no `data_dir` unless one is explicitly
configured so logging is disabled. You can access logs by providing the
[`-data-dir`](/consul/docs/agent/config/cli-flags#_data_dir) CLI option. If a data dir is
configured, this will also cause proxy processes to stay running when the agent
terminates as described in [Lifecycle](#lifecycle).

7
website/content/docs/connect/registration/index.mdx
View File

@ -7,14 +7,13 @@ description: >-
# Service Mesh Proxy Overview
To make Connect aware of proxies you will need to register them in a [service
definition](/consul/docs/discovery/services), just like you would register any other service with Consul. This section outlines your options for registering Connect proxies, either using independent registrations, or in nested sidecar registrations.
To enable service mesh proxies, you must define and register them with Consul. Proxies are a type of service in Consul that facilitate highly secure communication between services in a service mesh. The topics in the section outline your options for registering service mesh proxies. You can register proxies independently or nested inside a sidecar service registration.
## Proxy Service Registration
## Proxy service registration
To register proxies with independent proxy service registrations, you can define them in either in config files or via the API just like any other service. Learn more about all of the options you can define when registering your proxy service in the [proxy registration documentation](/consul/docs/connect/registration/service-registration).
## Sidecar Service Registration
## Sidecar service registration
To reduce the amount of boilerplate needed for a sidecar proxy,
application service definitions may define an inline sidecar service block. This is an opinionated

18
website/content/docs/connect/registration/service-registration.mdx
View File

@ -9,6 +9,7 @@ description: >-
This topic describes how to declare a proxy as a `connect-proxy` in service definitions. The `kind` must be declared and information about the service they represent must be provided to function as a Consul service mesh proxy.
## Configuration
Configure a service mesh proxy using the following syntax:
@ -178,9 +179,7 @@ You can configure the service mesh proxy to create listeners for upstream servic
### Upstream Configuration Examples
Upstreams support multiple destination types. The following examples include information about each implementation.
-> **Snake case**: The examples in this topic use `snake_case` because the syntax is supported in configuration files and API registrations. See [Service Definition Parameter Case](/consul/docs/discovery/services#service-definition-parameter-case) for additional information.
Upstreams support multiple destination types. The following examples include information about each implementation. Note that the examples in this topic use snake case, which is a convention that separates words with underscores, because the format is supported in configuration files and API registrations.
<CodeTabs heading="Example service destination upstream">
@ -300,10 +299,7 @@ The proxy will default to `direct` mode if a mode cannot be determined from the
The following examples show additional configuration for transparent proxies.
Added in v1.10.0.
-> Note that `snake_case` is used here as it works in both [config file and API
registrations](/consul/docs/discovery/services#service-definition-parameter-case).
Note that the examples in this topic use snake case, which is a convention that separates words with underscores, because the format is supported in configuration files and API registrations.
#### Configure a proxy listener for outbound traffic on port 22500
@ -328,8 +324,7 @@ registrations](/consul/docs/discovery/services#service-definition-parameter-case
The following examples show all possible mesh gateway configurations.
-> Note that `snake_case` is used here as it works in both [config file and API
registrations](/consul/docs/discovery/services#service-definition-parameter-case).
Note that the examples in this topic use snake case, which is a convention that separates words with underscores, because the format is supported in configuration files and API registrations.
#### Using a Local/Egress Gateway in the Local Datacenter
@ -385,9 +380,8 @@ The following examples show possible configurations to expose HTTP paths through
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
non-Connect-enabled applications to contact an HTTP endpoint.
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks.
-> Note that `snake_case` is used here as it works in both [config file and API
registrations](/consul/docs/discovery/services#service-definition-parameter-case).
Note that the examples in this topic use snake case, which is a convention that separates words with underscores, because the format is supported in configuration files and API registrations.
#### Expose listeners in Envoy for HTTP and GRPC checks registered with the local Consul agent

28
website/content/docs/connect/registration/sidecar-service.mdx
View File

@ -7,20 +7,16 @@ description: >-
# Register a Service Mesh Proxy in a Service Registration
Connect proxies are typically deployed as "sidecars" that run on the same node
as the single service instance that they handle traffic for. They might be on
the same VM or running as a separate container in the same network namespace.
This topic describes how to declare a proxy as a _sidecar_ proxy.
Sidecar proxies run on the same node as the single service instance that they handle traffic for.
They may be on the same VM or running as a separate container in the same network namespace.
To simplify the configuration experience when deploying a sidecar for a service
instance, Consul 1.3 introduced a new field in the Connect block of the [service
definition](/consul/docs/discovery/services).
## Configuration
The `connect.sidecar_service` field is a complete nested service definition on
which almost any regular service definition field can be set. The exceptions are
[noted below](#limitations). If used, the service definition is treated
identically to another top-level service definition. The value of the nested
definition is that _all fields are optional_ with some opinionated defaults
applied that make setting up a sidecar proxy much simpler.
Add the `connect.sidecar_service` block to your service definition file and specify the parameters to configure sidecar proxy behavior. The `sidecar_service` block is a service definition that can contain most regular service definition fields. Refer to [Limitations](#limitations) for information about unsupported service definition fields for sidecar proxies.
Consul treats sidecar proxy service definitions as a root-level service definition. All fields are optional in nested
definitions, which default to opinionated settings that are intended to reduce burden of setting up a sidecar proxy.
## Minimal Example
@ -134,7 +130,7 @@ proxy.
- `kind` - Defaults to `connect-proxy`. This can't be overridden currently.
- `check`, `checks` - By default we add a TCP check on the local address and
port for the proxy, and a [service alias
check](/consul/docs/discovery/checks#alias) for the parent service. If either
check](/consul/docs/services/usage/checks#alias-checks) for the parent service. If either
`check` or `checks` fields are set, only the provided checks are registered.
- `proxy.destination_service_name` - Defaults to the parent service name.
- `proxy.destination_service_id` - Defaults to the parent service ID.
@ -143,8 +139,7 @@ proxy.
## Limitations
Almost all fields in a [service definition](/consul/docs/discovery/services) may be
set on the `connect.sidecar_service` except for the following:
The following fields are not supported in the `connect.sidecar_service` block:
- `id` - Sidecar services get an ID assigned and it is an error to override
this. This ensures the agent can correctly deregister the sidecar service
@ -153,9 +148,6 @@ set on the `connect.sidecar_service` except for the following:
unset this to make the registration be for a regular non-connect-proxy
service.
- `connect.sidecar_service` - Service definitions can't be nested recursively.
- `connect.proxy` - (Deprecated) [Managed
proxies](/consul/docs/connect/proxies/managed-deprecated) can't be defined on a
sidecar.
- `connect.native` - Currently the `kind` is fixed to `connect-proxy` and it's
an error to register a `connect-proxy` that is also Connect-native.

2
website/content/docs/consul-vs-other/dns-tools-compare.mdx
View File

@ -12,5 +12,5 @@ description: >-
Consul was originally designed as a centralized service registry for any cloud environment that dynamically tracks services as they are added, changed, or removed within a compute infrastructure. Consul maintains a catalog of these registered services and their attributes, such as IP addresses or service name. For more information, refer to [What is Service Discovery?](/consul/docs/concepts/service-discovery).
As a result, Consul can also provide basic DNS functionality, including [lookups, alternate domains, and access controls](/consul/docs/discovery/dns). Since Consul is platform agnostic, you can retrieve service information across both cloud and on-premises data centers. Consul does not natively support some advanced DNS capabilities, such as filters or advanced routing logic. However, you can integrate Consul with existing DNS solutions, such as [NS1](https://help.ns1.com/hc/en-us/articles/360039417093-NS1-Consul-Integration-Overview) and [DNSimple](https://blog.dnsimple.com/2022/05/consul-integration/), to support these advanced capabilities.
As a result, Consul can also provide basic DNS functionality, including [lookups, alternate domains, and access controls](/consul/docs/services/discovery/dns-overview). Since Consul is platform agnostic, you can retrieve service information across both cloud and on-premises data centers. Consul does not natively support some advanced DNS capabilities, such as filters or advanced routing logic. However, you can integrate Consul with existing DNS solutions, such as [NS1](https://help.ns1.com/hc/en-us/articles/360039417093-NS1-Consul-Integration-Overview) and [DNSimple](https://blog.dnsimple.com/2022/05/consul-integration/), to support these advanced capabilities.

885
website/content/docs/discovery/checks.mdx
View File

@ -1,885 +0,0 @@
---
layout: docs
page_title: Configure Health Checks
description: >-
Agents can be configured to periodically perform custom checks on the health of a service instance or node. Learn about the types of health checks and how to define them in agent and service configuration files.
---
# Health Checks
One of the primary roles of the agent is management of system-level and application-level health
checks. A health check is considered to be application-level if it is associated with a
service. If not associated with a service, the check monitors the health of the entire node.
Review the [health checks tutorial](/consul/tutorials/developer-discovery/service-registration-health-checks)
to get a more complete example on how to leverage health check capabilities in Consul.
A check is defined in a configuration file or added at runtime over the HTTP interface. Checks
created via the HTTP interface persist with that node.
There are several types of checks:
- [`Script + Interval`](#script-check) - These checks invoke an external application
that performs the health check.
- [`HTTP + Interval`](#http-check) - These checks make an HTTP `GET` request to the specified URL
in the health check definition.
- [`TCP + Interval`](#tcp-check) - These checks attempt a TCP connection to the specified
address and port in the health check definition.
- [`UDP + Interval`](#udp-check) - These checks direct the client to periodically send UDP datagrams
to the specified address and port in the health check definition.
- [`OSService + Interval`](#osservice-check) - These checks periodically direct the Consul agent to monitor
the health of a service running on the host operating system.
- [`Time to Live (TTL)`](#time-to-live-ttl-check) - These checks attempt an HTTP connection after a given TTL elapses.
- [`Docker + Interval`](#docker-check) - These checks invoke an external application that
is packaged within a Docker container.
- [`gRPC + Interval`](#grpc-check) - These checks are intended for applications that support the standard
[gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
- [`H2ping + Interval`](#h2ping-check) - These checks test an endpoint that uses HTTP/2
by connecting to the endpoint and sending a ping frame.
- [`Alias`](#alias-check) - These checks alias the health state of another registered
node or service.
## Registering a health check
There are three ways to register a service with health checks:
1. Start or reload a Consul agent with a service definition file in the
[agent's configuration directory](/consul/docs/agent#configuring-consul-agents).
1. Call the
[`/agent/service/register`](/consul/api-docs/agent/service#register-service)
HTTP API endpoint to register the service.
1. Use the
[`consul services register`](/consul/commands/services/register)
CLI command to register the service.
When a service is registered using the HTTP API endpoint or CLI command,
the checks persist in the Consul data folder across Consul agent restarts.
## Types of checks
This section describes the available types of health checks you can use to
automatically monitor the health of a service instance or node.
-> **To manually mark a service unhealthy:** Use the maintenance mode
[CLI command](/consul/commands/maint) or
[HTTP API endpoint](/consul/api-docs/agent#enable-maintenance-mode)
to temporarily remove one or all service instances on a node
from service discovery DNS and HTTP API query results.
### Script check
Script checks periodically invoke an external application that performs the health check,
exits with an appropriate exit code, and potentially generates some output.
The specified `interval` determines the time between check invocations.
The output of a script check is limited to 4KB.
Larger outputs are truncated.
By default, script checks are configured with a timeout equal to 30 seconds.
To configure a custom script check timeout value,
specify the `timeout` field in the check definition.
After reaching the timeout on a Windows system,
Consul waits for any child processes spawned by the script to finish.
After reaching the timeout on other systems,
Consul attempts to force-kill the script and any child processes it spawned.
Script checks are not enabled by default.
To enable a Consul agent to perform script checks,
use one of the following agent configuration options:
- [`enable_local_script_checks`](/consul/docs/agent/config/cli-flags#_enable_local_script_checks):
Enable script checks defined in local config files.
Script checks registered using the HTTP API are not allowed.
- [`enable_script_checks`](/consul/docs/agent/config/cli-flags#_enable_script_checks):
Enable script checks no matter how they are registered.
~> **Security Warning:**
Enabling non-local script checks in some configurations may introduce
a remote execution vulnerability known to be targeted by malware.
We strongly recommend `enable_local_script_checks` instead.
For more information, refer to
[this blog post](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations).
The following service definition file snippet is an example
of a script check definition:
<CodeTabs heading="Script Check">
```hcl
check = {
id = "mem-util"
name = "Memory utilization"
args = ["/usr/local/bin/check_mem.py", "-limit", "256MB"]
interval = "10s"
timeout = "1s"
}
```
```json
{
"check": {
"id": "mem-util",
"name": "Memory utilization",
"args": ["/usr/local/bin/check_mem.py", "-limit", "256MB"],
"interval": "10s",
"timeout": "1s"
}
}
```
</CodeTabs>
#### Check script conventions
A check script's exit code is used to determine the health check status:
- Exit code 0 - Check is passing
- Exit code 1 - Check is warning
- Any other code - Check is failing
Any output of the script is captured and made available in the
`Output` field of checks included in HTTP API responses,
as in this example from the [local service health endpoint](/consul/api-docs/agent/service#by-name-json).
### HTTP check
HTTP checks periodically make an HTTP `GET` request to the specified URL,
waiting the specified `interval` amount of time between requests.
The status of the service depends on the HTTP response code: any `2xx` code is
considered passing, a `429 Too ManyRequests` is a warning, and anything else is
a failure. This type of check
should be preferred over a script that uses `curl` or another external process
to check a simple HTTP operation. By default, HTTP checks are `GET` requests
unless the `method` field specifies a different method. Additional request
headers can be set through the `header` field which is a map of lists of
strings, such as `{"x-foo": ["bar", "baz"]}`.
By default, HTTP checks are configured with a request timeout equal to 10 seconds.
To configure a custom HTTP check timeout value,
specify the `timeout` field in the check definition.
The output of an HTTP check is limited to approximately 4KB.
Larger outputs are truncated.
HTTP checks also support TLS. By default, a valid TLS certificate is expected.
Certificate verification can be turned off by setting the `tls_skip_verify`
field to `true` in the check definition. When using TLS, the SNI is implicitly
determined from the URL if it uses a hostname instead of an IP address.
You can explicitly set the SNI value by setting `tls_server_name`.
Consul follows HTTP redirects by default.
To disable redirects, set the `disable_redirects` field to `true`.
The following service definition file snippet is an example
of an HTTP check definition:
<CodeTabs heading="HTTP Check">
```hcl
check = {
id = "api"
name = "HTTP API on port 5000"
http = "https://localhost:5000/health"
tls_server_name = ""
tls_skip_verify = false
method = "POST"
header = {
Content-Type = ["application/json"]
}
body = "{\"method\":\"health\"}"
disable_redirects = true
interval = "10s"
timeout = "1s"
}
```
```json
{
"check": {
"id": "api",
"name": "HTTP API on port 5000",
"http": "https://localhost:5000/health",
"tls_server_name": "",
"tls_skip_verify": false,
"method": "POST",
"header": { "Content-Type": ["application/json"] },
"body": "{\"method\":\"health\"}",
"interval": "10s",
"timeout": "1s"
}
}
```
</CodeTabs>
### TCP check
TCP checks periodically make a TCP connection attempt to the specified IP/hostname and port, waiting `interval` amount of time between attempts.
If no hostname is specified, it defaults to "localhost".
The health check status is `success` if the target host accepts the connection attempt,
otherwise the status is `critical`. In the case of a hostname that
resolves to both IPv4 and IPv6 addresses, an attempt is made to both
addresses, and the first successful connection attempt results in a
successful check. This type of check should be preferred over a script that
uses `netcat` or another external process to check a simple socket operation.
By default, TCP checks are configured with a request timeout equal to 10 seconds.
To configure a custom TCP check timeout value,
specify the `timeout` field in the check definition.
The following service definition file snippet is an example
of a TCP check definition:
<CodeTabs heading="TCP Check">
```hcl
check = {
id = "ssh"
name = "SSH TCP on port 22"
tcp = "localhost:22"
interval = "10s"
timeout = "1s"
}
```
```json
{
"check": {
"id": "ssh",
"name": "SSH TCP on port 22",
"tcp": "localhost:22",
"interval": "10s",
"timeout": "1s"
}
}
```
</CodeTabs>
### UDP check
UDP checks periodically direct the Consul agent to send UDP datagrams
to the specified IP/hostname and port,
waiting `interval` amount of time between attempts.
The check status is set to `success` if any response is received from the targeted UDP server.
Any other result sets the status to `critical`.
By default, UDP checks are configured with a request timeout equal to 10 seconds.
To configure a custom UDP check timeout value,
specify the `timeout` field in the check definition.
If any timeout on read exists, the check is still considered healthy.
The following service definition file snippet is an example
of a UDP check definition:
<CodeTabs heading="UDP Check">
```hcl
check = {
id = "dns"
name = "DNS UDP on port 53"
udp = "localhost:53"
interval = "10s"
timeout = "1s"
}
```
```json
{
"check": {
"id": "dns",
"name": "DNS UDP on port 53",
"udp": "localhost:53",
"interval": "10s",
"timeout": "1s"
}
}
```
</CodeTabs>
### OSService check
OSService checks periodically direct the Consul agent to monitor the health of a service running on
the host operating system as either a Windows service (Windows) or a SystemD service (Unix).
The check is logged as `healthy` if the service is running.
If it is stopped or not running, the status is `critical`. All other results set
the status to `warning`, which indicates that the check is not reliable because
an issue is preventing the check from determining the health of the service.
The following service definition file snippet is an example
of an OSService check definition:
<CodeTabs heading="OSService Check">
```hcl
check = {
id = "myco-svctype-svcname-001"
name = "svcname-001 Windows Service Health"
service_id = "flash_pnl_1"
os_service = "myco-svctype-svcname-001"
interval = "10s"
}
```
```json
{
"check": {
"id": "myco-svctype-svcname-001",
"name": "svcname-001 Windows Service Health",
"service_id": "flash_pnl_1",
"os_service": "myco-svctype-svcname-001",
"interval": "10s"
}
}
```
</CodeTabs>
### Time to live (TTL) check
TTL checks retain their last known state for the specified `ttl` duration.
The state of the check updates periodically over the HTTP interface.
If the `ttl` duration elapses before a new check update
is provided over the HTTP interface,
the check is set to `critical` state.
This mechanism relies on the application to directly report its health.
For example, a healthy app can periodically `PUT` a status update to the HTTP endpoint.
Then, if the app is disrupted and unable to perform this update
before the TTL expires, the health check enters the `critical` state.
The endpoints used to update health information for a given check are: [pass](/consul/api-docs/agent/check#ttl-check-pass),
[warn](/consul/api-docs/agent/check#ttl-check-warn), [fail](/consul/api-docs/agent/check#ttl-check-fail),
and [update](/consul/api-docs/agent/check#ttl-check-update). TTL checks also persist their
last known status to disk. This persistence allows the Consul agent to restore the last known
status of the check across agent restarts. Persisted check status is valid through the
end of the TTL from the time of the last check.
To manually mark a service unhealthy,
it is far more convenient to use the maintenance mode
[CLI command](/consul/commands/maint) or
[HTTP API endpoint](/consul/api-docs/agent#enable-maintenance-mode)
rather than a TTL health check with arbitrarily high `ttl`.
The following service definition file snippet is an example
of a TTL check definition:
<CodeTabs heading="TTL Check">
```hcl
check = {
id = "web-app"
name = "Web App Status"
notes = "Web app does a curl internally every 10 seconds"
ttl = "30s"
}
```
```json
{
"check": {
"id": "web-app",
"name": "Web App Status",
"notes": "Web app does a curl internally every 10 seconds",
"ttl": "30s"
}
}
```
</CodeTabs>
### Docker check
These checks depend on periodically invoking an external application that
is packaged within a Docker Container. The application is triggered within the running
container through the Docker Exec API. We expect that the Consul agent user has access
to either the Docker HTTP API or the unix socket. Consul uses `$DOCKER_HOST` to
determine the Docker API endpoint. The application is expected to run, perform a health
check of the service running inside the container, and exit with an appropriate exit code.
The check should be paired with an invocation interval. The shell on which the check
has to be performed is configurable, making it possible to run containers which
have different shells on the same host.
The output of a Docker check is limited to 4KB.
Larger outputs are truncated.
Docker checks are not enabled by default.
To enable a Consul agent to perform Docker checks,
use one of the following agent configuration options:
- [`enable_local_script_checks`](/consul/docs/agent/config/cli-flags#_enable_local_script_checks):
Enable script checks defined in local config files.
Script checks registered using the HTTP API are not allowed.
- [`enable_script_checks`](/consul/docs/agent/config/cli-flags#_enable_script_checks):
Enable script checks no matter how they are registered.
!> **Security Warning:**
We recommend using `enable_local_script_checks` instead of `enable_script_checks` in production
environments, as remote script checks are more vulnerable to malware attacks. Learn more about how [script checks can be exploited](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations#how-script-checks-can-be-exploited).
The following service definition file snippet is an example
of a Docker check definition:
<CodeTabs heading="Docker Check">
```hcl
check = {
id = "mem-util"
name = "Memory utilization"
docker_container_id = "f972c95ebf0e"
shell = "/bin/bash"
args = ["/usr/local/bin/check_mem.py"]
interval = "10s"
}
```
```json
{
"check": {
"id": "mem-util",
"name": "Memory utilization",
"docker_container_id": "f972c95ebf0e",
"shell": "/bin/bash",
"args": ["/usr/local/bin/check_mem.py"],
"interval": "10s"
}
}
```
</CodeTabs>
### gRPC check
gRPC checks are intended for applications that support the standard
[gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
The state of the check will be updated by periodically probing the configured endpoint,
waiting `interval` amount of time between attempts.
By default, gRPC checks are configured with a timeout equal to 10 seconds.
To configure a custom Docker check timeout value,
specify the `timeout` field in the check definition.
gRPC checks default to not using TLS.
To enable TLS, set `grpc_use_tls` in the check definition.
If TLS is enabled, then by default, a valid TLS certificate is expected.
Certificate verification can be turned off by setting the
`tls_skip_verify` field to `true` in the check definition.
To check on a specific service instead of the whole gRPC server,
add the service identifier after the `gRPC` check's endpoint.
The following example shows a gRPC check for a whole application:
<CodeTabs heading="gRPC Check">
```hcl
check = {
id = "mem-util"
name = "Service health status"
grpc = "127.0.0.1:12345"
grpc_use_tls = true
interval = "10s"
}
```
```json
{
"check": {
"id": "mem-util",
"name": "Service health status",
"grpc": "127.0.0.1:12345",
"grpc_use_tls": true,
"interval": "10s"
}
}
```
</CodeTabs>
The following example shows a gRPC check for the specific `my_service` service:
<CodeTabs heading="gRPC Specific Service Check">
```hcl
check = {
id = "mem-util"
name = "Service health status"
grpc = "127.0.0.1:12345/my_service"
grpc_use_tls = true
interval = "10s"
}
```
```json
{
"check": {
"id": "mem-util",
"name": "Service health status",
"grpc": "127.0.0.1:12345/my_service",
"grpc_use_tls": true,
"interval": "10s"
}
}
```
</CodeTabs>
### H2ping check
H2ping checks test an endpoint that uses http2 by connecting to the endpoint
and sending a ping frame, waiting `interval` amount of time between attempts.
If the ping is successful within a specified timeout,
then the check status is set to `success`.
By default, h2ping checks are configured with a request timeout equal to 10 seconds.
To configure a custom h2ping check timeout value,
specify the `timeout` field in the check definition.
TLS is enabled by default.
To disable TLS and use h2c, set `h2ping_use_tls` to `false`.
If TLS is not disabled, a valid certificate is required unless `tls_skip_verify` is set to `true`.
The following service definition file snippet is an example
of an h2ping check definition:
<CodeTabs heading="H2ping Check">
```hcl
check = {
id = "h2ping-check"
name = "h2ping"
h2ping = "localhost:22222"
interval = "10s"
h2ping_use_tls = false
}
```
```json
{
"check": {
"id": "h2ping-check",
"name": "h2ping",
"h2ping": "localhost:22222",
"interval": "10s",
"h2ping_use_tls": false
}
}
```
</CodeTabs>
### Alias check
These checks alias the health state of another registered
node or service. The state of the check updates 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 state is set to `critical`.
For the blocking query, the check uses the ACL token set on the service or check definition.
If no ACL token is set in the service or check definition,
the blocking query uses the agent's default ACL token
([`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default)).
~> **Configuration info**: The alias check configuration expects the alias to be
registered on the same agent as the one you are aliasing. If the service is
not registered with the same agent, `"alias_node": "<node_id>"` must also be
specified. When using `alias_node`, 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.
The following service definition file snippet is an example
of an alias check for a local service:
<CodeTabs heading="Alias Check">
```hcl
check = {
id = "web-alias"
alias_service = "web"
}
```
```json
{
"check": {
"id": "web-alias",
"alias_service": "web"
}
}
```
</CodeTabs>
## Check definition
This section covers some of the most common options for check definitions.
For a complete list of all check options, refer to the
[Register Check HTTP API endpoint documentation](/consul/api-docs/agent/check#json-request-body-schema).
-> **Casing for check options:**
The correct casing for an option depends on whether the check is defined in
a service definition file or an HTTP API JSON request body.
For example, the option `deregister_critical_service_after` in a service
definition file is instead named `DeregisterCriticalServiceAfter` in an
HTTP API JSON request body.
#### General options
- `name` `(string: <required>)` - Specifies the name of the check.
- `id` `(string: "")` - Specifies a unique ID for this check on this node.
If unspecified, Consul defines the check id by:
- If the check definition is embedded within a service definition file,
a unique check id is auto-generated.
- Otherwise, the `id` is set to the value of `name`.
If names might conflict, you must provide unique IDs to avoid
overwriting existing checks with the same id on this node.
- `interval` `(string: <required for interval-based checks>)` - Specifies
the frequency at which to run this check.
Required for all check types except TTL and alias checks.
The value is parsed by Go's `time` package, and has the following
[formatting specification](https://golang.org/pkg/time/#ParseDuration):
> A duration string is a possibly signed sequence of decimal numbers, each with
> optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
> Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
- `service_id` `(string: <required for service health checks>)` - Specifies
the ID of a service instance to associate this check with.
That service instance must be on this node.
If not specified, this check is treated as a node-level check.
For more information, refer to the
[service-bound checks](#service-bound-checks) section.
- `status` `(string: "")` - Specifies the initial status of the health check as
"critical" (default), "warning", or "passing". For more details, refer to
the [initial health check status](#initial-health-check-status) section.
-> **Health defaults to critical:** If health status it not initially specified,
it defaults to "critical" to protect against including a service
in discovery results before it is ready.
- `deregister_critical_service_after` `(string: "")` - If specified,
the associated service and all its checks are deregistered
after this check is in the critical state for more than the specified value.
The value has the same formatting specification as the [`interval`](#interval) field.
The minimum timeout is 1 minute,
and the process that reaps critical services runs every 30 seconds,
so it may take slightly longer than the configured timeout to trigger the deregistration.
This field should generally be configured with a timeout that's significantly longer than
any expected recoverable outage for the given service.
- `notes` `(string: "")` - Provides a human-readable description of the check.
This field is opaque to Consul and can be used however is useful to the user.
For example, it could be used to describe the current state of the check.
- `token` `(string: "")` - Specifies an ACL token used for any interaction
with the catalog for the check, including
[anti-entropy syncs](/consul/docs/architecture/anti-entropy) 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.
#### Success/failures before passing/warning/critical
To prevent flapping health checks and limit the load they cause on the cluster,
a health check may be configured to become passing/warning/critical only after a
specified number of consecutive checks return as passing/critical.
The status does not transition states until the configured threshold is reached.
- `success_before_passing` - Number of consecutive successful results required
before check status transitions to passing. Defaults to `0`. Added in Consul 1.7.0.
- `failures_before_warning` - Number of consecutive unsuccessful results required
before check status transitions to warning. Defaults to the same value as that of
`failures_before_critical` to maintain the expected behavior of not changing the
status of service checks to `warning` before `critical` unless configured to do so.
Values higher than `failures_before_critical` are invalid. Added in Consul 1.11.0.
- `failures_before_critical` - Number of consecutive unsuccessful results required
before check status transitions to critical. Defaults to `0`. Added in Consul 1.7.0.
This feature is available for all check types except TTL and alias checks.
By default, both passing and critical thresholds are set to 0 so the check
status always reflects the last check result.
<CodeTabs heading="Flapping Prevention Example">
```hcl
checks = [
{
name = "HTTP TCP on port 80"
tcp = "localhost:80"
interval = "10s"
timeout = "1s"
success_before_passing = 3
failures_before_warning = 1
failures_before_critical = 3
}
]
```
```json
{
"checks": [
{
"name": "HTTP TCP on port 80",
"tcp": "localhost:80",
"interval": "10s",
"timeout": "1s",
"success_before_passing": 3,
"failures_before_warning": 1,
"failures_before_critical": 3
}
]
}
```
</CodeTabs>
## Initial health check status
By default, when checks are registered against a Consul agent, the state is set
immediately to "critical". This is useful to prevent services from being
registered as "passing" and entering the service pool before they are confirmed
to be healthy. In certain cases, it may be desirable to specify the initial
state of a health check. This can be done by specifying the `status` field in a
health check definition, like so:
<CodeTabs heading="Status Field Example">
```hcl
check = {
id = "mem"
args = ["/bin/check_mem", "-limit", "256MB"]
interval = "10s"
status = "passing"
}
```
```json
{
"check": {
"id": "mem",
"args": ["/bin/check_mem", "-limit", "256MB"],
"interval": "10s",
"status": "passing"
}
}
```
</CodeTabs>
The above service definition would cause the new "mem" check to be
registered with its initial state set to "passing".
## Service-bound checks
Health checks may optionally be bound to a specific service. This ensures
that the status of the health check will only affect the health status of the
given service instead of the entire node. Service-bound health checks may be
provided by adding a `service_id` field to a check configuration:
<CodeTabs heading="Status Field Example">
```hcl
check = {
id = "web-app"
name = "Web App Status"
service_id = "web-app"
ttl = "30s"
}
```
```json
{
"check": {
"id": "web-app",
"name": "Web App Status",
"service_id": "web-app",
"ttl": "30s"
}
}
```
</CodeTabs>
In the above configuration, if the web-app health check begins failing, it will
only affect the availability of the web-app service. All other services
provided by the node will remain unchanged.
## Agent certificates for TLS checks
The [enable_agent_tls_for_checks](/consul/docs/agent/config/config-files#enable_agent_tls_for_checks)
agent configuration option can be utilized to have HTTP or gRPC health checks
to use the agent's credentials when configured for TLS.
## Multiple check definitions
Multiple check definitions can be defined using the `checks` (plural)
key in your configuration file.
<CodeTabs heading="Multiple Checks Example">
```hcl
checks = [
{
id = "chk1"
name = "mem"
args = ["/bin/check_mem", "-limit", "256MB"]
interval = "5s"
},
{
id = "chk2"
name = "/health"
http = "http://localhost:5000/health"
interval = "15s"
},
{
id = "chk3"
name = "cpu"
args = ["/bin/check_cpu"]
interval = "10s"
},
...
]
```
```json
{
"checks": [
{
"id": "chk1",
"name": "mem",
"args": ["/bin/check_mem", "-limit", "256MB"],
"interval": "5s"
},
{
"id": "chk2",
"name": "/health",
"http": "http://localhost:5000/health",
"interval": "15s"
},
{
"id": "chk3",
"name": "cpu",
"args": ["/bin/check_cpu"],
"interval": "10s"
},
...
]
}
```
</CodeTabs>

594
website/content/docs/discovery/dns.mdx
View File

@ -1,594 +0,0 @@
---
layout: docs
page_title: Find services with DNS
description: >-
For service discovery use cases, Domain Name Service (DNS) is the main interface to look up, query, and address Consul nodes and services. Learn how a Consul DNS lookup can help you find services by tag, name, namespace, partition, datacenter, or domain.
---
# Query services with DNS
One of the primary query interfaces for Consul is DNS.
The DNS interface allows applications to make use of service
discovery without any high-touch integration with Consul.
For example, instead of making HTTP API requests to Consul,
a host can use the DNS server directly via name lookups
like `redis.service.us-east-1.consul`. This query automatically
translates to a lookup of nodes that provide the `redis` service,
are located in the `us-east-1` datacenter, and have no failing health checks.
It's that simple!
There are a number of configuration options that are important for the DNS interface,
specifically [`client_addr`](/consul/docs/agent/config/config-files#client_addr),[`ports.dns`](/consul/docs/agent/config/config-files#dns_port),
[`recursors`](/consul/docs/agent/config/config-files#recursors),[`domain`](/consul/docs/agent/config/config-files#domain),
[`alt_domain`](/consul/docs/agent/config/config-files#alt_domain), and [`dns_config`](/consul/docs/agent/config/config-files#dns_config).
By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.`
domain, without support for further DNS recursion. Please consult the
[documentation on configuration options](/consul/docs/agent/config),
specifically the configuration items linked above, for more details.
There are a few ways to use the DNS interface. One option is to use a custom
DNS resolver library and point it at Consul. Another option is to set Consul
as the DNS server for a node and provide a
[`recursors`](/consul/docs/agent/config/config-files#recursors) configuration so that non-Consul queries
can also be resolved. The last method is to forward all queries for the "consul."
domain to a Consul agent from the existing DNS server. Review the
[DNS Forwarding tutorial](/consul/tutorials/networking/dns-forwarding?utm_source=docs) for examples.
You can experiment with Consul's DNS server on the command line using tools such as `dig`:
```shell-session
$ dig @127.0.0.1 -p 8600 redis.service.dc1.consul. ANY
```
-> **Note:** In DNS, all queries are case-insensitive. A lookup of `PostgreSQL.node.dc1.consul` will find all nodes named `postgresql`.
## Node Lookups
To resolve names, Consul relies on a very specific format for queries.
There are fundamentally two types of queries: node lookups and service lookups.
A node lookup, a simple query for the address of a named node, looks like this:
```text
<node>.node[.<datacenter>].<domain>
```
For example, if we have a `foo` node with default settings, we could
look for `foo.node.dc1.consul.` The datacenter is an optional part of
the FQDN: if not provided, it defaults to the datacenter of the agent.
If we know `foo` is running in the same datacenter as our local agent,
we can instead use `foo.node.consul.` This convention allows for terse
syntax where appropriate while supporting queries of nodes in remote
datacenters as necessary.
For a node lookup, the only records returned are A and AAAA records
containing the IP address, and TXT records containing the
`node_meta` values of the node.
```shell-session
$ dig @127.0.0.1 -p 8600 foo.node.consul ANY
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 foo.node.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 24355
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 0
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;foo.node.consul. IN ANY
;; ANSWER SECTION:
foo.node.consul. 0 IN A 10.1.10.12
foo.node.consul. 0 IN TXT "meta_key=meta_value"
foo.node.consul. 0 IN TXT "value only"
;; AUTHORITY SECTION:
consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
```
By default the TXT records value will match the node's metadata key-value
pairs according to [RFC1464](https://www.ietf.org/rfc/rfc1464.txt).
Alternatively, the TXT record will only include the node's metadata value when the
node's metadata key starts with `rfc1035-`.
### Node Lookups for Consul Enterprise <EnterpriseAlert inline />
Consul nodes exist at the admin partition level within a datacenter.
By default, the partition and datacenter used in a [node lookup](#node-lookups) are
the partition and datacenter of the Consul agent that received the DNS query.
Use the following query format to specify a partition for a node lookup:
```text
<node>.node.<partition>.ap.<datacenter>.dc.<domain>
```
Consul server agents are in the `default` partition.
If DNS queries are addressed to Consul server agents,
node lookups to non-`default` partitions must explicitly specify
the partition of the target node.
## Service Lookups
A service lookup is used to query for service providers. Service queries support
two lookup methods: standard and strict [RFC 2782](https://tools.ietf.org/html/rfc2782).
By default, SRV weights are all set at 1, but changing weights is supported using the
`Weights` attribute of the [service definition](/consul/docs/discovery/services).
Note that DNS is limited in size per request, even when performing DNS TCP
queries.
For services having many instances (more than 500), it might not be possible to
retrieve the complete list of instances for the service.
When DNS SRV response are sent, order is randomized, but weights are not
taken into account. In the case of truncation different clients using weighted SRV
responses will have partial and inconsistent views of instances weights so the
request distribution could be skewed from the intended weights. In that case,
it is recommended to use the HTTP API to retrieve the list of nodes.
### Standard Lookup
The format of a standard service lookup is:
```text
[<tag>.]<service>.service[.<datacenter>].<domain>
```
The `tag` is optional, and, as with node lookups, the `datacenter` is as
well. If no tag is provided, no filtering is done on tag. If no
datacenter is provided, the datacenter of this Consul agent is assumed.
If we want to find any redis service providers in our local datacenter,
we could query `redis.service.consul.` If we want to find the PostgreSQL
primary in a particular datacenter, we could query
`primary.postgresql.service.dc2.consul.`
The DNS query system makes use of health check information to prevent routing
to unhealthy nodes. When a service query is made, any services failing their health
check or failing a node system check will be omitted from the results. To allow
for simple load balancing, the set of nodes returned is also randomized each time.
These mechanisms make it easy to use DNS along with application-level retries
as the foundation for an auto-healing service oriented architecture.
For standard services queries, both A and SRV records are supported. SRV records
provide the port that a service is registered on, enabling clients to avoid relying
on well-known ports. SRV records are only served if the client specifically requests
them, like so:
```shell-session
$ dig @127.0.0.1 -p 8600 consul.service.consul SRV
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 50483
;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;consul.service.consul. IN SRV
;; ANSWER SECTION:
consul.service.consul. 0 IN SRV 1 1 8300 foobar.node.dc1.consul.
;; ADDITIONAL SECTION:
foobar.node.dc1.consul. 0 IN A 10.1.10.12
```
### RFC 2782 Lookup
Valid formats for RFC 2782 SRV lookups depend on
whether you want to filter results based on a service tag:
- No filtering on service tag:
```text
_<service>._tcp[.service][.<datacenter>].<domain>
```
- Filtering on service tag specified in the RFC 2782 protocol field:
```text
_<service>._<tag>[.service][.<datacenter>].<domain>
```
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries must
prepend an underscore (`_`) to the `service` and `protocol` values in a query to
prevent DNS collisions.
To perform no tag-based filtering, specify `tcp` in the RFC 2782 protocol field.
To filter results on a service tag, specify the tag in the RFC 2782 protocol field.
Other than the query format and default `tcp` protocol/tag value, the behavior
of the RFC style lookup is the same as the standard style of lookup.
If you registered the service `rabbitmq` on port 5672 and tagged it with `amqp`,
you could make an RFC 2782 query for its SRV record as `_rabbitmq._amqp.service.consul`:
```shell-session
$ dig @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 52838
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;_rabbitmq._amqp.service.consul. IN SRV
;; ANSWER SECTION:
_rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul.
;; ADDITIONAL SECTION:
rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20
```
Again, note that the SRV record returns the port of the service as well as its IP.
#### SRV response for hosts in the .addr subdomain
If a service registered to Consul has an explicit IP [`address`](/consul/api-docs/agent/service#address)
or tagged address(es) defined on the service registration, the hostname returned
in the target field of the answer section for the DNS SRV query for the service
will be in the format of `<hexadecimal-encoded IP>.addr.<datacenter>.consul`.
<Tabs>
<Tab heading="IPv4">
In the example below, the `rabbitmq` service has been registered with an explicit
IPv4 address of `192.0.2.10`.
<CodeTabs heading="Service defined with explicit IPv4 address in agent config" filename="agent-config.hcl">
```hcl
node_name = "node1"
services {
name = "rabbitmq"
address = "192.0.2.10"
port = 5672
}
```
```json
{
"node_name": "node1",
"services": [
{
"name": "rabbitmq",
"address": "192.0.2.10",
"port": 5672
}
]
}
```
</CodeTabs>
When performing an SRV query for this service, the SRV response contains a single
record with a hostname in the format of `<hexadecimal-encoded IP>.addr.<datacenter>.consul`.
```shell-session
$ dig @127.0.0.1 -p 8600 -t srv _rabbitmq._tcp.service.consul +short
1 1 5672 c000020a.addr.dc1.consul.
```
In this example, the hex-encoded IP from the returned hostname is `c000020a`.
Converting each hex octet to decimal reveals the IP address that was specified
in the service registration.
```shell-session
$ echo -n "c000020a" | perl -ne 'printf("%vd\n", pack("H*", $_))'
192.0.2.10
```
</Tab>
<Tab heading="IPv6">
In the example below, the `rabbitmq` service has been registered with an explicit
IPv6 address of `2001:db8:1:2:cafe::1337`.
<CodeTabs heading="Service defined with explicit IPv6 address in agent config" filename="agent-config.hcl">
```hcl
node_name = "node1"
services {
name = "rabbitmq"
address = "2001:db8:1:2:cafe::1337"
port = 5672
}
```
```json
{
"node_name": "node1",
"services": [
{
"name": "rabbitmq",
"address": "2001:db8:1:2:cafe::1337",
"port": 5672
}
]
}
```
</CodeTabs>
When performing an SRV query for this service, the SRV response contains a single
record with a hostname in the format of `<hexadecimal-encoded IP>.addr.<datacenter>.consul`.
```shell-session
$ dig @127.0.0.1 -p 8600 -t srv _rabbitmq._tcp.service.consul +short
1 1 5672 20010db800010002cafe000000001337.addr.dc1.consul.
```
In this example, the hex-encoded IP from the returned hostname is
`20010db800010002cafe000000001337`. This is the fully expanded IPv6 address with
colon separators removed.
The following command re-adds the colon separators to display the fully expanded
IPv6 address that was specified in the service registration.
```shell-session
$ echo -n "20010db800010002cafe000000001337" | perl -ne 'printf join(":", unpack("(A4)*", $_))."\n"'
2001:0db8:0001:0002:cafe:0000:0000:1337
```
</Tab>
</Tabs>
### Service Lookups for Consul Enterprise <EnterpriseAlert inline />
By default, all service lookups use the `default` namespace
within the partition and datacenter of the Consul agent that received the DNS query.
To lookup services in another namespace, partition, and/or datacenter,
use the [canonical format](#canonical-format).
Consul server agents are in the `default` partition.
If DNS queries are addressed to Consul server agents,
service lookups to non-`default` partitions must explicitly specify
the partition of the target service.
To lookup services imported from a cluster peer,
refer to [service virtual IP lookups for Consul Enterprise](#service-virtual-ip-lookups-for-consul-enterprise) instead.
#### Canonical format
Use the following query format to specify namespace, partition, and/or datacenter
for `.service`, `.connect`, `.virtual`, and `.ingress` service lookup types.
All three fields (`namespace`, `partition`, `datacenter`) are optional.
```text
[<tag>.]<service>.service[.<namespace>.ns][.<partition>.ap][.<datacenter>.dc]<domain>
```
#### Alternative formats for specifying namespace
Though the [canonical format](#canonical-format) is recommended for readability,
you can use the following query formats specify namespace but not partition:
- Specify both namespace and datacenter:
```text
[<tag>.]<service>.service.<namespace>.<datacenter>.<domain>
```
- **Deprecated in Consul 1.11:**
Specify namespace without a datacenter,
which requires that DNS queries are addressed to a Consul agent with
[`dns_config.prefer_namespace`](/consul/docs/agent/config/config-files#dns_prefer_namespace)
set to `true`:
```text
[<tag>.]<service>.service.<namespace>.<domain>
```
### Prepared Query Lookups
The following formats are valid for prepared query lookups:
- Standard lookup
```text
<query name or id>.query[.<datacenter>].<domain>
```
- [RFC 2782](https://tools.ietf.org/html/rfc2782) SRV lookup
```text
_<query name or id>._tcp.query[.<datacenter>].<domain>
```
The `datacenter` is optional, and if not provided, the datacenter of this Consul
agent is assumed.
The `query name or id` is the given name or ID of an existing
[Prepared Query](/consul/api-docs/query). These behave like standard service
queries but provide a much richer set of features, such as filtering by multiple
tags and automatically failing over to look for services in remote datacenters if
no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also
added support for [prepared query templates](/consul/api-docs/query#prepared-query-templates)
which can match names using a prefix match, allowing one template to apply to
potentially many services.
To allow for simple load balancing, the set of nodes returned is randomized each time.
Both A and SRV records are supported. SRV records provide the port that a service is
registered on, enabling clients to avoid relying on well-known ports. SRV records are
only served if the client specifically requests them.
### Connect-Capable Service Lookups
To find Connect-capable services:
```text
<service>.connect.<domain>
```
This will find all [Connect-capable](/consul/docs/connect)
endpoints for the given `service`. A Connect-capable endpoint may be
both a proxy for a service or a natively integrated Connect application.
The DNS interface does not differentiate the two.
Most services will use a [proxy](/consul/docs/connect/proxies) that handles
service discovery automatically and therefore won't use this DNS format.
This DNS format is primarily useful for [Connect-native](/consul/docs/connect/native)
applications.
This endpoint currently only finds services within the same datacenter
and doesn't support tags. This DNS interface will be expanded over time.
If you need more complex behavior, please use the
[catalog API](/consul/api-docs/catalog).
### Service Virtual IP Lookups
To find the unique virtual IP allocated for a service:
```text
<service>.virtual[.<peer>].<domain>
```
This will return the unique virtual IP for any [Connect-capable](/consul/docs/connect)
service. Each Connect service has a virtual IP assigned to it by Consul - this is used
by sidecar proxies for the [Transparent Proxy](/consul/docs/connect/transparent-proxy) feature.
The peer name is an optional part of the FQDN, and it is used to query for the virtual IP
of a service imported from that peer.
The virtual IP is also added to the service's [Tagged Addresses](/consul/docs/discovery/services#tagged-addresses)
under the `consul-virtual` tag.
#### Service Virtual IP Lookups for Consul Enterprise <EnterpriseAlert inline />
By default, a service virtual IP lookup uses the `default` namespace
within the partition and datacenter of the Consul agent that received the DNS query.
To lookup services imported from a cluster peered partition or open-source datacenter,
specify the namespace and peer name in the lookup:
```text
<service>.virtual[.<namespace>].<peer>.<domain>
```
To lookup services not imported from a cluster peer,
refer to [service lookups for Consul Enterprise](#service-lookups-for-consul-enterprise) instead.
### Ingress Service Lookups
To find ingress-enabled services:
```text
<service>.ingress.<domain>
```
This will find all [ingress gateway](/consul/docs/connect/gateways/ingress-gateway)
endpoints for the given `service`.
This endpoint currently only finds services within the same datacenter
and doesn't support tags. This DNS interface will be expanded over time.
If you need more complex behavior, please use the
[catalog API](/consul/api-docs/catalog).
### UDP Based DNS Queries
When the DNS query is performed using UDP, Consul will truncate the results
without setting the truncate bit. This is to prevent a redundant lookup over
TCP that generates additional load. If the lookup is done over TCP, the results
are not truncated.
## Alternative Domain
By default, Consul responds to DNS queries in the `consul` domain,
but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/consul/docs/agent/config/config-files#domain) parameter.
In some instances, Consul may need to respond to queries in more than one domain,
such as during a DNS migration or to distinguish between internal and external queries.
Consul versions 1.5.2+ can be configured to respond to DNS queries on an alternative domain
through the [`alt_domain`](/consul/docs/agent/config/config-files#alt_domain) agent configuration
option. As of Consul versions 1.11.0+, Consul's DNS response will use the same domain as was used in the query;
in prior versions, the response may use the primary [`domain`](/consul/docs/agent/config/config-files#domain) no matter which
domain was used in the query.
In the following example, the `alt_domain` parameter is set to `test-domain`:
```hcl
alt_domain = "test-domain"
```
```shell-session
$ dig @127.0.0.1 -p 8600 consul.service.test-domain SRV
```
The following responses are returned:
```
;; QUESTION SECTION:
;consul.service.test-domain. IN SRV
;; ANSWER SECTION:
consul.service.test-domain. 0 IN SRV 1 1 8300 machine.node.dc1.test-domain.
;; ADDITIONAL SECTION:
machine.node.dc1.test-domain. 0 IN A 127.0.0.1
machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment="
```
-> **PTR queries:** Responses to PTR queries (`<ip>.in-addr.arpa.`) will always use the
[primary domain](/consul/docs/agent/config/config-files#domain) (not the alternative domain),
as there is no way for the query to specify a domain.
## Caching
By default, all DNS results served by Consul set a 0 TTL value. This disables
caching of DNS results. However, there are many situations in which caching is
desirable for performance and scalability. This is discussed more in the tutorial
for [DNS caching](/consul/tutorials/networking/dns-caching).
## WAN Address Translation
By default, Consul DNS queries will return a node's local address, even when
being queried from a remote datacenter. If you need to use a different address
to reach a node from outside its datacenter, you can configure this behavior
using the [`advertise-wan`](/consul/docs/agent/config/cli-flags#_advertise-wan) and
[`translate_wan_addrs`](/consul/docs/agent/config/config-files#translate_wan_addrs) configuration
options.
## DNS with ACLs
In order to use the DNS interface when
[Access Control Lists (ACLs)](/consul/docs/security/acl)
are enabled, you must first create ACL tokens with the necessary policies.
Consul agents resolve DNS requests using one of the preconfigured tokens below,
listed in order of precedence:
1. The agent's [`default` token](/consul/docs/agent/config/config-files#acl_tokens_default).
2. The built-in [`anonymous` token](/consul/docs/security/acl/acl-tokens#built-in-tokens).
Because the anonymous token is used when any request is made to Consul without
explicitly specifying a token, production deployments should not apply policies
needed for DNS to this token.
Consul will either accept or deny the request depending on whether the token
has the appropriate authorization. The following table describes the available
DNS lookups and required policies when ACLs are enabled:
| Lookup | Type | Description | ACLs Required |
| ------------------------------------------------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `*.node.consul` | [Node](#node-lookups) | Allow resolving DNS requests for the target node (i.e., `<target>.node.consul`) | [`node:read`](/consul/docs/security/acl/acl-rules#node-rules) |
| `*.service.consul`, `*.connect.consul`, `*.ingress.consul`, `*.virtual.consul` | [Service: standard](#service-lookups) | Allow resolving DNS requests for target service (e.g., `<target>.service.consul`) instances running on ACL-authorized nodes | [`service:read`](/consul/docs/security/acl/acl-rules#service-rules), [`node:read`](/consul/docs/security/acl/acl-rules#node-rules) |
| `*.query.consul` | [Service: prepared query](#prepared-query-lookups) | Allow resolving DNS requests for [service instances specified](/consul/api-docs/query#service-1) by the target prepared query (i.e., `<target>.query.consul`) running on ACL-authorized nodes | [`query:read`](/consul/docs/security/acl/acl-rules#prepared-query-rules), [`service:read`](/consul/docs/security/acl/acl-rules#service-rules), [`node:read`](/consul/docs/security/acl/acl-rules#node-rules) |
For guidance on how to configure an appropriate token for DNS, refer to the
securing Consul with ACLs guides for:
- [Production Environments](/consul/tutorials/security/access-control-setup-production#token-for-dns)
- [Development Environments](/consul/tutorials/day-0/access-control-setup?utm_source=docs#enable-acls-on-consul-clients)

701
website/content/docs/discovery/services.mdx
View File

@ -1,701 +0,0 @@
---
layout: docs
page_title: Register Services with Service Definitions
description: >-
Define and register services and their health checks with Consul to make a service available for service discovery or service mesh access. Learn how to format service definitions with this reference page and sample code.
---
# Register Services with Service Definitions
One of the main goals of service discovery is to provide a catalog of available
services. To that end, the agent provides a simple service definition format
to declare the availability of a service and to potentially associate it with
a health check. A health check associated with a service is considered to be an
application-level check. Define services in a configuration file or add it at
runtime using the HTTP interface.
Complete the [Getting Started tutorials](/consul/tutorials/get-started-vms/virtual-machine-gs-service-discovery) to get hands-on experience registering a simple service with a health check on your local machine.
## Service Definition
Configure a service by providing the service definition to the agent. You can
either specify the configuration file using the `-config-file` option, or specify
the directory containing the service definition file with the `-config-dir` option.
Consul can load service definitions saved as `.json` or `.hcl` files.
Send a `SIGHUP` to the running agent or use [`consul reload`](/consul/commands/reload) to check for new service definitions or to
update existing services. Alternatively, the service can be [registered dynamically](/consul/api-docs/agent/service#register-service)
using the [HTTP API](/consul/api-docs).
A service definition contains a set of parameters that specify various aspects of the service, including how it is discovered by other services in the network.
All possible parameters are included in the following example, but only the top-level `service` parameter and its `name` parameter child are required by default.
<CodeTabs heading="Service Definition">
```hcl
service {
name = "redis"
id = "redis"
port = 80
tags = ["primary"]
meta = {
custom_meta_key = "custom_meta_value"
}
tagged_addresses = {
lan = {
address = "192.168.0.55"
port = 8000
}
wan = {
address = "198.18.0.23"
port = 80
}
}
port = 8000
socket_path = "/tmp/redis.sock"
enable_tag_override = false
checks = [
{
args = ["/usr/local/bin/check_redis.py"]
interval = "10s"
}
]
kind = "connect-proxy"
proxy_destination = "redis"
proxy = {
destination_service_name = "redis"
destination_service_id = "redis1"
local_service_address = "127.0.0.1"
local_service_port = 9090
local_service_socket_path = "/tmp/redis.sock"
mode = "transparent"
transparent_proxy {
outbound_listener_port = 22500
}
mesh_gateway = {
mode = "local"
}
expose = {
checks = true
paths = [
{
path = "/healthz"
local_path_port = 8080
listener_port = 21500
protocol = "http2"
}
]
}
}
connect = {
native = false
}
weights = {
passing = 5
warning = 1
}
token = "233b604b-b92e-48c8-a253-5f11514e4b50"
namespace = "foo"
}
```
```json
{
"service": {
"id": "redis",
"name": "redis",
"tags": ["primary"],
"address": "",
"meta": {
"meta": "for my service"
},
"tagged_addresses": {
"lan": {
"address": "192.168.0.55",
"port": 8000,
},
"wan": {
"address": "198.18.0.23",
"port": 80
}
},
"port": 8000,
"socket_path": "/tmp/redis.sock",
"enable_tag_override": false,
"checks": [
{
"args": ["/usr/local/bin/check_redis.py"],
"interval": "10s"
}
],
"kind": "connect-proxy",
"proxy_destination": "redis", // Deprecated
"proxy": {
"destination_service_name": "redis",
"destination_service_id": "redis1",
"local_service_address": "127.0.0.1",
"local_service_port": 9090,
"local_service_socket_path": "/tmp/redis.sock",
"mode": "transparent",
"transparent_proxy": {
"outbound_listener_port": 22500
},
"config": {},
"upstreams": [],
"mesh_gateway": {
"mode": "local"
},
"expose": {
"checks": true,
"paths": [
{
"path": "/healthz",
"local_path_port": 8080,
"listener_port": 21500,
"protocol": "http2"
}
]
}
},
"connect": {
"native": false,
"sidecar_service": {}
"proxy": { // Deprecated
"command": [],
"config": {}
}
},
"weights": {
"passing": 5,
"warning": 1
},
"token": "233b604b-b92e-48c8-a253-5f11514e4b50",
"namespace": "foo"
}
}
```
</CodeTabs>
The following table describes the available parameters for service definitions.
### `service`
This is the root-level parameter that defines the service. You can specify the parameters to configure the service.
| Parameter | Description | Default | Required |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------- |
| `id` | String value that specifies the service ID. <p>If not specified, the value of the `name` field will be used. </p><p>Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services.</p> | Value of the `name` parameter | Optional |
| `name` | Specifies the name of the service. <br/>The value for this parameter is used as the ID if the `id` parameter is not specified.<br/>We recommend using valid DNS labels for service definition names for compatibility with external DNSs. | None | Required |
| `tags` | List of string values that can be used to add service-level labels. <br/>For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions. <br/>We recommend using valid DNS labels for service definition IDs for compatibility with external DNSs.<br/>Tag values are opaque to Consul.<br/> | None | Optional |
| `address` | String value that specifies a service-specific IP address or hostname. <br/>If no value is specified, the IP address of the agent node is used by default. <br/>There is no service-side validation of this parameter. | IP address of the agent node | Optional |
| `meta` | Object that defines a map of the max 64 key/value pairs. <br/>The meta object has the same limitations as the node meta object in the node definition. <br/>Meta data can be retrieved per individual instance of the service. All instances of a given service have their own copy of the meta data. <br/> See [Adding Meta Data](#adding-meta-data) for supported parameters.<br/> | None | Optional |
| `tagged_addresses` | Tagged addresses are additional addresses that may be defined for a node or service. See [Tagged Addresses](#tagged-addresses) for details. | None | Optional |
| `port` | Integer value that specifies a service-specific port number. The port number should be specified when the `address` parameter is defined to improve service discoverability. | Optional |
| `socket_path` | String value that specifies the path to the service socket. <br/>Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket. | None | Optional |
| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled. <br/> If set to `true`, then external agents can update this service in the catalog and modify the tags.<br/> Subsequent local sync operations by this agent will ignore the updated tags. <br/> This parameter only applies to the locally-registered service. If multiple nodes register the same service, the `enable_tag_override` configuration, and all other service configuration items, operate independently. <br/>Updating the tags for services registered on one node is independent from the same service (by name) registered on another node. <br/> See [anti-entropy syncs](/consul/docs/architecture/anti-entropy) for additional information.<br/> | False | Optional |
| `checks` | Array of objects that define health checks for the service. See [Health Checks](#health-checks) for details. | None | Optional |
| `kind` | String value that identifies the service as a Connect proxy. See [Connect](#connect) for details. | None | Optional |
| `proxy_destination` | String value that specifies the _name_ of the destination service that the service currently being configured proxies to. <br/>This parameter is deprecated. Use `proxy.destination_service` instead. <br/>See [Connect](#connect) for additional information. | None | Optional |
| `proxy` | Object that defines the destination services that the service currently being configured proxies to. See [Proxy](#proxy) for additional information. | None | Optional |
| `connect` | Object that configures a Consul Connect service mesh connection. See [Connect](#connect) for details. | None | Optional |
| `weights` | Object that configures the weight of the service in terms of its DNS service (SRV) response. See [DNS SRV Weights](#dns-srv-weights) for details. | None | Optional |
| `token` | String value specifying the ACL token to be used to register the service (if the ACL system is enabled). The token is required for the service to interact with the service catalog. See [Security Configurations](#security-configurations) for details. | None | Required if ACLs are enabled |
| `namespace` | String value specifying the Consul Namespace where the service should be registered. See [Security Configurations](#security-configurations) for details. | None | Optional |
### Adding Meta Data
You can add semantic meta data to the service using the `meta` parameter. This parameter defines a map of max 64 key/value pairs. You can specify the following parameters to define meta data for the service.
| Parameter | Description | Default | Required |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| `KEY` | String value that adds semantic metadata to the service. <br/>Keys can only have ASCII characters (`A` - `Z`, `a` - `z`, `0` - `9`, `_`, and `-`). <br/>Keys can not have special characters. <br/>Keys are limited to 128 characters.<br/>Values are limited to 512 characters. | None | Optional |
### Security Configurations
If the ACL system is enabled, specify a value for the `token` parameter to provide an ACL token. This token is
used for any interaction with the catalog for the service, including [anti-entropy syncs](/consul/docs/architecture/anti-entropy) and deregistration.
Services registered in Consul clusters where both [Consul Namespaces](/consul/docs/enterprise/namespaces)<EnterpriseAlert inline />
and the ACL system are enabled can be registered to specific namespaces that are associated with
ACL tokens scoped to the namespace. Services registered with a service definition
will not inherit the namespace associated with the ACL token specified in the `token`
field. The `namespace` _and_ the `token` parameters must be included in the service definition for the service to be registered to the
namespace that the ACL token is scoped to.
### Health Checks
You can add health checks to your service definition. Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database
to replace a failed secondary. The health check functionality is strongly integrated into 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 health 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`.
Consul includes several check types with different options. Refer to the [health checks documentation](/consul/docs/discovery/checks) for details.
### Proxy
Service definitions allow for an optional proxy registration. Proxies used with Connect
are registered as services in Consul's catalog.
See the [Proxy Service Registration](/consul/docs/connect/registration/service-registration) reference
for the available configuration options.
### Connect
The `kind` parameter determines the service's role. Services can be configured to perform several roles, but you must omit the `kind` parameter for typical non-proxy instances.
The following roles are supported for service entries:
- `connect-proxy`: Defines the configuration for a connect proxy
- `ingress-gateway`: Defines the configuration for an [ingress gateway](/consul/docs/connect/config-entries/ingress-gateway)
- `mesh-gateway`: Defines the configuration for a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway)
- `terminating-gateway`: Defines the configuration for a [terminating gateway](/consul/docs/connect/config-entries/terminating-gateway#terminating-gateway)
In the service definition example described above, the service is registered as a proxy because the `kind` property is set to `connect-proxy`.
The `proxy` parameter is also required for Connect proxy registrations and is only valid if `kind` is `connect-proxy`.
Refer to the [Proxy Service Registration](/consul/docs/connect/registration/service-registration) documentation for details about this type.
When the `kind` parameter is set to `connect-proxy`, the only required parameter for the `proxy` configuration is `destination_service_name`.
Refer to the [complete proxy configuration example](/consul/docs/connect/registration/service-registration#complete-configuration-example) for additional information.
The `connect` field can be specified to configure [Connect](/consul/docs/connect) for a service. This field is available in Consul 1.2.0 and later. The following parameters are available.
| Parameter | Description | Default | Required |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------- |
| `native` | Boolean value that advertises the service as [Connect-native](/consul/docs/connect/native). <br/>If set to `true`, do not configure a `sidecar_service`. | `false` | Optional |
| `sidecar_service` | Object that defines a nested service definition. <br/>Do not configure if `native` is set to `true`. | See [Sidecar Service Registration](/consul/docs/connect/registration/sidecar-service) for default configurations. | Optional |
-> **Non-service registration roles**: The `kind` values supported for configuration entries are different than what is supported for service registrations. Refer to the [Configuration Entries](/consul/docs/connect/config-entries) documentation for information about non-service registration types.
#### Deprecated parameters
Different Consul Connect parameters are supported for different Consul versions. The following table describes changes applicable to service discovery.
| Parameter | Description | Consul version | Status |
| ------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------- |
| `proxy_destination` | Specified the proxy destination **in the root level** of the definition file. | 1.2.0 to 1.3.0 | Deprecated since 1.5.0. <br/> Use `proxy.destination_service_name` instead. |
| `connect.proxy` | Specified "managed" proxies, [which have been deprecated](/consul/docs/connect/proxies/managed-deprecated). | 1.2.0 (beta) to 1.3.0 (beta) | Deprecated. |
### DNS SRV Weights
You can configure how the service responds to DNS SRV requests by specifying a set of states/weights in the `weights` field.
#### `weights`
When DNS SRV requests are made, the response will include the weights specified for the given state of the service.
This allows some instances to be given higher weight if they have more capacity. It also allows load reduction on
services with checks in `warning` status by giving passing instances a higher weight.
| Parameter | Description | Default | Required |
| --------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------- |
| `STATE` | Integer value indicating its weight. A higher number indicates more weight. | If not specified, the following weights are used: <br/> `"passing" : 1` <br/> `"warning" : 1` | Optional |
If a service is `critical`, it is excluded from DNS responses.
Services with warning checks are included in responses by default, but excluded if the optional param `only_passing = true`
is present in the agent DNS configuration or the `passing` query parameter is used via the API.
### 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](/consul/docs/architecture/anti-entropy) 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](/consul/docs/architecture/anti-entropy) 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.
### Tagged Addresses
Tagged addresses are additional addresses that may be defined for a node or
service. Tagged addresses can be used by remote agents and services as alternative
addresses for communicating with the given node or service. Multiple tagged
addresses may be configured on a node or service.
The following example describes the syntax for defining a tagged address.
<CodeTabs heading="Tagged address format">
```hcl
service {
name = "redis"
port = 80
tagged_addresses {
<tag> = {
address = "<address>"
port = port
}
}
}
```
```json
{
"service": {
"name": "redis",
"port": 80,
"tagged_addresses": {
"<tag>": {
"address": "<address>",
"port": port
}
}
}
}
```
</CodeTabs>
The following table provides an overview of the various tagged address types supported by Consul.
| Type | Description | Tags |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| LAN | LAN addresses are intended to be directly accessible only from services within the same Consul data center. See [LAN tags](#lan-tags) for details. | `lan` <br/> `lan_ipv4` <br/> `lan_ipv6` |
| Virtual | Virtual tagged addresses are logical address types that can be configured on [Connect](/consul/docs/connect)-enabled services. The virtual address provides a fixed IP address that can be used by downstream services when connecting to an upstream service. See [Virtual tags](#virtual-tags) for details. | `virtual` |
| WAN | Define a WAN address for the service or node when it should be accessed at an alternate address by services in a remote datacenter. See [WAN tags](#wan-tags) for details. | `wan` <br/> `wan_ipv4` <br/> `wan_ipv6` |
#### LAN tags
- `lan` - The IPv4 LAN address at which the node or service is accessible.
- `lan_ipv4` - The IPv4 LAN address at which the node or service is accessible.
- `lan_ipv6` - The IPv6 LAN address at which the node or service is accessible.
<CodeTabs heading="Example LAN tagged address configuration">
<CodeBlockConfig filename="redis-service.hcl">
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
lan = {
address = "192.0.2.10"
port = 80
}
lan_ipv4 = {
address = "192.0.2.10"
port = 80
}
lan_ipv6 = {
address = "2001:db8:1:2:cafe::1337"
port = 80
}
}
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-service.json">
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"lan": {
"address": "192.0.2.10",
"port": 80
},
"lan_ipv4": {
"address": "192.0.2.10",
"port": 80
},
"lan_ipv6": {
"address": "2001:db8:1:2:cafe::1337",
"port": 80
}
}
}
}
```
</CodeBlockConfig>
</CodeTabs>
#### Virtual tags
Connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied:
1. [Transparent proxy](/consul/docs/connect/transparent-proxy) is enabled for the
downstream and upstream services.
1. The upstream service is not configured for individual instances to be
[dialed directly](/consul/docs/connect/config-entries/service-defaults#dialeddirectly).
Virtual addresses are not required to be routable IPs within the
network. They are strictly a control plane construct used to provide a fixed
address for the instances of a given logical service. Egress connections from
the proxy to an upstream service will be destined to the IP address of an
individual service instance, not the virtual address of the logical service.
Use the following address tag to specify the logical address at which the
service can be reached by other services in the mesh.
- `virtual` - The virtual IP address at which a logical service is reachable.
<CodeTabs heading="Example virtual tagged address configuration">
<CodeBlockConfig filename="redis-service.hcl">
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
virtual = {
address = "203.0.113.50"
port = 80
}
}
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-service.json">
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"virtual": {
"address": "203.0.113.50",
"port": 80
}
}
}
}
```
</CodeBlockConfig>
</CodeTabs>
#### WAN tags
One or more of the following address tags can be configured for a node or service
to advertise how it should be accessed over the WAN.
- `wan` - The IPv4 WAN address at which the node or service is accessible when
being dialed from a remote data center.
- `wan_ipv4` - The IPv4 WAN address at which the node or service is accessible
when being dialed from a remote data center.
- `wan_ipv6` - The IPv6 WAN address at which the node or service is accessible
when being dialed from a remote data center.
<CodeTabs heading="Example WAN tagged address configuration">
<CodeBlockConfig filename="redis-service.hcl">
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
wan = {
address = "198.51.100.200"
port = 80
}
wan_ipv4 = {
address = "198.51.100.200"
port = 80
}
wan_ipv6 = {
address = "2001:db8:5:6:1337::1eaf"
port = 80
}
}
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-service.json">
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"wan": {
"address": "198.51.100.200",
"port": 80
},
"wan_ipv4": {
"address": "198.51.100.200",
"port": 80
},
"wan_ipv6": {
"address": "2001:db8:5:6:1337::1eaf",
"port": 80
}
}
}
}
```
</CodeBlockConfig>
</CodeTabs>
## Multiple Service Definitions
Multiple services definitions can be provided at once when registering services
via the agent configuration by using the plural `services` key (registering
multiple services in this manner is not supported using the HTTP API).
<CodeTabs heading="Multiple Service Definitions">
<CodeBlockConfig filename="redis-services.hcl">
```hcl
services {
id = "red0"
name = "redis"
tags = [
"primary"
]
address = ""
port = 6000
checks = [
{
args = ["/bin/check_redis", "-p", "6000"]
interval = "5s"
timeout = "20s"
}
]
}
services {
id = "red1"
name = "redis"
tags = [
"delayed",
"secondary"
]
address = ""
port = 7000
checks = [
{
args = ["/bin/check_redis", "-p", "7000"]
interval = "30s"
timeout = "60s"
}
]
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-services.json">
```json
{
"services": [
{
"id": "red0",
"name": "redis",
"tags": [
"primary"
],
"address": "",
"port": 6000,
"checks": [
{
"args": ["/bin/check_redis", "-p", "6000"],
"interval": "5s",
"timeout": "20s"
}
]
},
{
"id": "red1",
"name": "redis",
"tags": [
"delayed",
"secondary"
],
"address": "",
"port": 7000,
"checks": [
{
"args": ["/bin/check_redis", "-p", "7000"],
"interval": "30s",
"timeout": "60s"
}
]
},
...
]
}
```
</CodeBlockConfig>
</CodeTabs>
## Service and Tag Names with DNS
Consul exposes service definitions and tags over the [DNS](/consul/docs/discovery/dns)
interface. DNS queries have a strict set of allowed characters and a
well-defined format that Consul cannot override. While it is possible to
register services or tags with names that don't match the conventions, those
services and tags will not be discoverable via the DNS interface. It is
recommended to always use DNS-compliant service and tag names.
DNS-compliant service and tag names may contain any alpha-numeric characters, as
well as dashes. Dots are not supported because Consul internally uses them to
delimit service tags.
## Service Definition Parameter Case
For historical reasons Consul's API uses `CamelCased` parameter names in
responses, however its configuration file uses `snake_case` for both HCL and
JSON representations. For this reason the registration _HTTP APIs_ accept both
name styles for service definition parameters although APIs will return the
listings using `CamelCase`.
Note though that **all config file formats require
`snake_case` fields**. We always document service definition examples using
`snake_case` and JSON since this format works in both config files and API
calls.

2
website/content/docs/ecs/configuration-reference.mdx
View File

@ -185,7 +185,7 @@ Defines the Consul checks for the service. Each `check` object may contain the f
| `method` | `string` | optional | Specifies the HTTP method to be used for an HTTP check. When no value is specified, `GET` is used. |
| `name` | `string` | optional | The name of the check. |
| `notes` | `string` | optional | Specifies arbitrary information for humans. This is not used by Consul internally. |
| `os_service` | `string` | optional | Specifies the name of a service on which to perform an [OS service check](/consul/docs/discovery/checks#osservice-check). The check runs according the frequency specified in the `interval` parameter. |
| `os_service` | `string` | optional | Specifies the name of a service on which to perform an [OS service check](/consul/docs/services/usage/checks#osservice-check). The check runs according the frequency specified in the `interval` parameter. |
| `status` | `string` | optional | Specifies the initial status the health check. Must be one of `passing`, `warning`, `critical`, `maintenance`, or `null`. |
| `successBeforePassing` | `integer` | optional | Specifies the number of consecutive successful results required before check status transitions to passing. |
| `tcp` | `string` | optional | Specifies this is a TCP check. Must be an IP/hostname plus port to which a TCP connection is made every `interval`. |

10
website/content/docs/ecs/manual/install.mdx
View File

@ -373,11 +373,11 @@ configuration to a shared volume.
### `CONSUL_ECS_CONFIG_JSON`
Configuration is passed to the `consul-ecs` binary in JSON format using the `CONSUL_ECS_CONFIG_JSON` environment variable.
Consul uses the `CONSUL_ECS_CONFIG_JSON` environment variable to passed configurations to the `consul-ecs` binary in JSON format.
The following is an example of the configuration that might be used for a service named `example-client-app` with one upstream
service name `example-server-app`. The `proxy` and `service` blocks include information used by `consul-ecs-mesh-init` to perform
[service registration](/consul/docs/discovery/services) with Consul during task startup. The same configuration format is used for
The following example configures a service named `example-client-app` with one upstream
service name `example-server-app`. The `proxy` and `service` blocks include information used by `consul-ecs-mesh-init` to register the service with Consul during task start up.
The same configuration format is used for
the `consul-ecs-health-sync` container.
```json
@ -409,7 +409,7 @@ the `consul-ecs-health-sync` container.
| `proxy.upstreams` | list | The upstream services that your application calls over the service mesh, if any. The `destinationName` and `localBindPort` fields are required. |
| `service.name` | string | The name used to register this service into the Consul service catalog. |
| `service.port` | integer | The port your application listens on. Set to `0` if your application does not listen on any port. |
| `service.checks` | list | Consul [checks](/consul/docs/discovery/checks) to include so that Consul can run health checks against your application. |
| `service.checks` | list | Consul [checks](/consul/docs/services/usage/checks) to include so that Consul can run health checks against your application. |
See the [Configuration Reference](/consul/docs/ecs/configuration-reference) for a complete reference of fields.

2
website/content/docs/enterprise/admin-partitions.mdx
View File

@ -61,7 +61,7 @@ The partition in which [`proxy-defaults`](/consul/docs/connect/config-entries/pr
### Cross-partition Networking
You can configure services to be discoverable by downstream services in any partition within the datacenter. Specify the upstream services that you want to be available for discovery by configuring the `exported-services` configuration entry in the partition where the services are registered. Refer to the [`exported-services` documentation](/consul/docs/connect/config-entries/exported-services) for details. Additionally, the requests made by downstream applications must have the correct DNS name for the Virtual IP Service lookup to occur. Service Virtual IP lookups allow for communications across Admin Partitions when using Transparent Proxy. Refer to the [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) for additional information.
You can configure services to be discoverable by downstream services in any partition within the datacenter. Specify the upstream services that you want to be available for discovery by configuring the `exported-services` configuration entry in the partition where the services are registered. Refer to the [`exported-services` documentation](/consul/docs/connect/config-entries/exported-services) for details. Additionally, the requests made by downstream applications must have the correct DNS name for the Virtual IP Service lookup to occur. Service Virtual IP lookups allow for communications across Admin Partitions when using Transparent Proxy. Refer to the [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups-for-consul-enterprise) for additional information.
### Cluster Peering

2
website/content/docs/intro/index.mdx
View File

@ -24,7 +24,7 @@ Consul interacts with the _data plane_ through proxies. The data plane is the pa
The core Consul workflow consists of the following stages:
- **Register**: Teams add services to the Consul catalog, which is a central registry that lets services automatically discover each other without requiring a human operator to modify application code, deploy additional load balancers, or hardcode IP addresses. It is the runtime source of truth for all services and their addresses. Teams can manually [define and register services](/consul/docs/discovery/services) using the CLI or the API, or you can automate the process in Kubernetes with [service sync](/consul/docs/k8s/service-sync). Services can also include health checks so that Consul can monitor for unhealthy services.
- **Register**: Teams add services to the Consul catalog, which is a central registry that lets services automatically discover each other without requiring a human operator to modify application code, deploy additional load balancers, or hardcode IP addresses. It is the runtime source of truth for all services and their addresses. Teams can manually [define](/consul/docs/services/usage/define-services) and [register](/consul/docs/services/usage/register-services-checks) using the CLI or the API, or you can automate the process in Kubernetes with [service sync](/consul/docs/k8s/service-sync). Services can also include health checks so that Consul can monitor for unhealthy services.
- **Query**: Consul’s identity-based DNS lets you find healthy services in the Consul catalog. Services registered with Consul provide health information, access points, and other data that help you control the flow of data through your network. Your services only access other services through their local proxy according to the identity-based policies you define.
- **Secure**: After services locate upstreams, Consul ensures that service-to-service communication is authenticated, authorized, and encrypted. Consul service mesh secures microservice architectures with mTLS and can allow or restrict access based on service identities, regardless of differences in compute environments and runtimes.

2
website/content/docs/k8s/connect/cluster-peering/usage/establish-peering.mdx
View File

@ -319,7 +319,7 @@ Before you can call services from peered clusters, you must set service intentio
</CodeBlockConfig>
1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/consul/docs/discovery/dns#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) details how you would similarly format a DNS name including partitions and namespaces.
1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/services/discovery/dns-static-lookups#service-virtual-ip-lookups-for-consul-enterprise) details how you would similarly format a DNS name including partitions and namespaces.
<CodeBlockConfig filename="frontend.yaml" highlight="36,51">

2
website/content/docs/k8s/dns.mdx
View File

@ -8,7 +8,7 @@ description: >-
# Resolve Consul DNS Requests in Kubernetes
One of the primary query interfaces to Consul is the
[DNS interface](/consul/docs/discovery/dns). You can configure Consul DNS in
[DNS interface](/consul/docs/services/discovery/dns-overview). You can configure Consul DNS in
Kubernetes using a
[stub-domain configuration](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#configure-stub-domain-and-upstream-dns-servers)
if using KubeDNS or a [proxy configuration](https://coredns.io/plugins/proxy/) if using CoreDNS.

2
website/content/docs/k8s/service-sync.mdx
View File

@ -20,7 +20,7 @@ automatically installed and configured using the
Consul catalog enable Kubernetes services to be accessed by any node that
is part of the Consul cluster, including other distinct Kubernetes clusters.
For non-Kubernetes nodes, they can access services using the standard
[Consul DNS](/consul/docs/discovery/dns) or HTTP API.
[Consul DNS](/consul/docs/services/discovery/dns-overview) or HTTP API.
**Why sync Consul services to Kubernetes?** Syncing Consul services to
Kubernetes services enables non-Kubernetes services to be accessed using kube-dns and Kubernetes-specific

2
website/content/docs/nia/configuration.mdx
View File

@ -197,7 +197,7 @@ Service registration requires that the [Consul token](/consul/docs/nia/configura
| `default_check.enabled` | Optional | boolean | Enables CTS to create the default health check. | `true` |
| `default_check.address` | Optional | string | The address to use for the default HTTP health check. Needs to include the scheme (`http`/`https`) and the port, if applicable. | `http://localhost:<port>` or `https://localhost:<port>`. Determined from the [port configuration](/consul/docs/nia/configuration#port) and whether [TLS is enabled](/consul/docs/nia/configuration#enabled-2) on the CTS API. |
The default health check is an [HTTP check](/consul/docs/discovery/checks#http-interval) that calls the [Health API](/consul/docs/nia/api/health). The following table describes the values CTS sets for this default check, corresponding to the [Consul register check API](/consul/api-docs/agent/check#register-check). If an option is not listed in this table, then CTS is using the default value.
The default health check is an [HTTP check](/consul/docs/services/usage/checks#http-checks) that calls the [Health API](/consul/docs/nia/api/health). The following table describes the values CTS sets for this default check, corresponding to the [Consul register check API](/consul/api-docs/agent/check#register-check). If an option is not listed in this table, then CTS is using the default value.
| Parameter | Value |
| --------- | ----- |

2
website/content/docs/release-notes/consul/v1_13_x.mdx
View File

@ -15,7 +15,7 @@ description: >-
- **Enables TLS on the Envoy Prometheus endpoint**: The Envoy prometheus endpoint can be enabled when `envoy_prometheus_bind_addr` is set and then secured over TLS using new CLI flags for the `consul connect envoy` command. These commands are: `-prometheus-ca-file`, `-prometheus-ca-path`, `-prometheus-cert-file` and `-prometheus-key-file`. The CA, cert, and key can be provided to Envoy by a Kubernetes mounted volume so that Envoy can watch the files and dynamically reload the certs when the volume is updated.
- **UDP Health Checks**: Adds the ability to register service discovery health checks that periodically send UDP datagrams to the specified IP/hostname and port. Refer to [UDP checks](/consul/docs/discovery/checks#udp-interval).
- **UDP Health Checks**: Adds the ability to register service discovery health checks that periodically send UDP datagrams to the specified IP/hostname and port. Refer to [UDP checks](/consul/docs//services/usage/checks#udp-checks).
## What's Changed

13
website/content/docs/security/acl/acl-rules.mdx
View File

@ -586,8 +586,7 @@ These actions may required an ACL token to complete. Use the following methods t
This allows a single token to be used during all check registration operations.
* Provide an ACL token with `service` and `check` definitions at registration time.
This allows for greater flexibility and enables the use of multiple tokens on the same agent.
Refer to the [services](/consul/docs/discovery/services) and [checks](/consul/docs/discovery/checks) documentation for examples.
Tokens may also be passed to the [HTTP API](/consul/api-docs) for operations that require them.
Refer to the [services](/consul/docs/services/usage/define-services) and [checks](/consul/docs/services/usage/checks) documentation for examples. You can also pass tokens to the [HTTP API](/consul/api-docs) for operations that require them.
### Reading Imported Nodes
@ -815,12 +814,12 @@ to use for registration events:
2. Providing an ACL token with service and check definitions at registration
time. This allows for greater flexibility and enables the use of multiple
tokens on the same agent. Examples of what this looks like are available for
both [services](/consul/docs/discovery/services) and
[checks](/consul/docs/discovery/checks). Tokens may also be passed to the [HTTP
API](/consul/api-docs) for operations that require them. **Note:** all tokens
both [services](/consul/docs/services/usage/define-services) and
[checks](/consul/docs/services/usage/checks). Tokens may also be passed to the [HTTP
API](/consul/api-docs) for operations that require them. Note that all tokens
passed to an agent are persisted on local disk to allow recovery from
restarts. See [`-data-dir` flag
documentation](/consul/docs/agent/config/cli-flags#_data_dir) for notes on securing
restarts. Refer to [`-data-dir` flag
documentation](/consul/docs/agent/config/cli-flags#_data_dir) for information about securing
access.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with

2
website/content/docs/security/acl/acl-tokens.mdx
View File

@ -66,7 +66,7 @@ service = {
</CodeTabs>
Refer to the [service definitions documentation](/consul/docs/discovery/services#service-definition) for additional information.
Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference) for additional information.
### Agent Requests

55
website/content/docs/services/configuration/checks-configuration-reference.mdx Normal file
View File

@ -0,0 +1,55 @@
---
layout: docs
page_title: Health Check Configuration Reference
description: ->
Use the health checks to direct safety functions, such as removing failing nodes and replacing secondary services. Learn how to configure health checks.
---
# Health Check Configuration Reference
This topic provides configuration reference information for health checks. For information about the different kinds of health checks and guidance on defining them, refer to [Define Health Checks].
## Introduction
Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. You can configure health checks to monitor the health of the entire node. Refer to [Define Health Checks](/consul/docs/services/usage/checks) for information about how to define the differnet types of health checks available in Consul.
## Check block
Specify health check options in the `check` block. To register two or more heath checks in the same configuration, use the [`checks` block](#checks-block). The following table describes the configuration options contained in the `check` block.
| Parameter | Description | Check types |
| --- | --- | --- |
| `name` | Required string value that specifies the name of the check. Default is `service:<service-id>`. If multiple service checks are registered, the autogenerated default is appended with colon and incrementing number starting with `1`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `id` | A unique string value that specifies an ID for the check. Default to the `name` value. If `name` values conflict, specify a unique ID to avoid overwriting existing checks with same ID on the same node. Consul auto-generates an ID if the check is defined in a service definition file. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `notes` | String value that provides a human-readabiole description of the check. The contents are not visible to Consul. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `interval` | Required string value that specifies how frequently to run the check. The `interval` parameter is required for supported check types. The value is parsed by the golang [time package formatting specification](https://golang.org/pkg/time/#ParseDuration). | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>Docker </li> <li>gRPC </li> <li>H2ping</li> |
| `timeout` | String value that specifies how long unsuccessful requests take to end with a timeout. The `timeout` is optional for the supported check types and has the following defaults: <li> Script: `30s` </li> <li> HTTP: `10s` </li><li> TCP: `10s` </li><li> UDP: `10s` </li><li> gRPC: `10s` </li><li> H2ping: `10s` </li> | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>gRPC </li> <li>H2ping </li> |
| `status` | Optional string value that specifies the initial status of the health check. You can specify the following values: <li>`critical` (default)</li><li>`warning`</li><li>`passing`</li> | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `deregister_critical_service_after` | String value that specifies how long a service and its associated checks are allowed to be in a `critical` state. Consul deregisters services if they are `critical` for the specified amount of time. The value is parsed by the golang [time package formatting specification](https://golang.org/pkg/time/#ParseDuration) | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `success_before_passing` | Integer value that specifies how many consecutive times the check must pass before Consul marks the service or node as `passing`. Default is `0`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `failures_before_warning` | Integer value that specifies how many consecutive times the check must fail before Consul marks the service or node as `warning`. The value cannot be more than `failures_before_critical`. Defaults to the value specified for `failures_before_critical`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `failures_before_critical` | Integer value that specifies how many consecutive times the check must fail before Consul marks the service or node as `critical`. Default is `0`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
| `args` | Specifies a list of arguments strings to pass to the command line. The list of values includes the path to a script file or external application to invoke and any additional parameters for running the script or application. | <li> Script </li><li> Docker </li> |
| `docker_container_id` | Specifies the Docker container ID in which to run an external health check application. Specify the external application with the `args` parameter. | <li> Docker </li> |
| `shell` | String value that specifies the type of command line shell to use for running the health check application. Specify the external application with the `args` parameter. | <li> Docker </li> |
| `grpc` | String value that specifies the gRPC endpoint, including port number, to send requests to. Append the endpoint with `:/` and a service identifier to check a specific service. The endpoint must support the [gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). | <li>gRPC </li>|
| `grpc_use_tls` | Boolean value that enables TLS for gRPC checks when set to `true`. | <li>gRPC </li> |
| `h2ping` | String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to. | <li>H2ping</li> |
| `h2ping_use_tls` | Boolean value that enables TLS for H2ping checks when set to `true`. | <li>H2ping</li> |
| `http` | String value that specifies an HTTP endpoint to send requests to. | <li>HTTP</li> |
| `tls_server_name` | String value that specifies the name of the TLS server that issues certificates. Defaults to the SNI determined by the address specified in the `http` field. Set the `tls_skip_verify` to `false` to disable this field. | <li>HTTP</li> |
| `tls_skip_verify` | Boolean value that disbles TLS for HTTP checks when set to `true`. Default is `false`. | <li>HTTP</li> |
| `method` | String value that specifies the request method to send during HTTP checks. Default is `GET`. | <li>HTTP</li> |
| `header` | Object that specifies header fields to send in HTTP check requests. Each header specified in `header` object contains a list of string values. | <li>HTTP</li> |
| `body` | String value that contains JSON attributes to send in HTTP check requests. You must escap the quotation marks around the keys and values for each attribute. | <li>HTTP</li> |
| `disable_redirects` | Boolean value that prevents HTTP checks from following redirects if set to `true`. Default is `false`. | <li>HTTP</li> |
| `os_service` | String value that specifies the name of the name of a service to check during an OSService check. | <li>OSService</li> |
| `service_id` | String value that specifies the ID of a service instance to associate with an OSService check. That service instance must be on the same node as the check. If not specified, the check verifies the health of the node. | <li>OSService</li> |
| `tcp` | String value that specifies an IP address or host and port number for the check establish a TCP connection with. | <li>TCP</li> |
| `udp` | String value that specifies an IP address or host and port number for the check to send UDP datagrams to. | <li>UDP</li> |
| `ttl` | String value that specifies how long to wait for an update from an external process during a TTL check. | <li>TTL</li> |
| `alias_service` | String value that specifies a service or node that the service associated with the health check aliases. | <li>Alias</li> |
## Checks block
You can define multiple health checks in a single `checks` block. The `checks` block is an array of objects that contain the configuration options described in the [`check` block configuration reference](#check-block).

28
website/content/docs/services/configuration/services-configuration-overview.mdx Normal file
View File

@ -0,0 +1,28 @@
---
layout: docs
page_title: Services Configuration Overview
description: ->
This topic provides introduces the configuration items that enable you to register services with Consul so that they can connect to other services and nodes registered with Consul.
---
# Services Configuration Overview
This topic provides introduces the configuration items that enable you to register services with Consul so that they can connect to other services and nodes registered with Consul.
## Service definitions
A service definition contains a set of parameters that specify various aspects of the service, including how it is discovered by other services in the network. The service definition may also contain health check configurations. Refer to [Health Check Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference) for configuration details about health checks.
Configure individual services and health checks by specifying parameters in the `service` block of a service definition file. Refer to [Define Services](/consul/docs/services/usage/define-services) for information about defining services.
To register a service, provide the service definition to the Consul agent. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for information about registering services.
Consul supports service definitions written in JSON and HCL.
## Service defaults
Use the `service-defaults` configuration entry to define the default parameters for service definitions. This enables you to configure common settings, such as namespace or partition for Consul Enterprise deployments, in a single definition.
You can use `service-defaults` configuration entries on virtual machines and in Kubernetes environments.
## ACLs
Services registered in Consul clusters where both Consul Namespaces and the ACL system are enabled can be registered to specific namespaces that are associated with ACL tokens scoped to the namespace. Services registered with a service definition will not inherit the namespace associated with the ACL token specified in the token field. The namespace and the token parameters must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to.

654
website/content/docs/services/configuration/services-configuration-reference.mdx Normal file
View File

@ -0,0 +1,654 @@
---
page_title: Service Configuration Reference
description: Use the service definition to configure and register services to the Consul catalog, including services used as proxies in a Consul service mesh
---
# Services Configuration Reference
This topic describes the options you can use to define services for registering them with Consul. Refer to the following topics for usage information:
- [Define Services](/consul/docs/services/usage/define-services)
- [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks)
## Configuration model
The following outline shows how to format the configurations in the root `service` block. Click on a property name to view details about the configuration.
- [`name`](#name): string | required
- [`id`](#id): string | optional
- [`address`](#address): string | optional
- [`port`](#port): integer | optional
- [`tags`](#tags): list of strings | optional
- [`meta`](#meta): object | optional
- [_`custom_meta_key`_](#meta): string | optional
- [`tagged_addresses`](#tagged_addresses): object | optional
- [`lan`](#tagged_addresses-lan): object | optional
- [`address`](#tagged_addresses-lan): string | optional
- [`port`](#tagged_addresses-lan): integer | optional
- [`wan`](#tagged_addresses-wan): object | optional
- [`address`](#tagged_addresses-wan): string | optional
- [`port`](#tagged_addresses-wan): integer | optional
- [`socket_path`](#socket_path): string | optional
- [`enable_tag_override`](#enable_tag_override): boolean | optional
- [`checks`](#checks) : list of objects | optional
- [`kind`](#kind): string | optional
- [`proxy`](#proxy): object | optional
- [`connect`](#connect): object | optional
- [`native`](#connect): boolean | optional
- [`sidecar_service`](#connect): object | optional
- [`weights`](#weights): object | optional
- [`passing`](#weights): integer | optional
- [`warning`](#weights): integer | optional
- [`token`](#token): string | required if ACLs are enabled
- [`namespace`](#namespace): string | optional | <EnterpriseAlert inline />
## Specification
This topic provides details about the configuration parameters.
### name
Required value that specifies a name for the service. We recommend using valid DNS labels for service definition names for compatibility with external DNSs. The value for this parameter is used as the ID if the `id` parameter is not specified.
- Type: string
- Default: none
### id
Specifies an ID for the service. Services on the same node must have unique IDs. We recommend specifying unique values if the default name conflicts with other services.
- Type: string
- Default: Value of the `name` field.
### address
String value that specifies a service-specific IP address or hostname.
If no value is specified, the IP address of the agent node is used by default.
There is no service-side validation of this parameter.
- Type: string
- Default: IP address of the agent node
### port
Specifies a port number for the service. To improve service discoverability, we recommend specifying the port number, as well as an address in the [`tagged_addresses`](#tagged_addresses) parameter.
- Type: integer
- Default: Port number of the agent
### tags
Specifies a list of string values that add service-level labels. Tag values are opaque to Consul. We recommend using valid DNS labels for service definition IDs for compatibility with external DNSs. In the following example, the service is tagged as `v2` and `primary`:
```hcl
tags = ["v2", "primary"]
```
Consul uses tags as an anti-entropy mechanism to maintain the state of the cluster. You can disable the anti-entropy feature for a service using the [`enable_tag_override`](#enable_tag_override) setting, which enables external agents to modify tags on services in the catalog. Refer to [Modify anti-entropy synchronization](/consul/docs/services/usage/define-services#modify-anti-entropy-synchronization) for additional usage information.
### meta
The `meta` field contains custom key-value pairs that associate semantic metadata with the service. You can specify up to 64 pairs that meet the following requirements:
- Keys and values must be strings.
- Keys can only contain ASCII characters (`A` -` Z`, `a`- `z`, `0` - `9`, `_`, and `-`).
- Keys can not have special characters.
- Keys are limited to 128 characters.
- Values are limited to 512 characters.
In the following example, the `env` key is set to `prod`:
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
meta = {
env = "prod"
}
```
```json
"meta" : {
"env" : "prod"
}
```
</CodeTabs>
### tagged_addresses
The `tagged_address` field is an object that configures additional addresses for a node or service. Remote agents and services can communicate with the service using a tagged address as an alternative to the address specified in the [`address`](#address) field. You can configure multiple addresses for a node or service. The following tags are supported:
- [`lan`](#tagged_addresses-lan): IPv4 LAN address where the node or service is accessible.
- [`lan_ipv4`](#tagged_addresses-lan): IPv4 LAN address where the node or service is accessible.
- [`lan_ipv6`](#tagged_addresses-lan): IPv6 LAN address where the node or service is accessible.
- [`virtual`](#tagged_addresses-virtual): A fixed address for the instances of a given logical service.
- [`wan`](#tagged_addresses-wan): IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
- [`wan_ipv4`](#tagged_addresses-wan): IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
- [`wan_ipv6`](#tagged_addresses-lan): IPv6 WAN address at which the node or service is accessible when being dialed from a remote data center.
### tagged_addresses.lan
Object that specifies either an IPv4 or IPv6 LAN address and port number where the service or node is accessible. You can specify one or more of the following fields:
- `lan`
- `lan_ipv4`
- `lan_ipv6`
The field contains the following parameters:
- `address`
- `port`
In the following example, the `redis` service has an IPv4 LAN address of `192.0.2.10:80` and IPv6 LAN address of `[2001:db8:1:2:cafe::1337]:80`:
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
lan = {
address = "192.0.2.10"
port = 80
}
lan_ipv4 = {
address = "192.0.2.10"
port = 80
}
lan_ipv6 = {
address = "2001:db8:1:2:cafe::1337"
port = 80
}
}
}
```
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"lan": {
"address": "192.0.2.10",
"port": 80
},
"lan_ipv4": {
"address": "192.0.2.10",
"port": 80
},
"lan_ipv6": {
"address": "2001:db8:1:2:cafe::1337",
"port": 80
}
}
}
}
```
</CodeTabs>
### tagged_addresses.virtual
Object that specifies a fixed IP address and port number that downstream services in a service mesh can use to connect to the service. The `virtual` field contains the following parameters:
- `address`
- `port`
Virtual addresses are not required to be routable IPs within the network. They are strictly a control plane construct used to provide a fixed address for the instances of a logical service. Egress connections from the proxy to an upstream service go to the IP address of an individual service instance and not the virtual address of the logical service.
If the following conditions are met, connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied:
1. [Transparent proxy](/consul/docs/connect/transparent-proxy) is enabled for the downstream and upstream services.
1. The upstream service is not configured for individual instances to be [dialed directly](/consul/docs/connect/config-entries/service-defaults#dialeddirectly).
In the following example, the downstream services in the mesh can connect to the `redis` service at `203.0.113.50` on port `80`:
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
virtual = {
address = "203.0.113.50"
port = 80
}
}
}
```
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"virtual": {
"address": "203.0.113.50",
"port": 80
}
}
}
}
```
</CodeTabs>
### tagged_addresses.wan
Object that specifies either an IPv4 or IPv6 WAN address and port number where the service or node is accessible from a remote datacenter. You can specify one or more of the following fields:
- `wan`
- `wan_ipv4`
- `wan_ipv6`
The field contains the following parameters:
- `address`
- `port`
In the following example, services or nodes in remote datacenters can reach the `redis` service at `198.51.100.200:80` and `[2001:db8:5:6:1337::1eaf]:80`:
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
service {
name = "redis"
address = "192.0.2.10"
port = 80
tagged_addresses {
wan = {
address = "198.51.100.200"
port = 80
}
wan_ipv4 = {
address = "198.51.100.200"
port = 80
}
wan_ipv6 = {
address = "2001:db8:5:6:1337::1eaf"
port = 80
}
}
}
```
```json
{
"service": {
"name": "redis",
"address": "192.0.2.10",
"port": 80,
"tagged_addresses": {
"wan": {
"address": "198.51.100.200",
"port": 80
},
"wan_ipv4": {
"address": "198.51.100.200",
"port": 80
},
"wan_ipv6": {
"address": "2001:db8:5:6:1337::1eaf",
"port": 80
}
}
}
}
```
</CodeTabs>
### socket_path
String value that specifies the path to the service socket. Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket.
- Type: string
- Default: none
### enable_tag_override
Boolean value that determines if the anti-entropy feature for the service is enabled.
Set to `true` to allow external Consul agents modify tags on the services in the Consul catalog. The local Consul agent ignores updated tags during subsequent sync operations.
This parameter only applies to the locally-registered service. If multiple nodes register a service with the same `name`, the `enable_tag_override` configuration, and all other service configuration items, operate independently.
Refer to [Modify anti-entropy synchronization](/consul/docs/services/usage/define-services#modify-anti-entropy-synchronization) for additional usage information.
- Type: boolean
- Default: `false`
### checks
The `checks` block contains an array of objects that define health checks for the service. Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. Refer to [Health Check Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference) for information about configuring health checks.
### kind
String value that identifies the service as a proxy and determines its role in the service mesh. Do not configure the `kind` parameter for non-proxy service instances. Refer to [Consul Service Mesh](/consul/docs/connect) for additional information.
You can specify the following values:
- `connect-proxy`: Defines the configuration for a service mesh proxy. Refer to [Register a Service Mesh Proxy Outside of a Service Registration](/consul/docs/connect/registration/service-registration) for details about registering a service as a service mesh proxy.
- `ingress-gateway`: Defines the configuration for an [ingress gateway](/consul/docs/connect/config-entries/ingress-gateway)
- `mesh-gateway`: Defines the configuration for a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway)
- `terminating-gateway`: Defines the configuration for a [terminating gateway](/consul/docs/connect/gateways/terminating-gateway)
For non-service registration roles, the `kind` field has a different context when used to define configuration entries, such as `service-defaults`. Refer to the documentation for the configuration entry you want to implement for additional information.
### proxy
Object that specifies proxy configurations when the service is configured to operate as a proxy in a service mesh. Do not configure the `proxy` parameter for non-proxy service instances. Refer to [Register a Service Mesh Proxy Outside of a Service Registration](/consul/docs/connect/registration/service-registration) for details about registering your service as a service mesh proxy. Refer to [`kind`](#kind) for information about the types of proxies you can define. Services that you assign proxy roles to are registered as services in the catalog.
### connect
Object that configures a Consul service mesh connection. You should only configure the `connect` block of parameters if you are using Consul service mesh. Refer to [Consul Service Mesh](/consul/docs/connect) for additional information.
The following table describes the parameters that you can place in the `connect` block:
| Parameter | Description | Default |
| --- | --- | --- |
| `native` | Boolean value that advertises the service as a native service mesh proxy. Use this parameter to integrate your application with the `connect` API. Refer to [Service Mesh Native App Integration Overview](/consul/docs/connect/native) for additional information. If set to `true`, do not configure a `sidecar_service`. | `false` |
| `sidecar_service` | Object that defines a sidecar proxy for the service. Do not configure if `native` is set to `true`. Refer to [Register a Service Mesh Proxy in a Service Registration](/consul/docs/connect/registration/sidecar-service) for usage and configuration details. | Refer to [Register a Service Mesh Proxy in a Service Registration](/consul/docs/connect/registration/sidecar-service) for default configurations. |
### weights
Object that configures how the service responds to DNS SRV requests based on the service's health status. Configuring allows service instances with more capacity to respond to DNS SRV requests. It also reduces the load on services with checks in `warning` status by giving passing instances a higher weight.
You can specify one or more of the following states and configure an integer value indicating its weight:
- `passing`
- `warning`
- `critical`
Larger integer values increase the weight state. Services have the following default weights:
- `"passing" : 1`
- `"warning" : 1`
Services in a `critical` state are excluded from DNS responses by default. Services with `warning` checks are included in responses by default. Refer to [Perform Static DNS Queries](/consul/docs/services/discovery/dns-static-lookups) for additional information.
In the following example, service instances in a `passing` state respond to DNS SRV requests, while instances in a `critical` instance can still respond at a lower frequency:
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
service {
## ...
weights = {
passing = 3
warning = 2
critical = 1
}
## ...
}
```
```json
"service": {
## ...
"weights": {
"passing": 3,
"warning": 2,
"critical": 1
},
## ...
}
```
</CodeTabs>
### token
String value that specifies the ACL token to present when registering the service if ACLs are enabled. The token is required for the service to interact with the service catalog.
If [ACLs](/consul/docs/security/acl) and [namespaces](/consul/docs/enterprise/namespaces) are enabled, you can register services scoped to the specific [`namespace`](#namespace) associated with the ACL token in a Consul cluster.
Services registered with a service definition do not inherit the namespace associated with the ACL token specified in the token field. The `namespace` and `token` parameters must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to.
- Type: string
- Default: none
### namespace
String value that specifies the namespace in which to register the service. Refer [Namespaces](/consul/docs/enterprise/namespaces) for additional information.
- Type: string
- Default: none
## Multiple service definitions
You can define multiple services in a single definition file in the `servcies` block. This enables you register multiple services in a single command. Note that the HTTP API does not support the `services` block.
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
services {
id = "red0"
name = "redis"
tags = [
"primary"
]
address = ""
port = 6000
checks = [
{
args = ["/bin/check_redis", "-p", "6000"]
interval = "5s"
timeout = "20s"
}
]
}
services {
id = "red1"
name = "redis"
tags = [
"delayed",
"secondary"
]
address = ""
port = 7000
checks = [
{
args = ["/bin/check_redis", "-p", "7000"]
interval = "30s"
timeout = "60s"
}
]
}
```
```json
{
"services": [
{
"id": "red0",
"name": "redis",
"tags": [
"primary"
],
"address": "",
"port": 6000,
"checks": [
{
"args": ["/bin/check_redis", "-p", "6000"],
"interval": "5s",
"timeout": "20s"
}
]
},
{
"id": "red1",
"name": "redis",
"tags": [
"delayed",
"secondary"
],
"address": "",
"port": 7000,
"checks": [
{
"args": ["/bin/check_redis", "-p", "7000"],
"interval": "30s",
"timeout": "60s"
}
]
}
]
}
```
</CodeTabs>
## Example definition
The following example includes all possible parameters, but only the top-level `service` parameter and its `name` parameter are required by default.
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
service {
name = "redis"
id = "redis"
port = 80
tags = ["primary"]
meta = {
custom_meta_key = "custom_meta_value"
}
tagged_addresses = {
lan = {
address = "192.168.0.55"
port = 8000
}
wan = {
address = "198.18.0.23"
port = 80
}
}
port = 8000
socket_path = "/tmp/redis.sock"
enable_tag_override = false
checks = [
{
args = ["/usr/local/bin/check_redis.py"]
interval = "10s"
}
]
kind = "connect-proxy"
proxy_destination = "redis"
proxy = {
destination_service_name = "redis"
destination_service_id = "redis1"
local_service_address = "127.0.0.1"
local_service_port = 9090
local_service_socket_path = "/tmp/redis.sock"
mode = "transparent"
transparent_proxy {
outbound_listener_port = 22500
}
mesh_gateway = {
mode = "local"
}
expose = {
checks = true
paths = [
{
path = "/healthz"
local_path_port = 8080
listener_port = 21500
protocol = "http2"
}
]
}
}
connect = {
native = false
}
weights = {
passing = 5
warning = 1
}
token = "233b604b-b92e-48c8-a253-5f11514e4b50"
namespace = "foo"
}
```
```json
{
"service": {
"id": "redis",
"name": "redis",
"tags": ["primary"],
"address": "",
"meta": {
"meta": "for my service"
},
"tagged_addresses": {
"lan": {
"address": "192.168.0.55",
"port": 8000,
},
"wan": {
"address": "198.18.0.23",
"port": 80
}
},
"port": 8000,
"socket_path": "/tmp/redis.sock",
"enable_tag_override": false,
"checks": [
{
"args": ["/usr/local/bin/check_redis.py"],
"interval": "10s"
}
],
"kind": "connect-proxy",
"proxy_destination": "redis", // Deprecated
"proxy": {
"destination_service_name": "redis",
"destination_service_id": "redis1",
"local_service_address": "127.0.0.1",
"local_service_port": 9090,
"local_service_socket_path": "/tmp/redis.sock",
"mode": "transparent",
"transparent_proxy": {
"outbound_listener_port": 22500
},
"config": {},
"upstreams": [],
"mesh_gateway": {
"mode": "local"
},
"expose": {
"checks": true,
"paths": [
{
"path": "/healthz",
"local_path_port": 8080,
"listener_port": 21500,
"protocol": "http2"
}
]
}
},
"connect": {
"native": false,
"sidecar_service": {}
"proxy": { // Deprecated
"command": [],
"config": {}
}
},
"weights": {
"passing": 5,
"warning": 1
},
"token": "233b604b-b92e-48c8-a253-5f11514e4b50",
"namespace": "foo"
}
}
```
</CodeTabs>

76
website/content/docs/services/discovery/dns-configuration.mdx Normal file
View File

@ -0,0 +1,76 @@
---
layout: docs
page_title: Configure Consul DNS Behavior
description: ->
Learn how to modify the default DNS behavior so that services and nodes can easily discover other services and nodes in your network.
---
# Configure Consul DNS Behavior
This topic describes the default behavior of the Consul DNS functionality and how to customize how Consul performs queries.
## Introduction
The Consul DNS is the primary interface for querying records when Consul service mesh is disabled and your network runs in a non-Kubernetes environment. The DNS enables you to look up services and nodes registered with Consul using terminal commands instead of making HTTP API requests to Consul. Refer to the [Discover Consul Nodes and Services Overview](/consul/docs/services/discovery/dns-overview) for additional information.
## Configure DNS behaviors
By default, the Consul DNS listens for queries at `127.0.0.1:8600` and uses the `consul` domain. Specify the following parameters in the agent configuration to determine DNS behavior when querying services:
- [`client_addr`](/consul/docs/agent/config/config-files#client_addr)
- [`ports.dns`](/consul/docs/agent/config/config-files#dns_port)
- [`recursors`](/consul/docs/agent/config/config-files#recursors)
- [`domain`](/consul/docs/agent/config/config-files#domain)
- [`alt_domain`](/consul/docs/agent/config/config-files#alt_domain)
- [`dns_config`](/consul/docs/agent/config/config-files#dns_config)
### Configure WAN address translation
By default, Consul DNS queries return a node's local address, even when being queried from a remote datacenter. You can configure the DNS to reach a node from outside its datacenter by specifying the address in the following configuration fields in the Consul agent:
- [advertise-wan](/consul/docs/agent/config/cli-flags#_advertise-wan)
- [translate_wan_addrs](/consul//docs/agent/config/config-files#translate_wan_addrs)
### Use a custom DNS resolver library
You can specify a list of addresses in the agent's [`recursors`](/consul/docs/agent/config/config-files#recursors) field to provide upstream DNS servers that recursively resolve queries that are outside the service domain for Consul.
Nodes that query records outside the `consul.` domain resolve to an upstream DNS. You can specify IP addresses or use `go-sockaddr` templates. Consul resolves IP addresses in the specified order and ignores duplicates.
### Enable non-Consul queries
You enable non-Consul queries to be resolved by setting Consul as the DNS server for a node and providing a [`recursors`](/consul/docs/agent/config/config-files#recursors) configuration.
### Forward queries to an agent
You can forward all queries sent to the `consul.` domain from the existing DNS server to a Consul agent. Refer to [Forward DNS for Consul Service Discovery](/consul/tutorials/networking/dns-forwarding) for instructions.
### Query an alternate domain
By default, Consul responds to DNS queries in the `consul` domain, but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/consul/docs/agent/config/config-files#domain) parameter.
You can also specify an additional domain in the [`alt_domain`](/consul/docs/agent/config/config-files#alt_domain) agent configuration option, which configures Consul to respond to queries in a secondary domain. Configuring an alternate domain may be useful during a DNS migration or to distinguish between internal and external queries, for example.
Consul's DNS response uses the same domain as the query.
In the following example, the `alt_domain` parameter in the agent configuration is set to `test-domain`, which enables operators to query the domain:
```shell-session
$ dig @127.0.0.1 -p 8600 consul.service.test-domain SRV
;; QUESTION SECTION:
;consul.service.test-domain. IN SRV
;; ANSWER SECTION:
consul.service.test-domain. 0 IN SRV 1 1 8300 machine.node.dc1.test-domain.
;; ADDITIONAL SECTION:
machine.node.dc1.test-domain. 0 IN A 127.0.0.1
machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment="
```
#### PTR queries
Responses to pointer record (PTR) queries, such as `<ip>.in-addr.arpa.`, always use the [primary domain](/consul/docs/agent/config/config-files#domain) and not the alternative domain.
### Caching
By default, DNS results served by Consul are not cached. Refer to the [DNS Caching tutorial](/consul/tutorials/networking/dns-caching) for instructions on how to enable caching.

100
website/content/docs/services/discovery/dns-dynamic-lookups.mdx Normal file
View File

@ -0,0 +1,100 @@
---
layout: docs
page_title: Enable Dynamic DNS Queries
description: ->
Learn how to dynamically query the Consul DNS using prepared queries, which enable robust service and node lookups.
---
# Enable Dynamic DNS Queries
This topic describes how to dynamically query the Consul catalog using prepared queries. Prepared queries are configurations that enable you to register a complex service query and execute it on demand. For information about how to perform standard node and service lookups, refer to [Perform Static DNS Queries](/consul/docs/services/discovery/dns-static-lookups).
## Introduction
Prepared queries provide a rich set of lookup features, such as filtering by multiple tags and automatically failing over to look for services in remote datacenters if no healthy nodes are available in the local datacenter. You can also create prepared query templates that match names using a prefix match, allowing a single template to apply to potentially many services. Refer to [Query Consul Nodes and Services Overview](/consul/docs/services/discovery/dns-overview) for additional information about DNS query behaviors.
## Requirements
Consul 0.6.4 or later is required to create prepared query templates.
### ACLs
If ACLs are enabled, the querying service must present a token linked to permissions that enable read access for query, service, and node resources. Refer to the following documentation for information about creating policies to enable read access to the necessary resources:
- [Prepared query rules](/consul/docs/security/acl/acl-rules#prepared-query-rules)
- [Service rules](/consul/docs/security/acl/acl-rules#service-rules)
- [Node rules](/consul/docs/security/acl/acl-rules#node-rules)
## Create prepared queries
Refer to the [prepared query reference](/consul/api-docs/query#create-prepared-query) for usage information.
1. Specify the prepared query options in JSON format. The following prepared query targets all instances of the `redis` service in `dc1` and `dc2`:
```json
{
"Name": "my-query",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Token": "",
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"Near": "node1",
"OnlyPassing": false,
"Tags": ["primary", "!experimental"],
"NodeMeta": {
"instance_type": "m3.large"
},
"ServiceMeta": {
"environment": "production"
}
},
"DNS": {
"TTL": "10s"
}
}
```
Refer to the [prepared query configuration reference](/consul/api-docs/query#create-prepared-query) for information about all available options.
1. Send the query in a POST request to the [`/query` API endpoint](/consul/api-docs/query). If the request is successful, Consul prints an ID for the prepared query.
In the following example, the prepared query configuration is stored in the `payload.json` file:
```shell-session
$ curl --request POST --data @payload.json http://127.0.0.1:8500/v1/query
{"ID":"014af5ff-29e6-e972-dcf8-6ee602137127"}%
```
1. To run the query, send a GET request to the endpoint and specify the ID returned from the POST call.
```shell-session
$ curl http://127.0.0.1:8500/v1/query/14af5ff-29e6-e972-dcf8-6ee602137127/execute\?near\=_agent
```
## Execute prepared queries
You can execute a prepared query using the standard lookup format or the strict RFC 2782 SRV lookup.
### Standard lookup
Use the following format to execute a prepared query using the standard lookup format:
```
<query name or id>.query[.<datacenter>].<domain>
```
Refer [Standard lookups](/consul/docs/services/discovery/dns-static-lookups#standard-lookups) for additional information about the standard lookup format in Consul.
### RFC 2782 SRV lookup
Use the following format to execute a prepared query using the RFC 2782 lookup format:
```
_<query name or id>._tcp.query[.<datacenter>].<domain>
```
For additional information about following the RFC 2782 SRV lookup format in Consul, refer to [RFC 2782 Lookup](/consul/docs/services/discovery/dns-static-lookups#rfc-2782-lookup). For general information about the RFC 2782 specification, refer to [A DNS RR for specifying the location of services \(DNS SRV\)](https://tools.ietf.org/html/rfc2782).
### Lookup options
The `datacenter` subdomain is optional. By default, the lookup queries the datacenter of this Consul agent.
The `query name` or `id` subdomain is the name or ID of an existing prepared query.
## Results
To allow for simple load balancing, Consul returns the set of nodes in random order for each query. Prepared queries support A and SRV records. SRV records provide the port that a service is registered. Consul only serves SRV records if the client specifically requests them.

41
website/content/docs/services/discovery/dns-overview.mdx Normal file
View File

@ -0,0 +1,41 @@
---
layout: docs
page_title: DNS Usage Overview
description: >-
For service discovery use cases, Domain Name Service (DNS) is the main interface to look up, query, and address Consul nodes and services. Learn how a Consul DNS lookup can help you find services by tag, name, namespace, partition, datacenter, or domain.
---
# DNS Usage Overview
This topic provides overview information about how to look up Consul nodes and services using the Consul DNS.
## Consul DNS
The Consul DNS is the primary interface for discovering services registered in the Consul catalog. The DNS enables you to look up services and nodes registered with Consul using terminal commands instead of making HTTP API requests to Consul.
We recommend using the DNS for service discovery in virtual machine (VM) environments because it removes the need to modify native applications so that they can consume the Consul service discovery APIs.
The DNS has several default configurations, but you can customize how the server processes lookups. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for additional information.
### DNS versus native app integration
You can use DNS to reach services registered with Consul or modify your application to natively consume the Consul service discovery HTTP APIs.
We recommend using the DNS because it is less invasive. You do not have to modify your application with Consul to retrieve the service’s connection information. Instead, you can use a DNS fully qualified domain (FQDN) that conforms to Consul's lookup format to retreive the relevant information.
Refer to [ Native App Integration](/consul/docs/connect/native) and its [Go package](/consul/docs/connect/native/go) for additional information.
### DNS versus upstreams
If you are using Consul for service discovery and have not enabled service mesh features, then use the DNS to discover services and nodes in the Consul catalog.
If you are using Consul for service mesh on VMs, you can use upstreams or DNS. We recommend using upstreams because you can query services and nodes without modifying the application code or environment variables. Refer to [Upstream Configuration Reference](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for additional information.
If you are using Consul on Kubernetes, refer to [the upstreams annotation documentation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) for additional information.
## Static queries
Node lookups and service lookups are the fundamental types of static queries. Depending on your use case, you may need to use different query methods and syntaxes to query the DNS for services and nodes.
Consul relies on a very specific format for queries to resolve names. Note that all queries are case-sensitive.
Refer to [Perform Static DNS Lookups](/consul/docs/services/discovery/dns-static-lookups) for details about how to perform node and service lookups.
## Prepared queries
Prepared queries are configurations that enable you to register complex DNS queries. They provide lookup features that extend Consul's service discovery capabilities, such as filtering by multiple tags and automatically querying remote datacenters for services if no healthy nodes are available in the local datacenter. You can also create prepared query templates that match names using a prefix match, allowing a single template to apply to potentially many services. Refer to [Enable Dynamic DNS Queries](/consul/docs/services/discovery/dns-dynamic-lookups) for additional information.

357
website/content/docs/services/discovery/dns-static-lookups.mdx Normal file
View File

@ -0,0 +1,357 @@
---
layout: docs
page_title: Perform Static DNS Queries
description: ->
Learn how to use standard Consul DNS lookup formats to enable service discovery for services and nodes.
---
# Perform Static DNS Queries
This topic describes how to query the Consul DNS to look up nodes and services registered with Consul. Refer to [Enable Dynamic DNS Queries](/consul/docs/services/discovery/dns-dynamic-lookups) for information about using prepared queries.
## Introduction
Node lookups and service lookups are the fundamental types of queries you can perform using the Consul DNS. Node lookups interrogate the catalog for named Consul agents. Service lookups interrogate the catalog for services registered with Consul. Refer to [DNS Usage Overivew](/consul/docs/services/discovery/dns-overview) for additional background information.
## Requirements
All versions of Consul support DNS lookup features.
### ACLs
If ACLs are enabled, you must present a token linked with the necessary policies. We recommend using a separate token in production deployments for querying the DNS. By default, Consul agents resolve DNS requests using the preconfigured tokens in order of precedence:
The agent's [`default` token](/consul/docs/agent/config/config-files#acl_tokens_default)
The built-in [`anonymous` token](/consul/docs/security/acl/acl-tokens#built-in-tokens).
The following table describes the available DNS lookups and required policies when ACLs are enabled:
| Lookup | Type | Description | ACLs Required |
| --- | --- | --- | --- |
| `*.node.consul` | Node | Allows Consul to resolve DNS requests for the target node. Example: `<target>.node.consul` | `node:read` |
| `*.service.consul`<br/> `*.connect.consul` <br/> `*.ingress.consul` <br/>`*.virtual.consul` |Service: standard | Allows Consul to resolve DNS requests for target service instances running on ACL-authorized nodes. Example: `<target>.service.consul` | `service:read`<br/> `node:read` |
> **Tutorials**: For hands-on guidance on how to configure an appropriate token for DNS, refer to the tutorial for [Production Environments](/consul/tutorials/security/access-control-setup-production#token-for-dns) and [Development Environments](/consul/tutorials/day-0/access-control-setup#enable-acls-on-consul-clients).
## Node lookups
Specify the name of the node, datacenter, and domain using the following FQDN syntax:
```text
<node>.node[.<datacenter>.dc].<domain>
```
The `datacenter` subdomain is optional. By default, the lookup queries the datacenter of the agent.
By default, the domain is `consul`. Refer to [Configure DNS Behaviors]() for information about using alternate domains.
### Node lookup results
Node lookups return A and AAAA records that contain the IP address and TXT records containing the `node_meta` values of the node.
By default, TXT record values match the node's metadata key-value pairs according to [RFC1464](https://www.ietf.org/rfc/rfc1464.txt). If the metadata key starts with `rfc1035-`, the TXT record only includes the node's metadata value.
The following example lookup queries the `foo` node in the `default` datacenter:
```shell-session
$ dig @127.0.0.1 -p 8600 foo.node.consul ANY
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 foo.node.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 24355
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 0
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;foo.node.consul. IN ANY
;; ANSWER SECTION:
foo.node.consul. 0 IN A 10.1.10.12
foo.node.consul. 0 IN TXT "meta_key=meta_value"
foo.node.consul. 0 IN TXT "value only"
;; AUTHORITY SECTION:
consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
```
### Node lookups for Consul Enterprise
Consul Enterprise includes the admin partition concept, which is an abstraction that lets you define isolated administrative network areas. Refer to [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information.
Consul nodes reside in admin partitions within a datacenter. By default, node lookups query the same partition and datacenter of the Consul agent that received the DNS query.
Use the following query format to specify a partition for a node lookup:
```
<node>.node[.<partition>.ap][.<datacenter>.dc].<domain>
```
Consul server agents are in the `default` partition. If you send a DNS query to Consul server agents, you must explicitly specify the partition of the target node if it is not `default`.
## Service lookups
You can query the network for service providers using either the [standard lookup](#standard-lookup) method or [strict RFC 2782 lookup](#rfc-2782-lookup) method.
By default, all SRV records are weighted equally in service lookup responses, but you can configure the weights using the [`Weights`](/consul/docs/services/configuration/services-configuration-reference#weights) attribute of the service definition. Refer to [Define Services](/consul/docs/services/usage/define-services) for additional information.
The DNS protocol limits the size of requests, even when performing DNS TCP queries, which may affect your experience querying for services. For services with more than 500 instances, you may not be able to retrieve the complete list of instances for the service. Refer to [RFC 1035, Domain Names - Implementation and Specification](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.4) for additional information.
Consul randomizes DNS SRV records and ignores weights specified in service configurations when printing responses. If records are truncated, each client using weighted SRV responses may have partial and inconsistent views of instance weights. As a result, the request distribution may be skewed from the intended weights. We recommend calling the [`/catalog/nodes` API endpoint](/consul/api-docs/catalog#list-nodes) to retrieve the complete list of nodes. You can apply query parameters to API calls to sort and filter the results.
### Standard lookups
To perform standard service lookups, specify tags, the name of the service, datacenter, and domain using the following syntax to query for service providers:
```text
[<tag>.]<service>.service[.<datacenter>].dc.<domain>
```
The `tag` subdomain is optional. It filters responses so that only service providers containing the tag appear.
The `datacenter` subdomain is optional. By default, Consul interrogates the querying agent's datacenter.
By default, the lookups query in the `consul` domain. Refer to [Configure DNS Behaviors](/consul/docs/services/discovery/dns-configuration) for information about using alternate domains.
#### Standard lookup results
Standard services queries return A and SRV records. SRV records include the port that the service is registered on. SRV records are only served if the client specifically requests them.
Services that fail their health check or that fail a node system check are omitted from the results. As a load balancing measure, Consul randomizes the set of nodes returned in the response. These mechanisms help you use DNS with application-level retries as the foundation for a self-healing service-oriented architecture.
The following example retrieves the SRV records for any `redis` service registered in Consul.
```shell-session
$ dig @127.0.0.1 -p 8600 consul.service.consul SRV
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 50483
;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;consul.service.consul. IN SRV
;; ANSWER SECTION:
consul.service.consul. 0 IN SRV 1 1 8300 foobar.node.dc1.consul.
;; ADDITIONAL SECTION:
foobar.node.dc1.consul. 0 IN A 10.1.10.12
```
The following example command and FQDN retrieves the SRV records for the primary Postgres service in the secondary datacenter:
```shell-session hideClipboard
$ dig @127.0.0.1 -p 8600 primary.postgresql.service.dc2.consul SRV
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 primary.postgresql.service.dc2.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 50483
;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;consul.service.consul. IN SRV
;; ANSWER SECTION:
consul.service.consul. 0 IN SRV 1 1 5432 primary.postgresql.service.dc2.consul.
;; ADDITIONAL SECTION:
primary.postgresql.service.dc2.consul. 0 IN A 10.1.10.12
```
### RFC 2782 lookup
Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries must prepend `service` and `protocol` values with an underscore (`_`) to prevent DNS collisions. Use the following syntax to perform RFC 2782 lookups:
```text
_<service>._<protocol>[.service][.<datacenter>].<domain>
```
You can create lookups that filter results by placing service tags in the `protocol` field. Use the following syntax to create RFC 2782 lookups that filter results based on service tags:
```text
_<service>._<tag>[.service][.<datacenter>].<domain>
```
The following example queries the `rabbitmq` service tagged with `amqp`, which returns an instance at `rabbitmq.node1.dc1.consul` on port `5672`:
```shell-session
$ dig @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 52838
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;_rabbitmq._amqp.service.consul. IN SRV
;; ANSWER SECTION:
_rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul.
;; ADDITIONAL SECTION:
rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20
```
#### SRV responses for hosts in the .addr subdomain
If a service registered with Consul is configured with an explicit IP address or addresses in the [`address`](/consul/docs/services/configuration/services-configuration-reference#address) or [`tagged_address`](/consul/docs/services/configuration/services-configuration-reference#tagged_address) parameter, then Consul returns the hostname in the target field of the answer section for the DNS SRV query according to the following format:
```text
<hexadecimal-encoded IP>.addr.<datacenter>.consul`.
```
In the following example, the `rabbitmq` service is registered with an explicit IPv4 address of `192.0.2.10`.
```hcl
node_name = "node1"
services {
name = "rabbitmq"
address = "192.0.2.10"
port = 5672
}
{
"node_name": "node1",
"services": [
{
"name": "rabbitmq",
"address": "192.0.2.10",
"port": 5672
}
]
}
```
The following example SRV query response contains a single record with a hostname written as a hexadecimal value:
```shell-session
$ dig @127.0.0.1 -p 8600 -t srv _rabbitmq._tcp.service.consul +short
1 1 5672 c000020a.addr.dc1.consul.
```
You can convert hex octets to decimals to reveal the IP address. The following example command converts the hostname expressed as `c000020a` into the IPv4 address specified in the service registration.
```
$ echo -n "c000020a" | perl -ne 'printf("%vd\n", pack("H*", $_))'
192.0.2.10
```
In the following example, the `rabbitmq` service is registered with an explicit IPv6 address of `2001:db8:1:2:cafe::1337`.
```hcl
node_name = "node1"
services {
name = "rabbitmq"
address = "2001:db8:1:2:cafe::1337"
port = 5672
}
{
"node_name": "node1",
"services": [
{
"name": "rabbitmq",
"address": "2001:db8:1:2:cafe::1337",
"port": 5672
}
]
}
```
The following example SRV query response contains a single record with a hostname written as a hexadecimal value:
```shell-session
$ dig @127.0.0.1 -p 8600 -t SRV _rabbitmq._tcp.service.consul +short
1 1 5672 20010db800010002cafe000000001337.addr.dc1.consul.
```
The response contains the fully-expanded IPv6 address with colon separators removed. The following command re-adds the colon separators to display the fully expanded IPv6 address that was specified in the service registration.
```shell-session
$ echo -n "20010db800010002cafe000000001337" | perl -ne 'printf join(":", unpack("(A4)*", $_))."\n"'
2001:0db8:0001:0002:cafe:0000:0000:1337
```
### Service lookups for Consul Enterprise
You can perform the following types of service lookups to query for services in another namespace, partition, and datacenter:
- `.service`
- `.connect`
- `.virtual`
- `.ingress`
Use the following query format to specify namespace, partition, or datacenter:
```
[<tag>.]<service>.service[.<namespace>.ns][.<partition>.ap][.<datacenter>.dc]<domain>
```
The `namespace`, `partition`, and `datacenter` are optional. By default, all service lookups use the `default` namespace within the partition and datacenter of the Consul agent that received the DNS query.
Consul server agents reside in the `default` partition. If DNS queries are addressed to Consul server agents, you must explicitly specify the partition of the target service when querying for services in partitions other than `default`.
To lookup services imported from a cluster peer, refer to [Service virtual IP lookups for Consul Enterprise](#service-virtual-ip-lookups-for-consul-enterprise).
#### Alternative formats for specifying namespace
Although we recommend using the format described in [Service lookups for Consul Enterprise](#service-lookups-for-consul-enterprise) for readability, you can use the alternate query format to specify namespaces but not partitions:
```
[<tag>.]<service>.service.<namespace>.<datacenter>.<domain>
```
### Service mesh-enabled service lookups
Add the `.connect` subdomain to query for service mesh-enabled services:
```text
<service>.connect.<domain>
```
This finds all service mesh-capable endpoints for the service. A service mesh-capable endpoint may be a proxy for a service or a natively integrated service mesh application. The DNS interface does not differentiate the two.
Many services use a proxy that handles service discovery automatically. As a result, they may not use the DNS format, which is primarily for service mesh-native applications.
This endpoint only finds services within the same datacenter and does not support tags. Refer to the [`catalog` API endpoint](/consul/api-docs/catalog) for more complex behaviors.
### Service virtual IP lookups
Add the `.virtual` subdomain to queries to find the unique virtual IP allocated for a service:
```text
<service>.virtual[.<peer>].<domain>
```
This returns the unique virtual IP for any service mesh-capable service. Each service mesh service has a virtual IP assigned to it by Consul. Sidecar proxies use the virtual IP to enable the [transparent proxy](/consul/docs/connect/transparent-proxy) feature.
The peer name is an optional. The DNS uses it to query for the virtual IP of a service imported from the specified peer.
Consul adds virtual IPs to the [`tagged_addresses`](/consul/services/configuration/services-configuration-reference#tagged-addresses) field in the service definition under the `consul-virtual` tag.
#### Service virtual IP lookups for Consul Enterprise
By default, a service virtual IP lookup checks the `default` namespace within the partition and datacenter of the Consul agent that received the DNS query.
To lookup services imported from a partition in another cluster peered to the querying cluster or open-source datacenter, specify the namespace and peer name in the lookup:
```text
<service>.virtual[.<namespace>].<peer>.<domain>
```
To lookup services in a cluster peer that have not been imported, refer to [Service lookups for Consul Enterprise](#service-lookups-for-consul-enterprise).
### Ingress Service Lookups
Add the `.ingress` subdomain to your DNS FQDN to find ingress-enabled services:
```text
<service>.ingress.<domain>
```
This finds all ingress gateway endpoints for the service.
This endpoint finds services within the same datacenter and does not support tags. Refer to the [`catalog` API endpoint](/consul/api-docs/catalog) for more complex behaviors.
### UDP-based DNS queries
When the DNS query is performed using UDP, Consul truncateß the results without setting the truncate bit. This prevents a redundant lookup over TCP that generates additional load. If the lookup is done over TCP, the results are not truncated.

39
website/content/docs/services/services.mdx Normal file
View File

@ -0,0 +1,39 @@
---
layout: docs
page_title: Services Overview
description: >-
Learn about services and service discovery workflows and concepts for virtual machine environments.
---
# Services Overview
This topic provides overview information about services and how to make them discoverable in Consul when your network operates on virtual machines. If service mesh is enabled in your network, refer to the topics in [Consul Service Mesh](/consul/docs/connect/). If your network is running in Kubernetes, refer to the topics in [Consul on Kubernetes](/consul/docs/k8s).
## Introduction
A _service_ is an entity in your network that performs a specialized operation or set of related operations. In many contexts, a service is software that you want to make available to users or other programs with access to your network. Services can also refer to native Consul functionality, such as _service mesh proxies_ and _gateways_, that enable you to establish connections between different parts of your network.
You can define and register services with Consul, which makes them discoverable to other services in the network. You can also define various types of health checks that perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary.
## Workflow
For service discovery, the core Consul workflow for services consists of three stages:
1. **Define services and health checks**: A service definition lets you define various aspects of the service, including how it is discovered by other services in the network. You can define health checks in the service definitions to verify the health of the service. Refer to [Define Services](/consul/docs/services/usage/define-services) and [Define Health Checks](/consul/docs/services/usage/checks) for additional information.
1. **Register services and health checks**: After defining your services and health checks, you must register them with a Consul agent. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for additional information.
1. **Query for services**: After registering your services and health checks, other services in your network can use the DNS to perform static or dynamic lookups to access your service. Refer to [DNS Usage Overview](/consul/docs/services/discovery/dns-overview) for additional information about the different ways to discover services in your datacenters.
## Service mesh use cases
Consul redirects service traffic through sidecar proxies if you use Consul service mesh. As a result, you must specify upstream configurations in service definitions. The service mesh experience is different for virtual machine (VM) and Kubernetes environments.
### Virtual machines
You must define upstream services in the service definition. Consul uses the upstream configuration to bind the service with its upstreams. After registering the service, you must start a sidecar proxy on the VM to enable mesh connectivity. Refer to [Register a Service Mesh Proxy in a Service Registration](/consul/docs/connect/registration/sidecar-service) for details.
### Kubernetes
If you use Consul on Kubernetes, enable the service mesh injector in your Consul Helm chart and Consul automatically adds a sidecar to each of your pods using the Kubernetes `Service` definition as a reference. You can specify upstream annotations in the `Deployment` definition to bind upstream services to the pods.
Refer to [`connectInject`](/consul/docs/k8s/connect#installation-and-configuration) and [the upstreams annotation documentation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) for additional information.
### Multiple services
You can define common characteristics for services in your mesh, such as the admin partition, namespace, or upstreams, by creating and applying a `service-defaults` configuration entry. You can also define override configurations for specific upstreams or service instances. To use `service-defaults` configuraiton entries, you must enable Consul service mesh in your network.
Refer to [Define Service Defaults](/consul/docs/services/usage/define-services#define-service-defaults) for additional information.

592
website/content/docs/services/usage/checks.mdx Normal file
View File

@ -0,0 +1,592 @@
---
layout: docs
page_title: Define Health Checks
description: ->
Learn how to configure different types of health checks for services you register with Consul.
---
# Define Health Checks
This topic describes how to create different types of health checks for your services.
## Overview
Health checks are configurations that verifies the health of a service or node. Health checks configurations are nested in the `service` block. Refer to [Define Services](/consul/docs/services/usage/define-services) for information about specifying other service parameters.
You can define individual health checks for your service in separate `check` blocks or define multiple checks in a `checks` block. Refer to [Define multiple checks](#define-multiple-checks) for additional information.
You can create several different kinds of checks:
- _Script_ checks invoke an external application that performs the health check, exits with an appropriate exit code, and potentially generates output. Script checks are one of the most common types of checks.
- _HTTP_ checks make an HTTP GET request to the specified URL and wait for the specified amount of time. HTTP checks are one of the most common types of checks.
- _TCP_ checks attempt to connect to an IP or hostname and port over TCP and wait for the specified amount of time.
- _UDP_ checks send UDP datagrams to the specified IP or hostname and port and wait for the specified amount of time.
- _Time-to-live (TTL)_ checks are passive checks that await updates from the service. If the check does not receive a status update before the specified duration, the health check enters a `critical`state.
- _Docker_ checks are dependent on external applications packaged with a Docker container that are triggered by calls to the Docker `exec` API endpoint.
- _gRPC_ checks probe applications that support the standard gRPC health checking protocol.
- _H2ping_ checks test an endpoint that uses http2. The check connects to the endpoint and sends a ping frame.
- _Alias_ checks represent the health state of another registered node or service.
If your network runs in a Kubernetes environment, you can sync service health information with Kubernetes health checks. Refer to [Configure Health Checks for Consul on Kubernetes](/consul/docs/k8s/connect/health) for details.
### Registration
After defining health checks, you must register the service containing the checks with Consul. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for additional information. If the service is already registered, you can reload the service configuration file to implement your health check. Refer to [Reload](/consul/commands/reload) for additional information.
## Define multiple checks
You can define multiple checks for a service in a single `checks` block. The `checks` block contains an array of objects. The objects contain the configuration for each health check you want to implement. The following example includes two script checks named `mem` and `cpu` and an HTTP check that calls the `/health` API endpoint.
<CodeTabs tabs={[ "HCL","JSON" ]} heading="Multiple checks example">
```hcl
checks = [
{
id = "chk1"
name = "mem"
args = ["/bin/check_mem", "-limit", "256MB"]
interval = "5s"
},
{
id = "chk2"
name = "/health"
http = "http://localhost:5000/health"
interval = "15s"
},
{
id = "chk3"
name = "cpu"
args = ["/bin/check_cpu"]
interval = "10s"
},
...
]
```
```json
{
"checks": [
{
"id": "chk1",
"name": "mem",
"args": ["/bin/check_mem", "-limit", "256MB"],
"interval": "5s"
},
{
"id": "chk2",
"name": "/health",
"http": "http://localhost:5000/health",
"interval": "15s"
},
{
"id": "chk3",
"name": "cpu",
"args": ["/bin/check_cpu"],
"interval": "10s"
},
...
]
}
```
</CodeTabs>
## Define initial health check status
When checks are registered against a Consul agent, they are assigned a `critical` status by default. This prevents services from registering as `passing` and entering the service pool before their health is verified. You can add the `status` parameter to the check definition to specify the initial state. In the following example, the check registers in a `passing` state:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="Define initial check status example">
```hcl
check = {
id = "mem"
args = ["/bin/check_mem", "-limit", "256MB"]
interval = "10s"
status = "passing"
}
```
```json
{
"check": [
{
"args": [
"/bin/check_mem",
"-limit",
"256MB"
],
"id": "mem",
"interval": "10s",
"status": "passing"
}
]
}
```
</CodeTabs>
## Script checks
Script checks invoke an external application that performs the health check, exits with an appropriate exit code, and potentially generates output data. The output of a script check is limited to 4KB. Outputs that exceed the limit are truncated.
Script checks timeout after 30 seconds by default, but you can configure a custom script check timeout value by specifying the `timeout` field in the check definition. When the timeout is reached on Windows, Consul waits for any child processes spawned by the script to finish. For any other system, Consul attempts to force-kill the script and any child processes it has spawned once the timeout has passed.
### Script check configuration
To enable script checks, you must first enable the agent to send external requests, then configure the health check settings in the service definition:
1. Add one of the following configurations to your agent configuration file to enable a script check:
- [`enable_local_script_checks`](/consul/docs/agent/config/cli-flags#enable_local_script_checks): Enable script checks defined in local configuration files. Script checks registered using the HTTP API are not allowed.
- [`enable_script_checks`](/consul/docs/agent/config/cli-flags#enable_script_checks): Enable script checks no matter how they are registered.
!> **Security warning:** Enabling non-local script checks in some configurations may introduce a known remote execution vulnerability targeted by malware. We strongly recommend `enable_local_script_checks` instead.
1. Specify the script to run in the `args` of the `check` block in your service configuration file. In the following example, a check named `Memory utilization` invokes the `check_mem.py` script every 10 seconds and times out if a response takes longer than one second:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="Script check configuration">
```hcl
service {
## ...
check = {
id = "mem-util"
name = "Memory utilization"
args = ["/usr/local/bin/check_mem.py", "-limit", "256MB"]
interval = "10s"
timeout = "1s"
}
}
```
```json
{
"service": [
{
"check": {
"id": "mem-util",
"name": "Memory utilization",
"args": ["/usr/local/bin/check_mem.py", "-limit", "256MB"],
"interval": "10s",
"timeout": "1s"
}
} ]
}
```
</CodeTabs>
Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference) for information about all health check configurations.
### Script check exit codes
The following exit codes returned by the script check determine the health check status:
- Exit code 0 - Check is passing
- Exit code 1 - Check is warning
- Any other code - Check is failing
Any output of the script is captured and made available in the `Output` field of checks included in HTTP API responses. Refer to the example described in the [local service health endpoint](/consul/api-docs/agent/service#by-name-json).
## HTTP checks
_HTTP_ checks send an HTTP request to the specified URL and report the service health based on the [HTTP response code](#http-check-response-codes). We recommend using HTTP checks over [script checks](#script-checks) that use cURL or another external process to check an HTTP operation.
### HTTP check configuration
Add an `http` field to the `check` block in your service definition file and specify the HTTP address, including port number, for the check to call. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference) for information about all health check configurations.
In the following example, an HTTP check named `HTTP API on port 5000` sends a `POST` request to the `health` endpoint every 10 seconds:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="HTTP check configuration">
```hcl
check = {
id = "api"
name = "HTTP API on port 5000"
http = "https://localhost:5000/health"
tls_server_name = ""
tls_skip_verify = false
method = "POST"
header = {
Content-Type = ["application/json"]
}
body = "{\"method\":\"health\"}"
disable_redirects = true
interval = "10s"
timeout = "1s"
}
```
```json
{
"check": {
"id": "api",
"name": "HTTP API on port 5000",
"http": "https://localhost:5000/health",
"tls_server_name": "",
"tls_skip_verify": false,
"method": "POST",
"header": { "Content-Type": ["application/json"] },
"body": "{\"method\":\"health\"}",
"interval": "10s",
"timeout": "1s"
}
}
```
</CodeTabs>
HTTP checks send GET requests by default, but you can specify another request method in the `method` field. You can send additional headers in the `header` block. The `header` block contains a key and an array of strings, such as `{"x-foo": ["bar", "baz"]}`. By default, HTTP checks timeout at 10 seconds, but you can specify a custom timeout value in the `timeout` field.
HTTP checks expect a valid TLS certificate by default. You can disable certificate verification by setting the `tls_skip_verify` field to `true`. When using TLS and a host name is specified in the `http` field, the check automatically determines the SNI from the URL. If the `http` field is configured with an IP address or if you want to explicitly set the SNI, specify the name in the `tls_server_name` field.
The check follows HTTP redirects configured in the network by default. Set the `disable_redirects` field to `true` to disable redirects.
### HTTP check response codes
Responses larger than 4KB are truncated. The HTTP response determines the status of the service:
- A `200`-`299` response code is healthy.
- A `429` response code indicating too many requests is a warning.
- All other response codes indicate a failure.
## TCP checks
TCP checks establish connections to the specified IPs or hosts. If the check successfully establishes a connection, the service status is reported as `success`. If the IP or host does not accept the connection, the service status is reported as `critical`. We recommend TCP checks over [script checks](#script-checks) that use netcat or another external process to check a socket operation.
### TCP check configuration
Add a `tcp` field to the `check` block in your service definition file and specify the address, including port number, for the check to call. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/health-checks-configuration) for information about all health check configurations.
In the following example, a TCP check named `SSH TCP on port 22` attempts to connect to `localhost:22` every 10 seconds:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="TCP check configuration">
```hcl
check = {
id = "ssh"
name = "SSH TCP on port 22"
tcp = "localhost:22"
interval = "10s"
timeout = "1s"
}
```
```json
{
"check": {
"id": "ssh",
"name": "SSH TCP on port 22",
"tcp": "localhost:22",
"interval": "10s",
"timeout": "1s"
}
}
```
</CodeTabs>
If a hostname resolves to an IPv4 and an IPv6 address, Consul attempts to connect to both addresses. The first successful connection attempt results in a successful check.
By default, TCP check requests timeout at 10 seconds, but you can specify a custom timeout in the `timeout` field.
## UDP checks
UDP checks direct the Consul agent to send UDP datagrams to the specified IP or hostname and port. The check status is set to `success` if any response is received from the targeted UDP server. Any other result sets the status to `critical`.
### UDP check configuration
Add a `udp` field to the `check` block in your service definition file and specify the address, including port number, for sending datagrams. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference) for information about all health check configurations.
In the following example, a UDP check named `DNS UDP on port 53` sends datagrams to `localhost:53` every 10 seconds:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="UDP Check">
```hcl
check = {
id = "dns"
name = "DNS UDP on port 53"
udp = "localhost:53"
interval = "10s"
timeout = "1s"
}
```
```json
{
"check": {
"id": "dns",
"name": "DNS UDP on port 53",
"udp": "localhost:53",
"interval": "10s",
"timeout": "1s"
}
}
```
</CodeTabs>
By default, UDP checks timeout at 10 seconds, but you can specify a custom timeout in the `timeout` field. If any timeout on read exists, the check is still considered healthy.
## OSService check
OSService checks if an OS service is running on the host. OSService checks support Windows services on Windows hosts or SystemD services on Unix hosts. The check logs the service as `healthy` if it is running. If the service is not running, the status is logged as `critical`. All other results are logged with `warning`. A `warning` status indicates that the check is not reliable because an issue is preventing it from determining the health of the service.
### OSService check configurations
Add an `os_service` field to the `check` block in your service definition file and specify the name of the service to check. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference] for information about all health check configurations.
In the following example, an OSService check named `svcname-001 Windows Service Health` verifies that the `myco-svctype-svcname-001` service is running every 10 seconds:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="OSService check configuration">
```hcl
check = {
id = "myco-svctype-svcname-001"
name = "svcname-001 Windows Service Health"
service_id = "flash_pnl_1"
os_service = "myco-svctype-svcname-001"
interval = "10s"
}
```
```json
{
"check": {
"id": "myco-svctype-svcname-001",
"name": "svcname-001 Windows Service Health",
"service_id": "flash_pnl_1",
"os_service": "myco-svctype-svcname-001",
"interval": "10s"
}
}
```
</CodeTabs>
## TTL checks
Time-to-live (TTL) checks wait for an external process to report the service's state to a Consul [`/agent/check` HTTP endpoint](/consul/api-docs/agent/check). If the check does not receive an update before the specified `ttl` duration, the check logs the service as `critical`. For example, if a healthy application is configured to periodically send a `PUT` request a status update to the HTTP endpoint, then the health check logs a `critical` state if the application is unable to send the update before the TTL expires. The check uses the following endpoints to update health information:
- [pass](/consul/api-docs/agent/check#ttl-check-pass)
- [warn] (/consul/api-docs/agent/check#ttl-check-warn)
- [fail](/consul/api-docs/agent/check#ttl-check-fail)
- [update](/consul/api-docs/agent/check#ttl-check-update)
TTL checks also persist their last known status to disk so that the Consul agent can restore the last known status of the check across restarts. Persisted check status is valid through the end of the TTL from the time of the last check.
You can manually mark a service as unhealthy using the [`consul maint` CLI command](/consul/commands/maint) or [`agent/maintenance` HTTP API endpoint](/consul/api-docs/agent#enable-maintenance-mode), rather than waiting for a TTL health check if the `ttl` duration is high.
### TTL check configuration
Add a `ttl` field to the `check` block in your service definition file and specify how long to wait for an update from the external process. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference] for information about all health check configurations.
In the following example, a TTL check named `Web App Status` logs the application as `critical` if a status update is not received every 30 seconds:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="TTL check configuration">
```hcl
check = {
id = "web-app"
name = "Web App Status"
notes = "Web app does a curl internally every 10 seconds"
ttl = "30s"
}
```
```json
{
"check": {
"id": "web-app",
"name": "Web App Status",
"notes": "Web app does a curl internally every 10 seconds",
"ttl": "30s"
}
}
```
</CodeTabs>
## Docker checks
Docker checks invoke an application packaged within a Docker container. The application should perform a health check and exit with an appropriate exit code.
The application is triggered within the running container through the Docker `exec` API. You should have access to either the Docker HTTP API or the Unix socket. Consul uses the `$DOCKER_HOST` environment variable to determine the Docker API endpoint.
The output of a Docker check is limited to 4KB. Larger outputs are truncated.
### Docker check configuration
To enable Docker checks, you must first enable the agent to send external requests, then configure the health check settings in the service definition:
1. Add one of the following configurations to your agent configuration file to enable a Docker check:
- [`enable_local_script_checks`](/consul/docs/agent/config/cli-flags#enable_local_script_checks): Enable script checks defined in local config files. Script checks registered using the HTTP API are not allowed.
- [`enable_script_checks`](/consul/docs/agent/config/cli-flags#enable_script_checks): Enable script checks no matter how they are registered.
!> **Security warning**: Enabling non-local script checks in some configurations may introduce a known remote execution vulnerability targeted by malware. We strongly recommend `enable_local_script_checks` instead.
1. Configure the following fields in the `check` block in your service definition file:
- `docker_container_id`: The `docker ps` command is a common way to get the ID.
- `shell`: Specifies the shell to use for performing the check. Different containers can run different shells on the same host.
- `args`: Specifies the external application to invoke.
- `interval`: Specifies the interval for running the check.
In the following example, a Docker check named `Memory utilization` invokes the `check_mem.py` application in container `f972c95ebf0e` every 10 seconds:
<CodeTabs tabs={[ "HCL","JSON" ]} heading="Docker check configuration">
```hcl
check = {
id = "mem-util"
name = "Memory utilization"
docker_container_id = "f972c95ebf0e"
shell = "/bin/bash"
args = ["/usr/local/bin/check_mem.py"]
interval = "10s"
}
```
```json
{
"check": {
"id": "mem-util",
"name": "Memory utilization",
"docker_container_id": "f972c95ebf0e",
"shell": "/bin/bash",
"args": ["/usr/local/bin/check_mem.py"],
"interval": "10s"
}
}
```
</CodeTabs>
## gRPC checks
gRPC checks send a request to the specified endpoint. These checks are intended for applications that support the standard [gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
### gRPC check configuration
Add a `grpc` field to the `check` block in your service definition file and specify the endpoint, including port number, for sending requests. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference] for information about all health check configurations.
In the following example, a gRPC check named `Service health status` probes the entire application by sending requests to `127.0.0.1:12345` every 10 seconds:
<CodeTabs tabs={[ "HCL","JSON"]} heading="gRPC check on entire application">
```hcl
check = {
id = "mem-util"
name = "Service health status"
grpc = "127.0.0.1:12345"
grpc_use_tls = true
interval = "10s"
}
```
```json
{
"check": {
"id": "mem-util",
"name": "Service health status",
"grpc": "127.0.0.1:12345",
"grpc_use_tls": true,
"interval": "10s"
}
}
```
</CodeTabs>
gRPC checks probe the entire gRPC server, but you can check on a specific service by adding the service identifier after the gRPC check's endpoint using the following format: `/:service_identifier`.
In the following example, a gRPC check probes `my_service` in the application at `127.0.0.1:12345` every 10 seconds:
<CodeTabs tabs={[ "HCL","JSON"]} heading="gRPC check for a specific service">
```hcl
check = {
id = "mem-util"
name = "Service health status"
grpc = "127.0.0.1:12345/my_service"
grpc_use_tls = true
interval = "10s"
}
```
```json
{
"check": {
"id": "mem-util",
"name": "Service health status",
"grpc": "127.0.0.1:12345/my_service",
"grpc_use_tls": true,
"interval": "10s"
}
}
```
</CodeTabs>
TLS is disabled for gRPC checks by default. You can enable TLS by setting `grpc_use_tls` to `true`. If TLS is enabled, you must either provide a valid TLS certificate or disable certificate verification by setting the `tls_skip_verify` field to `true`.
By default, gRPC checks timeout after 10 seconds, but you can specify a custom duration in the `timeout` field.
## H2ping checks
H2ping checks test an endpoint that uses HTTP2 by connecting to the endpoint and sending a ping frame. If the endpoint sends a response within the specified interval, the check status is set to `success`.
### H2ping check configuration
Add an `h2ping` field to the `check` block in your service definition file and specify the HTTP2 endpoint, including port number, for the check to ping. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference) for information about all health check configurations.
In the following example, an H2ping check named `h2ping` pings the endpoint at `localhost:22222` every 10 seconds:
<CodeTabs tabs={[ "HCL", "JSON" ]} heading="H2ping check configuration">
```hcl
check = {
id = "h2ping-check"
name = "h2ping"
h2ping = "localhost:22222"
interval = "10s"
h2ping_use_tls = false
}
```
```json
{
"check": {
"id": "h2ping-check",
"name": "h2ping",
"h2ping": "localhost:22222",
"interval": "10s",
"h2ping_use_tls": false
}
}
```
</CodeTabs>
TLS is enabled by default, but you can disable TLS by setting `h2ping_use_tls` to `false`. When TLS is disabled, the Consul sends pings over h2c. When TLS is enabled, a valid certificate is required unless `tls_skip_verify` is set to `true`.
By default, H2ping checks timeout at 10 seconds, but you can specify a custom duration in the `timeout` field.
## Alias checks
Alias checks continuously report the health state of another registered node or service. If the alias experiences errors while watching the actual node or service, the check reports a`critical` state. Consul updates the alias and actual node or service state asynchronously but nearly instantaneously.
For aliased services on the same agent, the check monitors the local state without consuming additional network resources. For services and nodes on different agents, the check maintains a blocking query over the agent's connection with a current server and allows stale requests.
### ACLs
For the blocking query, the alias check presents the ACL token set on the actual service or the token configured in the check definition. If neither are available, the alias check falls back to the default ACL token set for the agent. Refer to [`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default) for additional information about the default ACL token.
### Alias checks configuration
Add an `alias_service` field to the `check` block in your service definition file and specify the name of the service or node to alias. All other fields are optional. Refer to [Health Checks Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference] for information about all health check configurations.
In the following example, an alias check with the ID `web-alias` reports the health state of the `web` service:
<CodeTabs tabs={[ "HCL", "JSON" ]} heading="Alias check configuration">
```hcl
check = {
id = "web-alias"
alias_service = "web"
}
```
```json
{
"check": {
"id": "web-alias",
"alias_service": "web"
}
}
```
</CodeTabs>
By default, the alias must be registered with the same Consul agent as the alias check. If the service is not registered with the same agent, you must specify `"alias_node": "<node_id>"` in the `check` configuration. If no service is specified and the `alias_node` field is enabled, the check aliases the health of the node. If a service is specified, the check will alias the specified service on this particular node.

366
website/content/docs/services/usage/define-services.mdx Normal file
View File

@ -0,0 +1,366 @@
---
layout: docs
page_title: Define Services
description: >-
Learn how to define services so that they are discoverable in your network.
---
# Define Services
This topic describes how to define services so that they can be discovered by other services. Refer to [Services Overview](/consul/docs/services/services) for additional information.
## Overview
You must tell Consul about the services deployed to your network if you want them to be discoverable. You can define services in a configuration file or send the service definition parameters as a payload to the `/agent/service/register` API endpoint. Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for details about how to register services with Consul.
You can define multiple services individually using `service` blocks or group multiple services into the same `services` configuration block. Refer to [Define multiple services in a single file](#define-multiple-services-in-a-single-file) for additional information.
If Consul service mesh is enabled in your network, you can use the `service-defaults` configuration entry to specify default global values for services. The configuraiton entry lets you define common service parameter, such as upstreams, namespaces, and partitions. Refer to [Define service defaults](#define-service-defaults) for additional information.
## Requirements
The core service discovery features are available in all versions of Consul.
### Service defaults
To use the [service defaults configuration entry](#define-service-defaults), verify that your installation meets the following requirements:
- Consul 1.5.0+
- Consul 1.8.4+ is required to use the `ServiceDefaults` custom resource on Kubernetes
### ACLs
If ACLs are enabled, resources in your network must present a token with `service:read` access to read a service defaults configuration entry.
You must also present a token with `service:write` access to create, update, or delete a service defaults configuration entry.
Service configurations must also contain and present an ACL token to perform anti-entropy syncs and deregistration operations. Refer to [Modify anti-entropy synchronozation](#modify-anti-entropy-synchronization) for additional information.
On Consul Enterprise, you can register services with specific namespaces if the services' ACL tokens are scoped to the namespace. Services registered with a service definition do not inherit the namespace associated with the ACL token specified in the `token` field. The `namespace` and the `token` parameters must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to.
## Define a service
Create a file for your service configurations and add a `service` block. The `service` block contains the parameters that configure various aspects of the service, including how it is discovered by other services in the network. The only required parameter is `name`. Refer to [Service Definition Reference](/consul/docs/services/configuration/services-configuration-reference) for details about the configuration options.
For Kubernetes environments, you can enable the [`connectInject`](/consul/docs/k8s/connect#installation-and-configuration) configuration in your Consul Helm chart so that Consul automatically adds a sidecar to each of your pods. Consul uses the Kubernetes `Service` definition as a reference.
The following example defines a service named `redis` that is available on port `80`. By default, the service has the IP address of the agent node.
<CodeTabs>
<CodeBlockConfig heading="service.hcl">
```hcl
service {
name = "redis"
id = "redis"
port = 80
tags = ["primary"]
meta = {
custom_meta_key = "custom_meta_value"
}
tagged_addresses = {
lan = {
address = "192.168.0.55"
port = 8000
}
wan = {
address = "198.18.0.23"
port = 80
}
}
}
```
</CodeBlockConfig>
<CodeBlockConfig heading="service.json">
```json
{
"service": [
{
"id": "redis",
"meta": [
{
"custom_meta_key": "custom_meta_value"
}
],
"name": "redis",
"port": 80,
"tagged_addresses": [
{
"lan": [
{
"address": "192.168.0.55",
"port": 8000
}
],
"wan": [
{
"address": "198.18.0.23",
"port": 80
}
]
}
],
"tags": [
"primary"
]
}
]
}
```
</CodeBlockConfig>
<CodeBlockConfig heading="service.yaml">
```yaml
service:
- id: redis
meta:
- custom_meta_key: custom_meta_value
name: redis
port: 80
tagged_addresses:
- lan:
- address: 192.168.0.55
port: 8000
wan:
- address: 198.18.0.23
port: 80
tags:
- primary
```
</CodeBlockConfig>
</CodeTabs>
### Health checks
You can add a `check` or `checks` block to your service configuration to define one or more health checks that monitor the health of your services. Refer to [Define Health Checks](/consul/docs/services/usage/checks) for additional information.
### Register a service
You can register your service using the [`consul services` command](/consul/commands/services) or by calling the [`/agent/services` API endpoint](/consul/api-docs/agent/services). Refer to [Register Services and Health Checks](/consul/docs/services/usage/register-services-checks) for details.
## Define service defaults
If Consul service mesh is enabled in your network, you can define default values for services in your mesh by creating and applying a `service-defaults` configuration entry containing. Refer to [Service Mesh Configuration Overview](/consul/docs/connect/configuration) for additional information.
Create a file for the configuration entry and specify the required fields. If you are authoring `service-defaults` in HCL or JSON, the `Kind` and `Name` fields are required. On Kubernetes, the `apiVersion`, `kind`, and `metadata.name` fields are required. Refer to [Service Defaults Reference](/consul/docs/connect/config-entries/service-defaults) for details about the configuration options.
The following example instructs services named `counting` to send up to `512` concurrent requests to a mesh gateway:
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
```hcl
Kind = "service-defaults"
Name = "counting"
UpstreamConfig = {
Defaults = {
MeshGateway = {
Mode = "local"
}
Limits = {
MaxConnections = 512
MaxPendingRequests = 512
MaxConcurrentRequests = 512
}
}
Overrides = [
{
Name = "dashboard"
MeshGateway = {
Mode = "remote"
}
}
]
}
```
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: counting
spec:
upstreamConfig:
defaults:
meshGateway:
mode: local
limits:
maxConnections: 512
maxPendingRequests: 512
maxConcurrentRequests: 512
overrides:
- name: dashboard
meshGateway:
mode: remote
```
```json
{
"Kind": "service-defaults",
"Name": "counting",
"UpstreamConfig": {
"Defaults": {
"MeshGateway": {
"Mode": "local"
},
"Limits": {
"MaxConnections": 512,
"MaxPendingRequests": 512,
"MaxConcurrentRequests": 512
}
},
"Overrides": [
{
"Name": "dashboard",
"MeshGateway": {
"Mode": "remote"
}
}
]
}
}
```
</CodeTabs>
### Apply service defaults
You can apply your `service-defaults` configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `service-defaults` custom resource definitions (CRD) to implement and manage Consul configuration entries.
Refer to the following topics for details about applying configuration entries:
- [How to Use Configuration Entries](/consul/docs/agent/config-entries)
- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds)
## Define multiple services in a single file
The `services` block contains an array of `service` objects. It is a wrapper that enables you to define multiple services in the service definition and instruct Consul to expect more than just a single service configuration. As a result, you can register multiple services in a single `consul services register` command. Note that the `/agent/service/register` API endpoint does not support the `services` parameter.
In the following example, the service definition configures an instance of the `redis` service tagged as `primary` running on port `6000`. It also configures an instance of the service tagged as `secondary` running on port `7000`.
<CodeTabs heading="Multiple Service Definitions">
<CodeBlockConfig filename="redis-services.hcl">
```hcl
services {
id = "red0"
name = "redis"
tags = [
"primary"
]
address = ""
port = 6000
checks = [
{
args = ["/bin/check_redis", "-p", "6000"]
interval = "5s"
timeout = "20s"
}
]
}
services {
id = "red1"
name = "redis"
tags = [
"delayed",
"secondary"
]
address = ""
port = 7000
checks = [
{
args = ["/bin/check_redis", "-p", "7000"]
interval = "30s"
timeout = "60s"
}
]
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="redis-services.json">
```json
{
"services": [
{
"id": "red0",
"name": "redis",
"tags": [
"primary"
],
"address": "",
"port": 6000,
"checks": [
{
"args": ["/bin/check_redis", "-p", "6000"],
"interval": "5s",
"timeout": "20s"
}
]
},
{
"id": "red1",
"name": "redis",
"tags": [
"delayed",
"secondary"
],
"address": "",
"port": 7000,
"checks": [
{
"args": ["/bin/check_redis", "-p", "7000"],
"interval": "30s",
"timeout": "60s"
}
]
},
...
]
}
```
</CodeBlockConfig>
</CodeTabs>
## Modify anti-entropy synchronization
By default, the Consul agent uses anti-entropy mechanisms to maintain information about services and service health, and synchronize local states with the Consul catalog. You can enable the `enable_tag_override` option in the service configuration, which lets external agents change the tags for a service. This can be useful in situations where an external monitoring service needs to be the source of truth for tag information. Refer [Anti-entropy](/consul/docs/architecture/anti-entropy) for details.
Add the `enable_tag_override` option to the `service` block and set the value to `true`:
<CodeTabs tabs={[ "HCL","JSON" ]}>
```hcl
service {
## ...
enable_tag_override = true
## ...
}
```
```json
"service": {
## ...
"enable_tag_override": true,
## ...
}
```
</CodeTabs>
This configuration only applies to the locally registered service. Nodes that register the same service apply the `enable_tag_override` and other service configurations independently. The tags for a service registered on one node update are not affected by operations performed on services with the same name registered on other nodes.
Refer to [`enable_tag_override`](/consul/docs/services/configuration/services-configuration-reference#enable_tag_override) for additional configuration information.
## Services in service mesh environments
Defining services for service mesh environments on virtual machines and in Kubernetes requires a different workflow.
### Define service mesh proxies
You can register services to function as service mesh or sidecar proxies so that they can facilitate communication between other services across your network. Refer to [Service Mesh Proxy Overview](/consul/docs/connect/registration) for additional information.
### Define services in Kubernetes
You can enable the services running in Kubernetes and Consul to sync automatically. Doing so ensures that Kubernetes services are available to Consul agents and services in Consul can be available as first-class Kubernetes services. Refer to [Service Sync for Consul on Kubernetes](/consul/docs/k8s/service-sync) for details.

67
website/content/docs/services/usage/register-services-checks.mdx Normal file
View File

@ -0,0 +1,67 @@
---
layout: docs
page_title: Register Services and Health Checks
description: ->
Learn how to register services and health checks with Consul agents.
---
# Register Services and Health Checks
This topic describes how to register services and health checks with Consul in networks running on virtual machines (VM). Refer to [Define Services](/consul/usage/services/usage/define-services) and [Define Health Checks](/consul/usage/services/usage/checks) for information about how to define services and health checks.
## Overview
Register services and health checks in VM environments by providing the service definition to a Consul agent. You can use several different methods to register services and health checks.
- Start a Consul agent and pass the service definition in the [agent's configuration directory](/consul/docs/agent#configuring-consul-agents).
- Reload the a running Consul agent and pass the service definition in the [agent's configuration directory](/consul/docs/agent#configuring-consul-agents). Use this method when implementing changes to an existing service or health check definition.
- Use the [`consul services register` command](/consul/commands/services/register) to register new service and health checks with a running Consul agent.
- Call the [`/agent/service/register`](/consul/api-docs/agent/service#register-service) HTTP API endpoint to to register new service and health checks with a running Consul agent.
- Call the [`/agent/check/register`](/consul/api-docs/agent/check#register-check) HTTP API endpoint to register a health check independent from the service.
When a service is registered using the HTTP API endpoint or CLI command, the checks persist in the Consul data folder. If the agent restarts, Consul uses the service and check configurations in the configuration directory to start the services.
Note that health checks associated with a service are application-level checks.
## Start an agent
We recommend registering services on startup because the service persists if the agent fails. Specify the directory containing the service definition with the `-config-dir` option on startup. When the Consul agent starts, it processes all configurations in the directory and registers any services contained in the configurations. In the following example, the Consul agent starts and loads the configurations contained in the `configs` directory:
```shell-session
$ consul agent -config-dir configs
```
Refer to [Starting the Consul Agent](/consul/docs/agent#starting-the-consul-agent) for additional information.
## Reload an agent
Store your service definition file in the directory containing your Consul configuration files and either send a `SIGHUP` signal to the Consul agent service or run the `consul reload` command. Refer to [Consul Reload](/consul/commands/reload) for additional information.
## Register using the CLI
Run the `consul services register` command and specify the service definition file to register the services and health checks defined in the file. In the following example, a service named `web` is registered:
```shell-session
$ consul services register -name=web services.hcl
```
Refer to [Consul Agent Service Registration](/consul/commands/services/register) for additional information about using the command.
## Register using the API
Use the following methods to register services and health checks using the HTTP API.
### Register services
Send a `PUT` request to the `/agent/service/register` API endpoint to dynamically register a service and its associated health checks. To register health checks independently, [call the checks API endpoint](#call-the-checks-http-api-endpoint).
The following example request registers the service defined in the `service.json` file.
```shell-session
$ curl --request PUT --data @service.json http://localhost:8500/v1/agent/service/register
```
Refer to [Service - Agent HTTP API](/consul/api-docs/agent/service) for additional information about the `services` endpoint.
### Register health checks
Send a `PUT` request to the `/agent/check/register` API endpoint to dynamically register a health check to the local Consul agent. The following example request registers a health check defined in a `payload.json` file.
```shell-session
$ curl --request PUT --data @payload.json http://localhost:8500/v1/agent/check/register
```
Refer to [Check - Agent HTTP API](/consul/api-docs/check/service) for additional information about the `check` endpoint.

4
website/content/docs/troubleshoot/troubleshoot-services.mdx
View File

@ -13,7 +13,7 @@ For more information, refer to the [`consul troubleshoot` CLI documentation](/co
## Introduction
When communication between upstream and downstream services in a service mesh fails, you can diagnose the cause manually with one or more of Consul’s built-in features, including [health check queries](/consul/docs/discovery/checks), [the UI topology view](/consul/docs/connect/observability/ui-visualization), and [agent telemetry metrics](/consul/docs/agent/telemetry#metrics-reference).
When communication between upstream and downstream services in a service mesh fails, you can diagnose the cause manually with one or more of Consul’s built-in features, including [health check queries](/consul/docs/services/usage/checks), [the UI topology view](/consul/docs/connect/observability/ui-visualization), and [agent telemetry metrics](/consul/docs/agent/telemetry#metrics-reference).
The `consul troubleshoot` command performs several checks in sequence that enable you to discover issues that impede service-to-service communication. The process systematically queries the [Envoy administration interface API](https://www.envoyproxy.io/docs/envoy/latest/operations/admin) and the Consul API to determine the cause of the communication failure.
@ -100,7 +100,7 @@ In the example output, troubleshooting upstream communication reveals that the `
! No healthy endpoints for cluster "backend2.default.dc1.internal.e08fa6d6-e91e-dfe0-f6e1-ba097a828e31.consul" for upstream "backend" found
```
The output from the troubleshooting process identifies service instances according to their [Consul DNS address](/consul/docs/discovery/dns#standard-lookup). Use the DNS information for failing services to diagnose the specific issues affecting the service instance.
The output from the troubleshooting process identifies service instances according to their [Consul DNS address](/consul/docs/services/discovery/dns-static-lookups#standard-lookup). Use the DNS information for failing services to diagnose the specific issues affecting the service instance.
For more information, refer to the [`consul troubleshoot` CLI documentation](/consul/commands/troubleshoot).

6
website/content/docs/upgrading/upgrade-specific.mdx
View File

@ -990,11 +990,9 @@ config files loaded by Consul, even when using the
[`-config-file`](/consul/docs/agent/config/cli-flags#_config_file) argument to specify a
file directly.
#### Service Definition Parameter Case changed
#### Use Snake Case for Service Definition Parameters
All config file formats now require snake_case fields, so all CamelCased parameter
names should be changed before upgrading.
See [Service Definition Parameter Case](/consul/docs/discovery/services#service-definition-parameter-case) documentation for details.
Snake case, which is a convention that uses underscores between words in a configuration key, is required for all configuration file formats. Change any camel cased parameter to snake case equivalents before upgrading.
#### Deprecated Options Have Been Removed

70
website/data/docs-nav-data.json
View File

@ -303,19 +303,70 @@
"divider": true
},
{
"title": "Service Discovery",
"title": "Services",
"routes": [
{
"title": "Register Services - Service Definitions",
"path": "discovery/services"
"title": "Services Overview",
"path": "services/services"
},
{
"title": "Find Services - DNS Interface",
"path": "discovery/dns"
"title": "Define and Register",
"routes": [
{
"title": "Define Services",
"path": "services/usage/define-services"
},
{
"title": "Define Health Checks",
"path": "services/usage/checks"
},
{
"title": "Register Services and Health Checks",
"path": "services/usage/register-services-checks"
}
]
},
{
"title": "Monitor Services - Check Definitions",
"path": "discovery/checks"
"title": "Service Discovery",
"routes": [
{
"title": "DNS Usage Overview",
"path": "services/discovery/dns-overview"
},
{
"title": "Configure Consul DNS Behavior",
"path": "services/discovery/dns-configuration"
},
{
"title": "Perform Static DNS Lookups",
"path": "services/discovery/dns-static-lookups"
},
{
"title": "Enable Dynamic DNS Lookups",
"path": "services/discovery/dns-dynamic-lookups"
}
]
},
{
"title": "Configuration",
"routes": [
{
"title": "Services Configuration Overview",
"path": "services/configuration/services-configuration-overview"
},
{
"title": "Services Configuration Reference",
"path": "services/configuration/services-configuration-reference"
},
{
"title": "Health Checks Configuration Reference",
"path": "services/configuration/checks-configuration-reference"
},
{
"title": "Service Defaults Configuration Reference",
"href": "connect/config-entries/service-defaults"
}
]
}
]
},
@ -459,11 +510,6 @@
{
"title": "Proxy Integration",
"path": "connect/proxies/integrate"
},
{
"title": "Managed (Deprecated)",
"path": "connect/proxies/managed-deprecated",
"hidden": true
}
]
},