From 584ee9f10ef5c428c61c0b762e39c901a563809f Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 20 Aug 2021 13:41:03 -0700 Subject: [PATCH 1/8] testing markdown table format for ref docs --- website/content/docs/discovery/services.mdx | 128 ++++++++++++-------- 1 file changed, 80 insertions(+), 48 deletions(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 2f627ab32..35df237d2 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -30,8 +30,7 @@ Consul. Check definitions can be updated by sending a `SIGHUP` to the agent. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service) using the [HTTP API](/api). -A service definition is a configuration that looks like the following. This -example shows all possible fields, but note that only a few are required. +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. ```json { @@ -109,6 +108,41 @@ example shows all possible fields, but note that only a few are required. } ``` +The following table describes the available parameters for service definitions. + +### `service` + +This is the root-level parameter that definex the service. You can specify the parameters to configure the service. + +| Parameter | Description | Default | Required | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------- | +| `id` | String value that specifies the service ID.

If not specified, the value of the `name` field will be used.

Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional | +| `name` | Specifies the name of the service.

The value for this parameter is used as the ID if the `id` parameter is not specified.

We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required | +| `tags` | List of string values that can be used to add service-level labels.

For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions.

We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.

Tag values are opaque to Consul.

| None | Optional | +| `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. | IP address of the agent node | Optional | +| `meta` | Object that defines a map of the max 64 key/value pairs.

The meta object has the same limitations as the node meta object in the node definition.

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.

See [Adding Meta Data](#adding-meta-data) for supported parameters.

| 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` | MISSING DESCRIPTION | None | Optional | +| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled.

If set to `true`, the then external agents can update this service in the catalog and modify the tags.

Subsequent local sync operations by this agent will ignore the updated tags.

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.

Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node.

See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.

| 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.

This parameter is deprecated. Use `proxy.destination_service` instead.

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 (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 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.

Keys can only have 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. | None | Optional | + + -Services may also contain a `token` field to provide an ACL token. This token is -used for any interaction with the catalog for the service, including -[anti-entropy syncs](/docs/internals/anti-entropy) and deregistration. +### 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](/docs/internals/anti-entropy) and deregistration. Services registered in Consul clusters where both [Consul Namespaces](/docs/enterprise/namespaces) and the ACL system are enabled can be registered to specific namespaces that are associated with -ACL tokens scoped to that namespace. Services registered with a service definition +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` field, in addition to the `token` field, must be -included in the service definition for the service to be registered to the +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. + -### Checks +### Health Checks -A service can have an associated health check. This is a powerful feature as -it allows a web balancer to gracefully remove failing nodes, a database -to replace a failed secondary, etc. The health check is strongly integrated in -the DNS interface as well. If a service is failing its health check or a -node has any failing system-level check, the DNS interface will omit that +You can add health checks to your service definition. Health checks perform severaly 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 funcationality is strongly integrated in the DNS interface, as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that node from any service query. -There are several check types that have differing required options as -[documented here](/docs/agent/checks). The check name is automatically -generated as `service:`. If there are multiple service checks +The health check name is automatically generated as `service:`. If there are multiple service checks registered, the ID will be generated as `service::` where `` is an incrementing number starting from `1`. --> **Note:** There is more information about [checks here](/docs/agent/checks). +Consul includes several check types with different options. Refer to the [health checks documentation](/docs/agent/checks) for details. ### Proxy @@ -202,17 +232,17 @@ for the available configuration options. ### Connect -The `kind` field is used to optionally identify the service as a [Connect -proxy](/docs/connect/proxies) instance. This value may be "connect-proxy" for -[Connect-capable](/docs/connect) proxies representing another service, -"mesh-gateway" for instances of a [mesh gateway](/docs/connect/mesh-gateway), -"terminating-gateway" for instances of a [terminating gateway](/docs/connect/terminating-gateway), -or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/ingress-gateway). -For typical non-proxy instances the `kind` field must be omitted. The `proxy` field -is also required for Connect proxy registrations and is only valid if `kind` is -`connect-proxy`. The only required `proxy` field for a `connect-proxy` is `destination_service_name`. -For more detail please see [complete proxy configuration -example](/docs/connect/registration/service-registration#complete-configuration-example) +The `kind` parameter determines role of the service. +For typical non-proxy instances, the `kind` field must be omitted. +Services can be configured to perform several roles. +Refer to the [Configuration Entries](/docs/connect/config-entries) documentation for Consul Connect for information about other registration types. + +In the service definition example described above, the `kind` property is set to `connect-proxy`, which registers the service as a 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](/docs/connect/registration/service-registration) documenatation for details about this type. + +The only required `proxy` field for a `connect-proxy` is `destination_service_name`. +Refer to the [complete proxy configuration example](/docs/connect/registration/service-registration#complete-configuration-example) for additional information. -> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was specified using `proxy_destination` at the top level. This will continue to work @@ -235,18 +265,21 @@ and the `connect.proxy` field will be removed in a future major release. ### DNS SRV Weights -The `weights` field is an optional field to specify the weight of a service in -DNS SRV responses. If this field is not specified, its default value is: -`"weights": {"passing": 1, "warning": 1}`. When 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 agent DNS configuration or `?passing` is used via the API. +You can configure how the service responds to DNS SRV requests by specifying a set of states/weights in the `weights` field. -When DNS SRV requests are made, the response will include the weights specified -given the state of the service. This allows some instances to be given higher -weight if they have more capacity, and optionally allows reducing load on -services with checks in `warning` status by giving passing instances a higher -weight. +#### `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:
`"passing" : 1`
`"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 @@ -277,12 +310,12 @@ deprecated and has been removed as of Consul 1.1. ### Tagged Addresses -Tagged addresses are additional addresses which may be defined for a node or +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 syntax for defining a tagged address is as follows. +The following example is describes the syntax for defining a tagged address. @@ -326,9 +359,9 @@ the same Consul data center. ##### Supported 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. +- `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. @@ -528,7 +561,6 @@ service { - ## Multiple Service Definitions Multiple services definitions can be provided at once when registering services From 1bb21ab24e356e94492b0ee1bb008358f70feb10 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Mon, 23 Aug 2021 11:09:34 -0700 Subject: [PATCH 2/8] Update website/content/docs/discovery/services.mdx Co-authored-by: Geoffrey Grosenbach <26+topfunky@users.noreply.github.com> --- website/content/docs/discovery/services.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 35df237d2..919e752ae 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -213,7 +213,7 @@ deprecated and has been removed as of Consul 1.1. --> ### Health Checks -You can add health checks to your service definition. Health checks perform severaly safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database +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 funcationality is strongly integrated in the DNS interface, as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that node from any service query. From 7fce25fdbfd153bb3d0ca7819e73f8b4ba75f9f2 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Mon, 23 Aug 2021 11:09:43 -0700 Subject: [PATCH 3/8] Update website/content/docs/discovery/services.mdx Co-authored-by: Geoffrey Grosenbach <26+topfunky@users.noreply.github.com> --- website/content/docs/discovery/services.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 919e752ae..c1d6a6986 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -112,7 +112,7 @@ The following table describes the available parameters for service definitions. ### `service` -This is the root-level parameter that definex the service. You can specify the parameters to configure the service. +This is the root-level parameter that defines the service. You can specify the parameters to configure the service. | Parameter | Description | Default | Required | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------- | From 4f85b1082b2800ce0e84ad0d2dc5517f944c9660 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 24 Aug 2021 09:57:48 -0700 Subject: [PATCH 4/8] fixed typos, finished applying tables, minor editing --- website/content/docs/discovery/services.mdx | 131 +++++++------------- 1 file changed, 46 insertions(+), 85 deletions(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 35df237d2..ce3f225f7 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -15,19 +15,20 @@ description: >- 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 is considered to be application level if it is -associated with a service. A service is defined in a configuration file +a health check. A health check associated with a service is considered to be an +application-level check. A service is defined in a configuration file or added at runtime over the HTTP interface. -Use the [Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery?utm_source=consul.io&utm_medium=docs) to get hands-on experience registering a simple service with a health check on your local machine. +Complete the [Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery?utm_source=consul.io&utm_medium=docs) to get hands-on experience registering a simple service with a health check on your local machine. ## Service Definition -To configure a service, either provide the service definition as a -`-config-file` option to the agent or place it inside the `-config-dir` of the -agent. The file must end in the `.json` or `.hcl` extension to be loaded by -Consul. Check definitions can be updated by sending a `SIGHUP` to the agent. -Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service) +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. +Save the service definition as a `.json` or `.hcl` file. so that it can be loaded by Consul. +Send a `SIGHUP` to the running agent to check for new service definitions or to +update existing services. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service) using the [HTTP API](/api). 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. @@ -112,64 +113,35 @@ The following table describes the available parameters for service definitions. ### `service` -This is the root-level parameter that definex the service. You can specify the parameters to configure the 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.

If not specified, the value of the `name` field will be used.

Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional | -| `name` | Specifies the name of the service.

The value for this parameter is used as the ID if the `id` parameter is not specified.

We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required | -| `tags` | List of string values that can be used to add service-level labels.

For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions.

We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.

Tag values are opaque to Consul.

| None | Optional | -| `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. | IP address of the agent node | Optional | -| `meta` | Object that defines a map of the max 64 key/value pairs.

The meta object has the same limitations as the node meta object in the node definition.

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.

See [Adding Meta Data](#adding-meta-data) for supported parameters.

| 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` | MISSING DESCRIPTION | None | Optional | -| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled.

If set to `true`, the then external agents can update this service in the catalog and modify the tags.

Subsequent local sync operations by this agent will ignore the updated tags.

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.

Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node.

See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.

| 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.

This parameter is deprecated. Use `proxy.destination_service` instead.

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 (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 | +| Parameter | Description | Default | Required | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ---------------------------- | +| `id` | String value that specifies the service ID.
If not specified, the value of the `name` field will be used.
Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional | +| `name` | Specifies the name of the service.
The value for this parameter is used as the ID if the `id` parameter is not specified.
We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required | +| `tags` | List of string values that can be used to add service-level labels.
For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions.
We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.
Tag values are opaque to Consul.
| None | Optional | +| `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. | IP address of the agent node | Optional | +| `meta` | Object that defines a map of the max 64 key/value pairs.
The meta object has the same limitations as the node meta object in the node definition.
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.
See [Adding Meta Data](#adding-meta-data) for supported parameters.
| 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.
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.
If set to `true`, the then external agents can update this service in the catalog and modify the tags.
Subsequent local sync operations by this agent will ignore the updated tags.
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.
Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node.
See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.
| 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.
This parameter is deprecated. Use `proxy.destination_service` instead.
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 (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 defines a map of max 64 key/value pairs. You can specify the following parameters to define meta data for the service. +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.

Keys can only have 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. | None | Optional | - - +| Parameter | Description | Default | Required | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- | +| `KEY` | String value that adds semantic metadata to the service.
Keys can only have 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. | None | Optional | ### Security Configurations @@ -213,7 +185,7 @@ deprecated and has been removed as of Consul 1.1. --> ### Health Checks -You can add health checks to your service definition. Health checks perform severaly safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database +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 funcationality is strongly integrated in the DNS interface, as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that node from any service query. @@ -315,7 +287,7 @@ service. Tagged addresses can be used by remote agents and services as alternati addresses for communicating with the given node or service. Multiple tagged addresses may be configured on a node or service. -The following example is describes the syntax for defining a tagged address. +The following example describes the syntax for defining a tagged address. @@ -349,15 +321,15 @@ service { -Consul supports several tagged address types. The various types and their use -cases are detailed below. +The following table provides an overview of the various tagged address types supported by Consul. -#### LAN +| 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`
`lan_ipv4`
`lan_ipv6` | +| Virtual | Virtual tagged addresses are logical address types that can be configured on [Connect](/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`
`wan_ipv4`
`wan_ipv6` | -LAN addresses are intended to be directly accessible only from services within -the same Consul data center. - -##### Supported tags +#### 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. @@ -420,27 +392,21 @@ service { -#### Virtual +#### Virtual tags -Virtual tagged addresses are logical address types which can be configured on -[Connect](/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. Connections to the virtual address are load balanced across -available instances of a service, provided the following conditions are satisfied: +Connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied: 1. [Transparent proxy](/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](/docs/connect/config-entries/service-defaults#dialeddirectly). --> **Note**: Virtual addresses are not required to be routable IPs within the +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. -##### Supported tags - Use the following address tag to specify the logical address at which the service can be reached by other services in the mesh. @@ -487,12 +453,7 @@ service { -#### 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. - -##### Supported tags +#### 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. From 832a5e4067485af37b393eb13c7b054d602f4c1d Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 24 Aug 2021 11:15:33 -0700 Subject: [PATCH 5/8] fixed more typos, applied additional tables, additional edits --- website/content/docs/discovery/services.mdx | 48 ++++++++++----------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index ce3f225f7..d68af4b2c 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -16,8 +16,8 @@ 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. A service is defined in a configuration file -or added at runtime over the HTTP interface. +application-level check. Define services in a configuration file or add it at +runtime using the HTTP interface. Complete the [Getting Started tutorials](https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery?utm_source=consul.io&utm_medium=docs) to get hands-on experience registering a simple service with a health check on your local machine. @@ -26,7 +26,8 @@ Complete the [Getting Started tutorials](https://learn.hashicorp.com/tutorials/c 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. -Save the service definition as a `.json` or `.hcl` file. so that it can be loaded by Consul. +Consul can load service definitions saved as `.json` or `.hcl` files. + Send a `SIGHUP` to the running agent to check for new service definitions or to update existing services. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service) using the [HTTP API](/api). @@ -128,8 +129,8 @@ This is the root-level parameter that defines the service. You can specify the p | `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled.
If set to `true`, the then external agents can update this service in the catalog and modify the tags.
Subsequent local sync operations by this agent will ignore the updated tags.
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.
Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node.
See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.
| 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.
This parameter is deprecated. Use `proxy.destination_service` instead.
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 | +| `proxy_destination` | String value that specifies the _name_ of the destination service that the service currently being configured proxies to.
This parameter is deprecated. Use `proxy.destination_service` instead.
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 (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 | @@ -204,36 +205,31 @@ for the available configuration options. ### Connect -The `kind` parameter determines role of the service. -For typical non-proxy instances, the `kind` field must be omitted. -Services can be configured to perform several roles. +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. Refer to the [Configuration Entries](/docs/connect/config-entries) documentation for Consul Connect for information about other registration types. -In the service definition example described above, the `kind` property is set to `connect-proxy`, which registers the service as a proxy. +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](/docs/connect/registration/service-registration) documenatation for details about this type. -The only required `proxy` field for a `connect-proxy` is `destination_service_name`. +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](/docs/connect/registration/service-registration#complete-configuration-example) for additional information. --> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was -specified using `proxy_destination` at the top level. This will continue to work -until at least 1.5.0 but it's highly recommended to switch to using -`proxy.destination_service_name`. +The `connect` field can be specified to configure [Connect](/docs/connect) for a service. This field is available in Consul 1.2.0 and later. The following parameters are available. -The `connect` field can be specified to configure -[Connect](/docs/connect) for a service. This field is available in -Consul 1.2.0 and later. The `native` value can be set to true to advertise the -service as [Connect-native](/docs/connect/native). The `sidecar_service` -field is an optional nested service definition its behavior and defaults are -described in [Sidecar Service -Registration](/docs/connect/registration/sidecar-service). If `native` is true, -it is an error to also specify a sidecar service registration. +| Parameter | Description | Default | Required | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------- | +| `native` | Boolean value that advertises the service as [Connect-native](/docs/connect/native).
If set to `true`, do not configure a `sidecar_service`. | `false` | Optional | +| `sidecar_service` | Object that defines a nested service definition.
Do not configure if `native` is set to `true`. | See [Sidecar Service Registration](/docs/connect/registration/sidecar-service) for default configurations. | Optional | --> **Deprecation Notice:** From version 1.2.0 to 1.3.0 during beta, Connect -supported "Managed" proxies which are specified with the `connect.proxy` field. -[Managed Proxies are deprecated](/docs/connect/proxies/managed-deprecated) -and the `connect.proxy` field will be removed in a future major release. +#### 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.
Use `proxy.destination_service_name` instead. | +| `connect.proxy` | Specified "managed" proxies, [which have been deprecated](/docs/connect/proxies/managed-deprecated). | 1.2.0 (beta) to 1.3.0 (beta) | Deprecated. | ### DNS SRV Weights From 7b4a7bcc3892a45b51d3f0a9b79b8f51d4e5ce9d Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 24 Aug 2021 12:05:01 -0700 Subject: [PATCH 6/8] removed merge conflict chars --- website/content/docs/discovery/services.mdx | 37 ++++++++++----------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 76d8010fa..43224d729 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -116,26 +116,25 @@ The following table describes the available parameters for service definitions. This is the root-level parameter that defines the service. You can specify the parameters to configure the service. -<<<<<<< HEAD -| Parameter | Description | Default | Required | +| Parameter | Description | Default | Required | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ---------------------------- | -| `id` | String value that specifies the service ID.
If not specified, the value of the `name` field will be used.
Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional | -| `name` | Specifies the name of the service.
The value for this parameter is used as the ID if the `id` parameter is not specified.
We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required | -| `tags` | List of string values that can be used to add service-level labels.
For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions.
We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.
Tag values are opaque to Consul.
| None | Optional | -| `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. | IP address of the agent node | Optional | -| `meta` | Object that defines a map of the max 64 key/value pairs.
The meta object has the same limitations as the node meta object in the node definition.
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.
See [Adding Meta Data](#adding-meta-data) for supported parameters.
| 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.
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.
If set to `true`, the then external agents can update this service in the catalog and modify the tags.
Subsequent local sync operations by this agent will ignore the updated tags.
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.
Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node.
See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.
| 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.
This parameter is deprecated. Use `proxy.destination_service` instead.
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 (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 | +| `id` | String value that specifies the service ID.
If not specified, the value of the `name` field will be used.
Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional | +| `name` | Specifies the name of the service.
The value for this parameter is used as the ID if the `id` parameter is not specified.
We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required | +| `tags` | List of string values that can be used to add service-level labels.
For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions.
We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.
Tag values are opaque to Consul.
| None | Optional | +| `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. | IP address of the agent node | Optional | +| `meta` | Object that defines a map of the max 64 key/value pairs.
The meta object has the same limitations as the node meta object in the node definition.
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.
See [Adding Meta Data](#adding-meta-data) for supported parameters.
| 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.
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.
If set to `true`, the then external agents can update this service in the catalog and modify the tags.
Subsequent local sync operations by this agent will ignore the updated tags.
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.
Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node.
See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.
| 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.
This parameter is deprecated. Use `proxy.destination_service` instead.
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 (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 From 09679aee3ad7ed28080f3e907d98fe06e3c01d0d Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 30 Aug 2021 14:49:32 -0700 Subject: [PATCH 7/8] applying @blake 's feedback --- website/content/docs/discovery/services.mdx | 52 ++++++++++++--------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 43224d729..d28d8cf84 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -28,7 +28,7 @@ either specify the configuration file using the `-config-file` option, or specif 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 to check for new service definitions or to +Send a `SIGHUP` to the running agent or use [`consul reload`](/commands/reload) to check for new service definitions or to update existing services. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service) using the [HTTP API](/api). @@ -116,25 +116,25 @@ The following table describes the available parameters for service definitions. 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.
If not specified, the value of the `name` field will be used.
Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services. | Value of the `name` parameter | Optional | -| `name` | Specifies the name of the service.
The value for this parameter is used as the ID if the `id` parameter is not specified.
We recommend using valid DNS labels for service definition names for compatibility wit external DNSs. | None | Required | -| `tags` | List of string values that can be used to add service-level labels.
For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions.
We recommend using valid DNS labels for service definition IDs for compatibility wit external DNSs.
Tag values are opaque to Consul.
| None | Optional | -| `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. | IP address of the agent node | Optional | -| `meta` | Object that defines a map of the max 64 key/value pairs.
The meta object has the same limitations as the node meta object in the node definition.
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.
See [Adding Meta Data](#adding-meta-data) for supported parameters.
| 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.
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.
If set to `true`, the then external agents can update this service in the catalog and modify the tags.
Subsequent local sync operations by this agent will ignore the updated tags.
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.
Updating the tags for services registered on one node is indepenedent from the same service (by name) registered on another node.
See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.
| 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.
This parameter is deprecated. Use `proxy.destination_service` instead.
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 (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 | +| Parameter | Description | Default | Required | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------- | +| `id` | String value that specifies the service ID.

If not specified, the value of the `name` field will be used.

Services must have unique IDs per node, so you should specify unique values if the default `name` will conflict with other services.

| Value of the `name` parameter | Optional | +| `name` | Specifies the name of the service.
The value for this parameter is used as the ID if the `id` parameter is not specified.
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.
For example, you can define tags that distinguish between `primary` and `secondary` nodes or service versions.
We recommend using valid DNS labels for service definition IDs for compatibility with external DNSs.
Tag values are opaque to Consul.
| None | Optional | +| `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. | IP address of the agent node | Optional | +| `meta` | Object that defines a map of the max 64 key/value pairs.
The meta object has the same limitations as the node meta object in the node definition.
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.
See [Adding Meta Data](#adding-meta-data) for supported parameters.
| 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.
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.
If set to `true`, then external agents can update this service in the catalog and modify the tags.
Subsequent local sync operations by this agent will ignore the updated tags.
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.
Updating the tags for services registered on one node is independent from the same service (by name) registered on another node.
See [anti-entropy syncs](/docs/internals/anti-entropy) for additional information.
| 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.
This parameter is deprecated. Use `proxy.destination_service` instead.
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 @@ -159,7 +159,7 @@ 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 funcationality is strongly integrated in the DNS interface, as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that +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:`. If there are multiple service checks @@ -178,7 +178,13 @@ 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. -Refer to the [Configuration Entries](/docs/connect/config-entries) documentation for Consul Connect for information about other registration types. + +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](/docs/connect/config-entries/ingress-gateway) +- `mesh-gateway`: Defines the configuration for a [mesh gateway](/docs/connect/gateways/mesh-gateway#mesh-gateway-configuration) +- `terminating-gateway`: Defines the configuration for a [terminating gateway](/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`. @@ -194,6 +200,8 @@ The `connect` field can be specified to configure [Connect](/docs/connect) for a | `native` | Boolean value that advertises the service as [Connect-native](/docs/connect/native).
If set to `true`, do not configure a `sidecar_service`. | `false` | Optional | | `sidecar_service` | Object that defines a nested service definition.
Do not configure if `native` is set to `true`. | See [Sidecar Service Registration](/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](/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. From 51b45c34de02bbd6b03fd5fe0906525dbc09f941 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 30 Aug 2021 14:50:55 -0700 Subject: [PATCH 8/8] missed typo --- website/content/docs/discovery/services.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index d28d8cf84..92ed20576 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -188,7 +188,7 @@ The following roles are supported for service entries: 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](/docs/connect/registration/service-registration) documenatation for details about this type. +Refer to the [Proxy Service Registration](/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](/docs/connect/registration/service-registration#complete-configuration-example) for additional information.