diff --git a/website/content/api-docs/agent/service.mdx b/website/content/api-docs/agent/service.mdx index 1a5122e41018..cf821c9ddf13 100644 --- a/website/content/api-docs/agent/service.mdx +++ b/website/content/api-docs/agent/service.mdx @@ -639,7 +639,7 @@ The `/agent/service/register` endpoint supports camel case and _snake case_ for - `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a service mesh proxy instance. This is only valid if `Kind` defines a proxy or gateway. - See the [Proxy documentation](/consul/docs/connect/registration/service-registration) + Refer to the [Service mesh proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference) for full details. - `Connect` `(Connect: nil)` - Specifies the @@ -698,8 +698,8 @@ For the `Connect` field, the parameters are: Managed proxies (which have been deprecated since Consul v1.3.0) have been [removed](/consul/docs/connect/proxies) since v1.6.0. - `SidecarService` `(ServiceDefinition: nil)` - Specifies an optional nested - service definition to register. For more information see - [Sidecar Service Registration](/consul/docs/connect/registration/sidecar-service). + service definition to register. Refer to + [Deploy sidecar services](/consul/docs/connect/proxies/deploy-sidecar-services) for additional information. ### Sample Payload diff --git a/website/content/api-docs/discovery-chain.mdx b/website/content/api-docs/discovery-chain.mdx index ba222116ec65..bef03ac12ec2 100644 --- a/website/content/api-docs/discovery-chain.mdx +++ b/website/content/api-docs/discovery-chain.mdx @@ -57,10 +57,8 @@ The table below shows this endpoint's support for - `compile-dc` `(string: "")` - Specifies the datacenter to use as the basis of compilation. This will default to the datacenter of the agent being queried. - This value comes from an [upstream - configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) - [`datacenter`](/consul/docs/connect/registration/service-registration#datacenter) - parameter. + This value comes from the `datacenter` parameter in an [upstream + configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference). - `ns` `(string: "")` - Specifies the source namespace you use as the basis of compilation. You can also [specify the namespace through other methods](#methods-to-specify-namespace). @@ -71,11 +69,8 @@ The table below shows this endpoint's support for timeout](/consul/docs/connect/config-entries/service-resolver#connecttimeout) for any service resolved in the compiled chain. - This value comes from the `connect_timeout_ms` key in an [upstream - configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) - opaque - [`config`](/consul/docs/connect/registration/service-registration#config-1) - parameter. + This value comes from the `connect_timeout_ms` key in the opaque `config` field of the [upstream + configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference). - `OverrideProtocol` `(string: "")` - Overrides the final [protocol](/consul/docs/connect/config-entries/service-defaults#protocol) used in @@ -86,23 +81,17 @@ The table below shows this endpoint's support for would be L7 and TCP is passed here the chain will not include Routers or Splitters. - This value comes from the `protocol` key in an [upstream - configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) - opaque - [`config`](/consul/docs/connect/registration/service-registration#config-1) - parameter. + This value comes from the `protocol` key in an opaque `config` field of the [upstream + configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference). - `OverrideMeshGateway` `(MeshGatewayConfig: )` - Overrides the final [mesh gateway configuration](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) for this any service resolved in the compiled chain. - This value comes from either the [proxy - configuration](/consul/docs/connect/registration/service-registration#complete-configuration-example) - [`mesh_gateway`](/consul/docs/connect/registration/service-registration#mesh_gateway) - parameter or an [upstream - configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) - [`mesh_gateway`](/consul/docs/connect/registration/service-registration#mesh_gateway-1) - parameter. If both are present the value defined on the upstream is used. + This value comes from the `mesh_gateway` parameter in either the [proxy + configuration](/consul/docs/connect/proxies/proxy-config-reference#proxy-parameters) or [upstream + configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) + If both parameters are configured, Consul uses the value defined on the upstream. - `Mode` `(string: "")` - One of `none`, `local`, or `remote`. diff --git a/website/content/commands/connect/envoy.mdx b/website/content/commands/connect/envoy.mdx index bb2cc5d77e81..aa2de2e35bf8 100644 --- a/website/content/commands/connect/envoy.mdx +++ b/website/content/commands/connect/envoy.mdx @@ -36,7 +36,7 @@ Usage: `consul connect envoy [options] [-- pass-through options]` #### Envoy Options for both Sidecars and Gateways -- `-proxy-id` - The [proxy service](/consul/docs/connect/registration/service-registration) ID. +- `-proxy-id` - The [proxy service](/consul/docs/connect/proxies/proxy-config-reference) ID. This service ID must already be registered with the local agent unless a gateway is being registered with the `-register` flag. As of Consul 1.8.0, this can also be specified via the `CONNECT_PROXY_ID` environment variable. @@ -133,7 +133,7 @@ compatibility with Envoy and prevent potential issues. Default is `false`. - `-sidecar-for` - The _ID_ (not name if they differ) of the service instance this proxy will represent. The target service doesn't need to exist on the local agent yet but a [sidecar proxy - registration](/consul/docs/connect/registration/service-registration) with + registration](/consul/docs/proxies/deploy-sidecar-services) with `proxy.destination_service_id` equal to the passed value must be present. If multiple proxy registrations targeting the same local service instance are present the command will error and `-proxy-id` should be used instead. @@ -225,9 +225,9 @@ proxy configuration needed. ## Examples -Assume a local service instance is registered on the local agent with a +In the following examples, a local service instance is registered on the local agent with a sidecar proxy (using the [sidecar service -registration](/consul/docs/connect/registration/service-registration) helper) as below. +registration](/consul/docs/connect/proxies/deploy-sidecar-services) helper): ```hcl service { diff --git a/website/content/commands/connect/proxy.mdx b/website/content/commands/connect/proxy.mdx index db3192dbee4f..0a4571df5f9e 100644 --- a/website/content/commands/connect/proxy.mdx +++ b/website/content/commands/connect/proxy.mdx @@ -24,14 +24,14 @@ Usage: `consul connect proxy [options]` - `-sidecar-for` - The _ID_ (not name if they differ) of the service instance this proxy will represent. The target service doesn't need to exist on the local agent yet but a [sidecar proxy - registration](/consul/docs/connect/registration/service-registration) with + registration](/consul/docs/connect/proxies/deploy-sidecar-services) with `proxy.destination_service_id` equal to the passed value must be present. If multiple proxy registrations targeting the same local service instance are present the command will error and `-proxy-id` should be used instead. This can also be specified via the `CONNECT_SIDECAR_FOR` environment variable. - `-proxy-id` - The [proxy - service](/consul/docs/connect/registration/service-registration) ID on the + service](/consul/docs/connect/proxies/proxy-config-reference) ID on the local agent. This must already be present on the local agent. This option can also be specified via the `CONNECT_PROXY_ID` environment variable. diff --git a/website/content/commands/connect/redirect-traffic.mdx b/website/content/commands/connect/redirect-traffic.mdx index 44decfef4071..af59baee56b7 100644 --- a/website/content/commands/connect/redirect-traffic.mdx +++ b/website/content/commands/connect/redirect-traffic.mdx @@ -38,7 +38,7 @@ Usage: `consul connect redirect-traffic [options]` - `-consul-dns-port` - The port of the Consul DNS resolver. If provided, DNS queries will be redirected to the provided IP address for name resolution. -- `-proxy-id` - The [proxy service](/consul/docs/connect/registration/service-registration) ID. +- `-proxy-id` - The [proxy service](/consul/docs/connect/proxies/proxy-config-reference) ID. This service ID must already be registered with the local agent. - `-proxy-inbound-port` - The inbound port that the proxy is listening on. diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index a2ca9083b89a..03c8b5ec7cee 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -637,16 +637,16 @@ Refer to the [formatting specification](https://golang.org/pkg/time/#ParseDurati - `server` ((#server_rpc_port)) - Server RPC address. Default 8300. TCP only. - `sidecar_min_port` ((#sidecar_min_port)) - Inclusive minimum port number - to use for automatically assigned [sidecar service registrations](/consul/docs/connect/registration/sidecar-service). + to use for automatically assigned [sidecar service registrations](/consul/docs/connect/proxies/deploy-sidecar-services). Default 21000. Set to `0` to disable automatic port assignment. - `sidecar_max_port` ((#sidecar_max_port)) - Inclusive maximum port number - to use for automatically assigned [sidecar service registrations](/consul/docs/connect/registration/sidecar-service). + to use for automatically assigned [sidecar service registrations](/consul/docs/connect/proxies/deploy-sidecar-services). Default 21255. Set to `0` to disable automatic port assignment. - `expose_min_port` ((#expose_min_port)) - Inclusive minimum port number - to use for automatically assigned [exposed check listeners](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference). + to use for automatically assigned [exposed check listeners](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference). Default 21500. Set to `0` to disable automatic port assignment. - `expose_max_port` ((#expose_max_port)) - Inclusive maximum port number - to use for automatically assigned [exposed check listeners](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference). + to use for automatically assigned [exposed check listeners](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference). Default 21755. Set to `0` to disable automatic port assignment. - `primary_datacenter` - This designates the datacenter diff --git a/website/content/docs/connect/cluster-peering/tech-specs.mdx b/website/content/docs/connect/cluster-peering/tech-specs.mdx index 8fe2794416b3..36c7dc9d9130 100644 --- a/website/content/docs/connect/cluster-peering/tech-specs.mdx +++ b/website/content/docs/connect/cluster-peering/tech-specs.mdx @@ -64,7 +64,7 @@ Refer to [mesh gateway modes](/consul/docs/connect/gateways/mesh-gateway#modes) 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/define-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. +- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams`](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) documentation for details. - The `proxy.upstreams.destination_name` parameter is always required. - The `proxy.upstreams.destination_peer` parameter must be configured to enable cross-cluster traffic. - The `proxy.upstream/destination_namespace` configuration is only necessary if the destination service is in a non-default namespace. diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index 05e5de30f7e8..015ad6f317d6 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -330,7 +330,7 @@ Specifies an arbitrary map of configuration values used by service mesh proxies. #### Values - Default: None -- Data type: Map of +- Data type: Map ### `EnvoyExtensions` @@ -339,7 +339,7 @@ Specifies a list of extensions that modify Envoy proxy configurations. Refer to #### Values - Default: None -- Data type: Map of containing the following fields: +- Data type: List of maps containing the following fields: - `Name` - `Required` - `Arguments` @@ -371,7 +371,7 @@ Specifies a mode for how proxies direct inbound and outbound traffic. You can sp ### `TransparentProxy` -Contains configurations for proxies that are running in transparent proxy mode. Refer to [Transparent proxy mode](/consul/docs/k8s/connect/transparent-proxy) for additional information. +Contains configurations for proxies that are running in transparent proxy mode. This mode enables permissive mTLS for Consul so that you can use your Kubernetes cluster's DNS service instead of Consul DNS. Refer to [Transparent proxy mode](/consul/docs/k8s/connect/transparent-proxy) for additional information. #### Values @@ -384,8 +384,8 @@ The following table describes how to configure values in the `TransparentProxy` | Parameter | Description | Data type | Default | | --- | --- | --- | --- | -| `OutboundListenerPort` | Specifies the port that the proxy listens on for outbound traffic. Outbound application traffic must be captured and redirected to this port. | Integer | `15001` | -| `DialedDirectly` | Determines whether other proxies in transparent mode can directly dial this proxy instance's IP address. Proxies in transparent mode commonly dial upstreams at the [`virtual`](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual) tagged address, which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader. | Boolean | `false` | +| `OutboundListenerPort` | Specifies the port that the proxy listens on for outbound traffic. Outbound application traffic must be captured and redirected to this port. | Integer | `15001` | +| `DialedDirectly` | Determines whether other proxies in transparent mode can directly dial this proxy instance's IP address. Proxies in transparent mode commonly dial upstreams at the [`virtual` tagged address](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual), which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader. | Boolean | `false` | ### `MutualTLSMode` @@ -431,14 +431,14 @@ Example use-cases include exposing the `/metrics` endpoint to a monitoring syste ### `Expose{}.Checks` -Exposes all HTTP and gRPC checks registered with the agent when set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. +Exposes all HTTP and gRPC checks registered with the agent when set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or the [Consul agent's `advertise_addr`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the [agent's `expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. -We recommend enabling the `Checks` configuration when a Consul client cannot reach registered services over localhost, such as when Consul agents run in their own pods in Kubernetes. +We recommend enabling the `Checks` configuration when a Consul client cannot reach registered services over localhost. #### Values - Default: `false` -- Data type: boolean +- Data type: Boolean ### `Expose{}.Paths[]` @@ -447,7 +447,7 @@ Specifies a list of configuration maps that define paths to expose through Envoy #### Values - Default: None -- Data type: List of maps. +- Data type: List of maps The following table describes the parameters for each map you can define in the list: @@ -496,7 +496,7 @@ The following table describes the parameters you can define in the `AccessLogs` -### apiVersion +### `apiVersion` Specifies the verion of the Consul API to use to apply the configuration entry. This must be set to `consul.hashicorp.com/v1alpha1`. @@ -571,7 +571,7 @@ Specifies a list of extensions that modify Envoy proxy configurations. Refer to #### Values - Default: None -- Data type: Map of containing the following fields: +- Data type: List of maps of containing the following fields: - `name` - `required` - `arguments` @@ -593,6 +593,7 @@ The following table describes how to configure values in the `EnvoyExtensions` m Specifies a mode for how proxies direct inbound and outbound traffic. You can specify one of the following values: - `transparent`: In transparent mode, proxies capture and redirect inbound and outbound traffic. The mode does not enable traffic redirection, but directs Consul to configure Envoy as if traffic is already being redirected. + - `direct`: In this mode, the local application and other proxies must directly dial proxy listeners. #### Values @@ -602,7 +603,7 @@ Specifies a mode for how proxies direct inbound and outbound traffic. You can sp ### `spec.transparentProxy` -Contains configurations for proxies that are running in transparent proxy mode. Refer to [Transparent proxy mode](/consul/docs/k8s/connect/transparent-proxy) for additional information. +Contains configurations for proxies that are running in transparent proxy mode. This mode enables permissive mTLS for Consul so that you can use your Kubernetes cluster's DNS service instead of Consul DNS. Refer to [Transparent proxy mode](/consul/docs/k8s/connect/transparent-proxy) for additional information. #### Values @@ -615,8 +616,8 @@ The following table describes how to configure values in the `TransparentProxy` | Parameter | Description | Data type | Default | | --- | --- | --- | --- | -| `outboundListenerPort` | Specifies the port that the proxy listens on for outbound traffic. Outbound application traffic must be captured and redirected to this port. | Integer | `15001` | -| `dialedDirectly` | Determines whether other proxies in transparent mode can directly dial this proxy instance's IP address. Proxies in transparent mode commonly dial upstreams at the [`virtual`](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual) tagged address, which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader. | Boolean | `false` | +| `outboundListenerPort` | Specifies the port that the proxy listens on for outbound traffic. Outbound application traffic must be captured and redirected to this port. | Integer | `15001` | +| `dialedDirectly` | Determines whether other proxies in transparent mode can directly dial this proxy instance's IP address. Proxies in transparent mode commonly dial upstreams at the [`virtual` tagged address](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual), which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader. | Boolean | `false` | ### `spec.mutualTLSMode` @@ -662,14 +663,14 @@ Example use-cases include exposing the `/metrics` endpoint to a monitoring syste ### `spec.expose{}.checks` -Exposes all HTTP and gRPC checks registered with the agent when set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. +Exposes all HTTP and gRPC checks registered with the agent when set to `true`. Envoy exposes listeners for the checks and only accepts connections originating from localhost or the [Consul agent's `advertise_addr`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the [agent's `expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. We recommend enabling the `Checks` configuration when a Consul client cannot reach registered services over localhost, such as when Consul agents run in their own pods in Kubernetes. #### Values - Default: `false` -- Data type: boolean +- Data type: Boolean ### `spec.expose{}.paths[]` @@ -723,6 +724,7 @@ The following table describes the parameters you can define in the `accessLogs` | `jsonFormat` | Specifies a JSON-formatted string that represents the format for each emitted access log. You can use [Envoy command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to customize the emitted data. You can also nest data. You cannot set this field and the `textFormat` field concurrently. | String | [Default log format](/consul/docs/connect/observability/access-logs#default-log-format) | | `textFormat` | Specifies a text-formatted string that represents the format for each emitted access log. You can use [Envoy command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to customize the emitted data. You can also nest data. You cannot set this field and the `jsonFormat` field concurrently. | String | None | + @@ -750,7 +752,7 @@ Config { #### Consul Enterprise -For Consul Enterprise, you can only create the configuration entry in the `default` namespace. The namepace configuration applies to proxies in all namespaces. +When using multiple namespaces with Consul Enterprise, the only configuration entry that affects proxy defaults is the one in the `default` namespace. This configuration applies to proxies in all namespaces. ```hcl Kind = "proxy-defaults" @@ -778,7 +780,7 @@ spec: #### Consul Enterprise -For Consul Enterprise, you can only create the configuration entry in the `default` namespace. The namepace configuration applies to proxies in all namespaces. +When using multiple namespaces with Consul Enterprise, the only configuration entry that affects proxy defaults is the one in the `default` namespace. This configuration applies to proxies in all namespaces. ```yaml apiVersion: consul.hashicorp.com/v1alpha1 @@ -808,7 +810,7 @@ spec: ``` #### Consul Enterprise -For Consul Enterprise, you can only create the configuration entry in the `default` namespace. The namepace configuration applies to proxies in all namespaces. +When using multiple namespaces with Consul Enterprise, the only configuration entry that affects proxy defaults is the one in the `default` namespace. This configuration applies to proxies in all namespaces. ```json { @@ -875,7 +877,7 @@ spec: ### Access Logs -The following example enables access logs for all proxies. efer to [access logs](/consul/docs/connect/observability/access-logs) for more detailed examples. +The following example enables access logs for all proxies. Refer to [access logs](/consul/docs/connect/observability/access-logs) for more detailed examples. diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index 648271c684c9..df7141a87411 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -778,7 +778,7 @@ Specifies the TLS server name indication (SNI) when federating with an external ### `Expose` -Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to listen on localhost only. Applications that are not Consul service mesh-enabled can still contact an HTTP endpoint. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) for additional information and example configurations. +Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to listen on `localhost` only. Applications that are not Consul service mesh-enabled can still contact an HTTP endpoint. Refer to [Expose Paths Configuration Reference](/consul/docs/proxies/proxy-config-reference#expose-paths-configuration-reference) for additional information and example configurations. - Default: none - Data type: map @@ -1198,7 +1198,7 @@ Specifies the TLS server name indication (SNI) when federating with an external ### `spec.expose` -Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to listen on localhost only. Applications that are not Consul service mesh-enabled can still contact an HTTP endpoint. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) for additional information and example configurations. +Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to listen on `localhost` only. Applications that are not Consul service mesh-enabled can still contact an HTTP endpoint. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference) for additional information and example configurations. #### Values @@ -2053,7 +2053,7 @@ represents a location outside the Consul cluster. Services can dial destinations name: 'Expose', type: 'ExposeConfig: ', description: `Controls the default - [expose path configuration](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) + [expose path configuration](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference) for Envoy. Added in v1.6.2.

Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing non-mesh-enabled applications to contact an HTTP endpoint. diff --git a/website/content/docs/connect/configuration.mdx b/website/content/docs/connect/configuration.mdx index 5edf02886ba1..0ce7230ab2ef 100644 --- a/website/content/docs/connect/configuration.mdx +++ b/website/content/docs/connect/configuration.mdx @@ -78,7 +78,7 @@ needed for a secure deployment. ## Centralized proxy and service configuration 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), +[sidecar service definitions](/consul/docs/connect/proxies/deploy-sidecar-services), and the default protocols for service instances in their [service definitions](/consul/docs/services/usage/define-services). diff --git a/website/content/docs/connect/connect-internals.mdx b/website/content/docs/connect/connect-internals.mdx index 73a3cc1e8980..99541f012c3b 100644 --- a/website/content/docs/connect/connect-internals.mdx +++ b/website/content/docs/connect/connect-internals.mdx @@ -97,7 +97,7 @@ a long period of inactivity (3 days by default), the cache will empty itself. ## Connections Across Datacenters -A sidecar proxy's [upstream configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) +A sidecar proxy's [upstream configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) may specify an alternative datacenter or a prepared query that can address services in multiple datacenters (such as the [geo failover](/consul/tutorials/developer-discovery/automate-geo-failover) pattern). diff --git a/website/content/docs/connect/distributed-tracing.mdx b/website/content/docs/connect/distributed-tracing.mdx index 939cde52d5a5..9b74a612579c 100644 --- a/website/content/docs/connect/distributed-tracing.mdx +++ b/website/content/docs/connect/distributed-tracing.mdx @@ -145,9 +145,9 @@ spec: --> **NOTE:** This example uses a [proxy defaults](/consul/docs/connect/config-entries/proxy-defaults) config entry which will apply to all proxies -but you can also apply this config in the -[proxy service registration](/consul/docs/connect/registration/service-registration#proxy-parameters) (not supported on Kubernetes). +-> **NOTE:** This example uses a [proxy defaults](/consul/docs/connect/config-entries/proxy-defaults) configuration entry, which applies to all proxies, +but you can also apply the configuration in the +[`proxy` block of your service configuration](/consul/docs/connect/proxies/proxy-config-reference#proxy-parameters). The proxy service registration is not supported on Kubernetes. Within the config there are two keys you need to customize: diff --git a/website/content/docs/connect/gateways/mesh-gateway/index.mdx b/website/content/docs/connect/gateways/mesh-gateway/index.mdx index 6faec5e9e760..17821edf531f 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/index.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/index.mdx @@ -48,7 +48,7 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe Configure the following settings to register the mesh gateway as a service in Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. +* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. * Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. @@ -127,8 +127,8 @@ Name: web ### Enabling Gateways for a Service Instance -The following [Proxy Service Registration](/consul/docs/connect/registration/service-registration) -definition will enable gateways for the service instance in the `remote` mode. +The following [proxy service configuration](/consul/docs/connect/proxies/deploy-service-mesh-proxies) + enables gateways for the service instance in the `remote` mode. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx index 4e269d00fd48..22a4e9d9b8f7 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx @@ -43,7 +43,7 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe Configure the following settings to register the mesh gateway as a service in Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and partition. Refer to the [`upstreams` documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_partition` must be configured to enable cross-partition traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. +* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and partition. Refer to the [`upstreams` documentation](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_partition` must be configured to enable cross-partition traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. * Configure the `exported-services` configuration entry to enable Consul to export services contained in an admin partition to one or more additional partitions. Refer to the [Exported Services documentation](/consul/docs/connect/config-entries/exported-services) for details. * Define the `Proxy.Config` settings using opaque parameters compatible with your proxy, i.e., Envoy. For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. @@ -121,8 +121,8 @@ Name: web ### Enabling Gateways for a Service Instance -The following [Proxy Service Registration](/consul/docs/connect/registration/service-registration) -definition will enable gateways for `web` service instances in the `finance` partition. +The following [proxy service configuration](/consul/docs/connect/proxies/deploy-service-mesh-proxies) +enables gateways for `web` service instances in the `finance` partition. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx index 5a764c437248..dc017e0af232 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx @@ -57,7 +57,7 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe Configure the following settings to register the mesh gateway as a service in Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. +* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. * Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. @@ -137,8 +137,8 @@ Name: web ### Enabling Gateways for a Service Instance -The following [Proxy Service Registration](/consul/docs/connect/registration/service-registration) -definition will enable gateways for the service instance in the `remote` mode. +The following [proxy service configuration](/consul/docs/connect/proxies/deploy-service-mesh-proxies) +enables gateways for the service instance in the `remote` mode. diff --git a/website/content/docs/connect/l7-traffic/discovery-chain.mdx b/website/content/docs/connect/l7-traffic/discovery-chain.mdx index ae7582509c99..b7ee4e975ef8 100644 --- a/website/content/docs/connect/l7-traffic/discovery-chain.mdx +++ b/website/content/docs/connect/l7-traffic/discovery-chain.mdx @@ -59,11 +59,10 @@ various configuration entries interact in more complex ways. For example: [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) config entry. Violations must be rejected as invalid. -- If an [upstream - configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) - [`datacenter`](/consul/docs/connect/registration/service-registration#datacenter) - parameter is defined then any configuration entry that does not explicitly - refer to a desired datacenter should use that value from the upstream. +- When an [upstream + configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) + `datacenter` parameter is defined, any configuration entry that does not explicitly + refer to a desired datacenter uses the value defined in the upstream. ## Compilation @@ -80,9 +79,9 @@ API](/consul/api-docs/discovery-chain). - **Datacenter** - The datacenter to use as the basis of compilation. - **Overrides** - Discovery-time tweaks to apply when compiling. These should be derived from either the - [proxy](/consul/docs/connect/registration/service-registration#complete-configuration-example) + [proxy](/consul/docs/connect/proxies/proxy-config-reference#complete-configuration-example) or - [upstream](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) + [upstream](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) configurations if either are set. ### Compilation Results diff --git a/website/content/docs/connect/observability/index.mdx b/website/content/docs/connect/observability/index.mdx index 35db2edd4b49..95dce806a0ab 100644 --- a/website/content/docs/connect/observability/index.mdx +++ b/website/content/docs/connect/observability/index.mdx @@ -44,7 +44,7 @@ Find other possible metrics syncs in the [Envoy documentation](/consul/docs/conn ### Service protocol 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. +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/proxies/proxy-config-reference#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 @@ -54,5 +54,5 @@ load balancing and routing decisions. ### 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). +[`upstreams`](/consul/docs/connect/proxies/proxy-config-reference#upstreams) +sidecar parameter, which can be defined in a service's [sidecar registration](/consul/docs/connect/proxies/deploy-sidecar-services). diff --git a/website/content/docs/connect/proxies/built-in.mdx b/website/content/docs/connect/proxies/built-in.mdx index c393d4648a89..1bfd943db7fb 100644 --- a/website/content/docs/connect/proxies/built-in.mdx +++ b/website/content/docs/connect/proxies/built-in.mdx @@ -77,7 +77,7 @@ All fields are optional with a reasonable default. - `upstreams`- **Deprecated** Upstreams are now specified in the `connect.proxy` definition. Upstreams specified in the opaque config map here will continue to work for compatibility but it's strongly recommended that - you move to using the higher level [upstream configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference). + you move to using the higher level [upstream configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference). ## Proxy Upstream Config Key Reference diff --git a/website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx b/website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx index 60d9cc5ab745..630da4a131de 100644 --- a/website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx +++ b/website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx @@ -1,4 +1,4 @@ ---- +--- layout: docs page_title: Deploy service mesh proxies description: >- @@ -7,7 +7,9 @@ description: >- # Deploy service mesh proxies services -This topic describes how to create, register, and start service mesh proxies in Consul. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for additional information about how proxies enable Consul functionalities. For information about deployed sidecar proxies, refer to [Deploy sidecar proxy services](/consul/docs/connect/proxies/deploy-sidecar-services). +This topic describes how to create, register, and start service mesh proxies in Consul. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for additional information about how proxies enable Consul functionalities. + +For information about deploying proxies as sidecars for service instances, refer to [Deploy sidecar proxy services](/consul/docs/connect/proxies/deploy-sidecar-services). ## Overview @@ -16,21 +18,21 @@ Complete the following steps to deploy a service mesh proxy: 1. It is not required, but you can create a proxy defaults configuration entry that contains global passthrough settings for all Envoy proxies. 1. Create a service definition file and specify the proxy configurations in the `proxy` block. 1. Register the service using the API or CLI. -1. Start the proxy service. +1. Start the proxy service. Proxies appear in the list of services registered to Consul, but they must be started before they begin to route traffic in your service mesh. ## Requirements -If [ACLs](/consul/docs/security/acl) are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information. +If ACLs are enabled and you want to configure global Envoy settings using the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information. ## Configure global Envoy passthrough settings -If you want to define global passthrough settings for all Envoy proxies, create a proxy defaults configuration entry and specify default settings, such as access log configuration. [Service defaults configuration entries](/consul/docs/connect/config-entries/service-defaults) override proxy defaults and individual service configurations override both configuration entries. +If you want to define global passthrough settings for all Envoy proxies, create a proxy defaults configuration entry and specify default settings, such as access log configuration. Note that [service defaults configuration entries](/consul/docs/connect/config-entries/service-defaults) override proxy defaults and individual service configurations override both configuration entries. 1. Create a proxy defaults configuration entry and specify the following parameters: - `Kind`: Must be set to `proxy-defaults` - `Name`: Must be set to `global` 1. Configure any additional settings you want to apply to all proxies. Refer to [Proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) for details about all settings available in the configuraiton entry. -1. Apply the configuration by either calling the [`/config` API endpoint](/consul/api-docs/config) or running the [`consul config write` CLI command](/consul/commands/config/write). The following example writes a proxy defaults configuration entry from a local HCL file using the CLI: +1. Apply the configuration by either calling the [`/config` HTTP API endpoint](/consul/api-docs/config) or running the [`consul config write` CLI command](/consul/commands/config/write). The following example writes a proxy defaults configuration entry from a local HCL file using the CLI: ```shell-session $ consul config write proxy-defaults.hcl @@ -48,7 +50,7 @@ Create a service definition file and configure the following fields to define a Refer to the [Service mesh proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference) for example configurations. - ## Register the service +## Register the service Provide the service definition to the Consul agent to register your proxy service. You can use the same methods for registering proxy services as you do for registering application services: diff --git a/website/content/docs/connect/proxies/deploy-sidecar-services.mdx b/website/content/docs/connect/proxies/deploy-sidecar-services.mdx index 23e7a6238aa1..8e15569b0996 100644 --- a/website/content/docs/connect/proxies/deploy-sidecar-services.mdx +++ b/website/content/docs/connect/proxies/deploy-sidecar-services.mdx @@ -7,7 +7,7 @@ description: >- # Deploy sidecar services -This topic describes how to create, register, and start sidecar proxy services in Consul. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for additional information about how proxies enable Consul functionalities. For information about deploying service mesh proxies, refer to [Deploy service mesh proxies](/consul/docs/connect/proxies/deploy-service-mesh-proxies). +This topic describes how to create, register, and start sidecar proxy services in Consul. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for additional information about how proxies enable Consul's functions and operations. For information about deploying service mesh proxies, refer to [Deploy service mesh proxies](/consul/docs/connect/proxies/deploy-service-mesh-proxies). ## Overview @@ -23,7 +23,7 @@ You can attach a sidecar proxy to a service you want to deploy to your mesh: ## Requirements -If [ACLs](/consul/docs/security/acl) are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information. +If ACLs are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information. ## Configure global Envoy passthrough settings @@ -43,9 +43,9 @@ $ consul config write proxy-defaults.hcl Create a service definition and configure the following fields: -1. Specify a name for the service you want to attach a sidecar proxy to in the `name` field. This field is required for all services you want to register in Consul. -1. Specify a port number where other services registered with Consul can discover and connect to the service in the `port` field. This field is required for all services you want to register in Consul. -1. Set the `connect` field to `{ sidecar_service: {} }`. The `{ sidecar_service: {} }` value is a macro that applies a set of default configurations that enable you to quickly implement a sidecar. Refer to [Sidecar service defaults](#sidecar-service-defaults) for additional information. +1. `name`: Specify a name for the service you want to attach a sidecar proxy to in the `name` field. This field is required for all services you want to register in Consul. +1. `port`: Specify a port number where other services registered with Consul can discover and connect to the service in the `port` field. This field is required for all services you want to register in Consul. +1. `connect`: Set the `connect` field to `{ sidecar_service: {} }`. The `{ sidecar_service: {} }` value is a macro that applies a set of default configurations that enable you to quickly implement a sidecar. Refer to [Sidecar service defaults](#sidecar-service-defaults) for additional information. 1. Configure any additional options for your service. Refer to [Services configuration reference](/consul/docs/services/configuration/services-configuration-reference) for details. In the following example, a service named `web` is configured with a sidecar proxy: @@ -200,16 +200,16 @@ the `connect.sidecar_service` definition to customize the proxy registration. The "parent" service refers to the service definition that embeds the sidecar proxy. -- `id` - ID defaults to being `-sidecar-proxy`. This can't +- `id` - ID defaults to `-sidecar-proxy`. This value cannot be overridden as it is used to [manage the lifecycle](#lifecycle) of the registration. -- `name` - Defaults to being `-sidecar-proxy`. +- `name` - Defaults to `-sidecar-proxy`. - `tags` - Defaults to the tags of the parent service. - `meta` - Defaults to the service metadata of the parent service. - `port` - Defaults to being auto-assigned from a configurable range specified by [`sidecar_min_port`](/consul/docs/agent/config/config-files#sidecar_min_port) and [`sidecar_max_port`](/consul/docs/agent/config/config-files#sidecar_max_port). -- `kind` - Defaults to `connect-proxy`. This can't be overridden currently. +- `kind` - Defaults to `connect-proxy`. This value cannot be overridden. - `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/services/usage/checks#alias-checks) for the parent service. If either @@ -221,7 +221,7 @@ proxy. ### Example with overwritten configurations -In the following example, but the `sidecar_service` macro sets baselines configurations for the proxy, but the [proxy +In the following example, the `sidecar_service` macro sets baselines configurations for the proxy, but the [proxy upstreams](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference) and [built-in proxy configuration](/consul/docs/connect/proxies/built-in) fields contain custom values: @@ -253,13 +253,12 @@ configuration](/consul/docs/connect/proxies/built-in) fields contain custom valu 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 + this value. This ID is required to ensure that the agent can correctly deregister the sidecar service later when the parent service is removed. -- `kind` - Kind defaults to `connect-proxy` and there is currently no way to - 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.native` - Currently the `kind` is fixed to `connect-proxy` and it's +- `kind` - Kind defaults to `connect-proxy` and there is no way to + unset this behavior. +- `connect.sidecar_service` - Service definitions cannot be nested recursively. +- `connect.native` - The `kind` is fixed to `connect-proxy` and it is an error to register a `connect-proxy` that is also service mesh-native. ## Lifecycle @@ -270,17 +269,16 @@ have some specific behavior around their lifecycle that makes them easier to work with. The agent fixes the ID of the sidecar service to be based on the parent -service's ID. This enables the following behavior. +service's ID, which enables the following behavior. -- A service instance can _only ever have one_ sidecar service registered. -- When re-registering via API or reloading from configuration file: - - If something changes in the nested sidecar service definition, the change - will _update_ the current sidecar registration instead of creating a new +- A service instance can only ever have one sidecar service registered. +- When re-registering through the HTTP API or reloading from configuration file: + - If something changes in the nested sidecar service definition, the update is applied to the current sidecar registration instead of creating a new one. - If a service registration removes the nested `sidecar_service` then the - previously registered sidecar for that service will be deregistered + previously registered sidecar for that service is deregistered automatically. - When reloading the configuration files, if a service definition changes its - ID, then a new service instance _and_ a new sidecar instance will be - registered. The old ones will be removed since they are no longer found in - the config files. \ No newline at end of file + ID, then a new service instance and a new sidecar instance are + registered. The old instance and proxy are removed because they are no longer found in + the configuration files. diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 7c87842c1de9..1f3ea797b902 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -24,7 +24,7 @@ Consul can configure Envoy sidecars to proxy traffic over the following protocol On Consul 1.5.0 and older, Envoy proxies can only proxy TCP traffic at L4. -Some [L7 features](/consul/docs/connect/l7-traffic) can be configured using [configuration entries](/consul/docs/agent/config-entries). You can add [custom Envoy configurations](#advanced-configuration) to the [proxy service definition](/consul/docs/connect/registration/service-registration) to use Envoy features that are not currently exposed through configuration entries. Adding custom Envoy configurations to the service definition is an interim solution that enables you to use the more powerful features of Envoy. +You can configure some [L7 features](/consul/docs/connect/l7-traffic) in [configuration entries](/consul/docs/agent/config-entries). You can add [custom Envoy configurations](#advanced-configuration) to the [proxy service definition](/consul/docs/connect/proxies/proxy-config-reference), which enables you to leverage Envoy features that are not exposed through configuration entries. You can also use the [Consul Envoy extensions](/consul/docs/connect/proxies/envoy-extensions) to implement Envoy features. ~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/consul/commands/connect/envoy) Envoy must be run with the `--max-obj-name-len` option set to `256` or greater for Envoy versions prior to 1.11.0. @@ -77,7 +77,7 @@ The dynamic configuration Consul service mesh provides to each Envoy instance in - Service-discovery results for upstreams to enable each sidecar proxy to load-balance outgoing connections. - L7 configuration including timeouts and protocol-specific options. -- Configuration to [expose specific HTTP paths](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference). +- Configuration to [expose specific HTTP paths](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference). For more information on the parts of the Envoy proxy runtime configuration that are currently controllable via Consul service mesh, refer to [Dynamic @@ -139,9 +139,9 @@ Consul service mesh can control some parts of the bootstrap configuration by spe Add the following configuration items to the [global `proxy-defaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` -field of a [proxy service definition](/consul/docs/connect/registration/service-registration). When +field of a [proxy service definition](/consul/docs/proxies/proxy-config-reference). When connected to a Consul client agent, you can place the configuration in the `proxy.config` field of -the [`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. +the [`sidecar_service`](/consul/docs/connect/proxies/deploy-sidecar-services) block. - `envoy_statsd_url` - A URL in the form `udp://ip:port` identifying a UDP StatsD listener that Envoy should deliver metrics to. For example, this may be @@ -278,7 +278,7 @@ automatically configure its upstream listeners appropriately too as below. This automated discovery results in Consul auto-populating the `proxy.config` and `proxy.upstreams[*].config` fields of the [proxy service -definition](/consul/docs/connect/registration/service-registration) that is +definition](/consul/docs/connect/proxies/proxy-config-reference) that is actually registered. To learn about other options that can be configured centrally see the @@ -287,7 +287,7 @@ To learn about other options that can be configured centrally see the ### Proxy Config Options These fields may also be overridden explicitly in `proxy.config` of the [proxy service -definition](/consul/docs/connect/registration/service-registration), or defined in +definition](/consul/docs/connect/proxies/proxy-config-reference), or defined in the [global `proxy-defaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults) to act as defaults that are inherited by all services. @@ -359,8 +359,8 @@ defaults that are inherited by all services. The following configuration items may be overridden directly in the `proxy.upstreams[].config` field of a [proxy service -definition](/consul/docs/connect/registration/service-registration) or -[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/proxies/proxy-config-reference) or +[`sidecar_service`](/consul/docs/connect/proxies/deploy-sidecar-services) block. - `protocol` - Same as above in main config but affects the listener setup for the upstream. @@ -436,7 +436,7 @@ definition](/consul/docs/connect/registration/service-registration) or ### Gateway Options These fields may also be overridden explicitly in the [proxy service -definition](/consul/docs/connect/registration/service-registration), or defined in +definition](/consul/docs/connect/proxies/proxy-config-reference), or defined in the [global `proxy-defaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults) to act as defaults that are inherited by all services. @@ -610,8 +610,8 @@ Users may add the following configuration items to the [global `proxy-defaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` field of a [proxy service -definition](/consul/docs/connect/registration/service-registration) or -[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/proxies/proxy-config-reference) or +[`sidecar_service`](/consul/docs/connect/proxies/deploy-sidecar-services) block. - `envoy_extra_static_clusters_json` - Specifies one or more [Envoy clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto) that will be appended to the array of [static @@ -791,8 +791,8 @@ Users may add the following configuration items to the [global `proxy-defaults` configuration entry](/consul/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` field of a [proxy service -definition](/consul/docs/connect/registration/service-registration) or -[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/proxies/proxy-config-reference) or +[`sidecar_service`](/consul/docs/connect/proxies/deploy-sidecar-services) block. - `envoy_bootstrap_json_tpl` - Specifies a template in Go template syntax that is used in place of [the default @@ -988,8 +988,8 @@ definition](/consul/docs/connect/registration/service-registration) or The following configuration items may be overridden directly in the `proxy.upstreams[].config` field of a [proxy service -definition](/consul/docs/connect/registration/service-registration) or -[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/proxies/proxy-config-reference) or +[`sidecar_service`](/consul/docs/connect/deploy/deploy-sidecar-services) block. ~> **Note:** - When a [`service-router`](/consul/docs/connect/config-entries/service-router), diff --git a/website/content/docs/connect/proxies/index.mdx b/website/content/docs/connect/proxies/index.mdx index eeea3305f214..32ec802235b1 100644 --- a/website/content/docs/connect/proxies/index.mdx +++ b/website/content/docs/connect/proxies/index.mdx @@ -7,21 +7,25 @@ description: >- # Service mesh proxy overview -This topic provides an overview of how Consul uses proxies in your service mesh. A proxy is a type of service that enables unmodified applications to connect to other services in the service mesh. Consul ships with a built-in L4 proxy and has first class support for Envoy. You can plug other proxies into your environment, as well, and apply configurations in Consul to define proxy behavior. +This topic provides an overview of how Consul uses proxies in your service mesh. A proxy is a type of service that enables unmodified applications to connect to other services in the service mesh. Consul ships with a built-in L4 proxy and has first class support for Envoy. You can plug other proxies into your environment as well, and apply configurations in Consul to define proxy behavior. ## Proxy use cases -_Proxies_ are services that you can configure to perform several different types of functions in Consul. +You can configure proxies to perform several different types of functions in Consul. + +### Service mesh proxies + +A _service mesh proxy_ is any type of proxy service that you use for communication in a service mesh. Specialized proxy implementations, such as sidecar proxies and gateways, are subsets of service mesh proxies. Refer to [Deploy service mesh proxy services](/consul/docs/connect/proxies/deploy-service-mesh-proxies) for instructions on how to deploy a service mesh proxy. ### Sidecars -You can configure proxies to operate as sidecar services transparently handles inbound and outbound service connections. Sidecars also automatically wrap and verify TLS connections. Each service in your mesh should have its own sidecar proxy. +Sidecar proxies are service mesh proxy implementations that transparently handles inbound and outbound service connections. Sidecars automatically wrap and verify TLS connections. In a non-containerized network, each service in your mesh should have its own sidecar proxy. Refer to [Deploy sidecar services](/consul/docs/connect/proxies/deploy-sidecar-services) for additional information. ### Gateways -You can configure proxies to operate as gateway services, which allow service-to-service traffic across different network areas, including peered clusters, WAN-federated datacenters, and nodes outside the mesh. Consul ships with several types of gateway capabilities, but gateways deliver the underlying functionality. +You can configure service mesh proxies to operate as gateway services, which allow service-to-service traffic across different network areas, including peered clusters, WAN-federated datacenters, and nodes outside the mesh. Consul ships with several types of gateway capabilities, but gateways deliver the underlying functionality. Refer to [Gateways overview](/consul/docs/connect/gateways) for additional information. @@ -40,7 +44,7 @@ The following procedure describes how to implement proxies: 1. **Configure global proxy settings**. You can configure global passthrough settings for all proxies deployed to your service mesh in the proxy defaults configuration entry. This step is not required, but it enables you to define common behaviors in a central configuration. 1. **Deploy your service mesh proxy**. Configure proxy behavior in a service definition and register the proxy with Consul. -1. **Start the proxy service**. +1. **Start the proxy service**. Proxies appear in the list of services registered to Consul and must be started before they begin to route traffic in your service mesh. ### Dynamic upstreams require native integration @@ -48,7 +52,7 @@ Service mesh proxies do not support dynamic upstreams. If an application require ## Proxies in Kubernetes-orchestrated networks -For Kubernetes-orchestrated environments, Consul deploys _dataplanes_ by default to manage proxies. Consul dataplanes are light-weight processes that leverage existing Kubernetes sidecar orchestration capabilities. Refer to the [dataplanes documentation](/consul/docs/connect/dataplane) for additional information. +For Kubernetes-orchestrated environments, Consul deploys _dataplanes_ by default to manage sidecar proxies. Consul dataplanes are light-weight processes that leverage existing Kubernetes sidecar orchestration capabilities. Refer to the [dataplanes documentation](/consul/docs/connect/dataplane) for additional information. ## Guidance @@ -67,7 +71,7 @@ Refer to the following resources for help using service mesh proxies: ### Reference documentation -- [Proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) for additional information. +- [Proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) - [Envoy proxies reference](/consul/docs/connect/proxies/envoy) - [Service mesh proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference) - [`consul connect envoy` command](/consul/commands/connect/envoy) diff --git a/website/content/docs/connect/proxies/proxy-config-reference.mdx b/website/content/docs/connect/proxies/proxy-config-reference.mdx index dc3765b8cdb5..8c2b5fb5c8e7 100644 --- a/website/content/docs/connect/proxies/proxy-config-reference.mdx +++ b/website/content/docs/connect/proxies/proxy-config-reference.mdx @@ -89,7 +89,7 @@ Specify the following parameters in the `proxy` code block to configure a sideca * `local_service_port`: Integer value that specifies the port that the proxy should use to connect to the _local_ service instance. Refer to the [proxy parameters reference](#local-service-port) for details. * `local_service_address`: String value that specifies the IP address or hostname that the proxy should use to connect to the _local_ service. Refer to the [proxy parameters reference](#local-service-address) for details. -See [Sidecar Service Registration](/consul/docs/connect/registration/sidecar-service) for additional information about configuring service mesh proxies as sidecars. +Refer to [Deploy sidecar services](/consul/docs/connect/proxies/deploy-sidecar-services) for additional information about configuring service mesh proxies as sidecars. ### Complete configuration example diff --git a/website/content/docs/k8s/connect/health.mdx b/website/content/docs/k8s/connect/health.mdx index 654cb5034245..a3096d5c9cba 100644 --- a/website/content/docs/k8s/connect/health.mdx +++ b/website/content/docs/k8s/connect/health.mdx @@ -20,7 +20,7 @@ The Consul health check's state reflects the pod's readiness status. 1. If the pod is using [transparent proxy mode](/consul/docs/connect/transparent-proxy), the mutating webhook redirects all `http` based startup, liveness, and readiness probes in the pod through the Envoy proxy. This webhook is defined in the -[`ExposePaths` configuration](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) +[`ExposePaths` configuration](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference) for each probe so that kubelet can access the endpoint through the Envoy proxy. The mutation behavior can be disabled, by setting either the `consul.hashicorp.com/transparent-proxy-overwrite-probes` diff --git a/website/content/docs/services/configuration/services-configuration-reference.mdx b/website/content/docs/services/configuration/services-configuration-reference.mdx index 95f01e16ff73..7dd71a9ce103 100644 --- a/website/content/docs/services/configuration/services-configuration-reference.mdx +++ b/website/content/docs/services/configuration/services-configuration-reference.mdx @@ -320,7 +320,7 @@ String value that identifies the service as a proxy and determines its role in t 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. +- `connect-proxy`: Defines the configuration for a service mesh proxy. Refer to [Deploy service mesh proxies](/consul/docs/connect/proxies/deploy-service-mesh-proxies) 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) @@ -328,7 +328,7 @@ You can specify the following values: 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. +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 [Service mesh proxies overview](/consul/docs/connect/proxies) 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. @@ -338,7 +338,7 @@ The following table describes the parameters that you can place in the `connect` | 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. | +| `sidecar_service` | Object that defines a sidecar proxy for the service. Do not configure if `native` is set to `true`. Refer to [Deploy sidecar services](/consul/docs/connect/proxies/deploy-sidecar-services) for usage and configuration details. | Refer to [Sidecar service defaults](/consul/docs/connect/proxies/deploy-sidecar-services#sidecar-service-defaults). | ### 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. diff --git a/website/content/docs/services/discovery/dns-overview.mdx b/website/content/docs/services/discovery/dns-overview.mdx index 843d97bd185d..34e92e5fe8a2 100644 --- a/website/content/docs/services/discovery/dns-overview.mdx +++ b/website/content/docs/services/discovery/dns-overview.mdx @@ -26,7 +26,7 @@ Refer to [ Native App Integration](/consul/docs/connect/native) and its [Go pack ### 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 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/proxies/proxy-config-reference#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. diff --git a/website/content/docs/services/services.mdx b/website/content/docs/services/services.mdx index f2d4eb70c111..116193afe361 100644 --- a/website/content/docs/services/services.mdx +++ b/website/content/docs/services/services.mdx @@ -35,7 +35,7 @@ Consul redirects service traffic through sidecar proxies if you use Consul servi ### 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. +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 [Deploy sidecar services](/consul/docs/connect/proxies/deploy-sidecar-services) for additional information. ### Kubernetes diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 610a6af201b0..616a37c888aa 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -786,7 +786,7 @@ Starting with Consul 1.7.1 this is the new default. Managed proxies, which are deprecated since Consul v1.3.0, have now been [removed](/consul/docs/connect/proxies). Before upgrading, you must migrate any managed proxy usage to [sidecar service -registrations](/consul/docs/connect/registration/sidecar-service). +registrations](/consul/docs/connect/proxies/deploy-sidecar-services). ## Consul 1.4.0