From 7f823e040f0d82c70d514f99fa69a4c656c24ad8 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 24 Aug 2021 11:15:33 -0700 Subject: [PATCH] fixed more typos, applied additional tables, additional edits --- website/content/docs/discovery/services.mdx | 52 ++++++++++----------- 1 file changed, 24 insertions(+), 28 deletions(-) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index ce3f225f74..d68af4b2cf 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 `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. - --> **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. +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. + +| 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 | + +#### 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