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 e86e3d4291c2..744873df5656 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 68a5fcbbcef5..f099bc303392 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -636,16 +636,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 1d94a79389b6..f2bd2c9ce513 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -1,53 +1,135 @@ --- layout: docs -page_title: Proxy Defaults - Configuration Entry Reference +page_title: Proxy defaults configuration entry reference description: >- The proxy defaults configuration entry kind defines default behaviors for proxies in the service mesh. Use the reference guide to learn about `""proxy-defaults""` config entry parameters. --- -# Proxy Defaults Configuration Entry +# Proxy defaults configuration reference -The `proxy-defaults` configuration entry (`ProxyDefaults` on Kubernetes) allows you to globally configure passthrough Envoy settings for proxies in the service mesh, including both sidecars and gateways. -It is different from the [`mesh` configuration entry](/consul/docs/connect/config-entries/mesh), which sets Consul features for cluster peering, transparent proxy, and TLS behavior that also affect Consul servers. - -Only one global entry is supported. -For Consul Enterprise, only the global entry in the `default` partition is recognized. +This topic provides reference information for proxy defaults configuration entries. Refer to [Service mesh proxy overview](/consul/docs/connect/proxies) for information about using proxies in Consul. ## Introduction -You can customize some service registration settings for service mesh proxies centrally using the `proxy-defaults` configuration entry in the `kind` field. +Proxy defaults configuration entries set global passthrough Envoy settings for proxies in the service mesh, including sidecars and gateways. Proxy defaults configuration entries do not control features for peered clusters, transparent proxy, or TLS behavior. For information about configuring Consul settings that affect service mesh behavior, refer to the [mesh configuration entry reference](/consul/docs/connect/config-entries/mesh). + +Consul only supports one global proxy defaults configuration entry at a time. If multiple configuration entries are defined in Consul Enterprise, Consul implements the configuration entry in the `default` partition. -You can still override this centralized configuration for specific services -with the [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) -configuration entry `kind` or for individual proxy instances in their [sidecar -service definitions](/consul/docs/connect/registration/sidecar-service). +## Configuration model -## Usage +The following list outlines field hierarchy, language-specific data types, and requirements in proxy defaults configuration entries. Click on a property name to view additional details, including default values. -1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). -1. Determine the settings you want to implement (see [Configuration](#configuration)). You can create a file containing the configuration or pass them to the state store directly to apply the configuration. -1. Apply the configuration using one of the following methods: - - Kubernetes CRD: Refer to the [Custom Resource Definitions](/consul/docs/k8s/crds) documentation for details. - - Issue the `consul config write` command: Refer to the [Consul Config Write](/consul/commands/config/write) documentation for details. + -## Configuration + + +- [`Kind`](#kind): string | required | must be set to `proxy-defaults` +- [`Name`](#name): string | must be set to `global` +- [`Namespace`](#namespace): string | `default` | +- [`Partition`](#partition): string | `default` | +- [`Meta`](#meta): map +- [`Config`](#meta): map +- [`EnvoyExtensions`](#envoyextensions): list of maps + - [`Name`](#envoyextensions): string + - [`Required`](#envoyextensions): string + - [`Arguments`](#envoyextensions): string + - [`ConsulVersion`](#envoyextensions): string + - [`EnvoyVersion`](#envoyextensions): string +- [`Mode`](#mode): string +- [`TransparentProxy`](#transparentproxy): map + - [`OutboundListenerPort`](#transparentproxy): number | `15001` + - [`DialedDirectly`](#transparentproxy): boolean | `false` +- [`MutualTLSMode`](#mutualtlsmode): string +- [`MeshGateway`](#meshgateway): map + - [`Mode`](#meshgateway): string +- [`Expose`](#expose): map + - [`Checks`](#expose-checks): boolean | `false` + - [`Paths`](#expose-paths): list of maps + - [`Path`](#expose-paths-path): string | must begin with `/` + - [`LocalPathPort`](#expose-paths): number | `0` + - [`ListenerPort`](#expose-paths): number | `0` + - [`Protocol`](#expose-paths): string | `http` +- [`FailoverPolicy`](#failoverpolicy): map + - [`Mode`](#failoverpolicy-mode): string +- [`AccessLogs`](#accesslogs): map + - [`Enabled`](#accesslogs): boolean | `false` + - [`DisableListenerLogs`](#accesslogs): boolean | `false` + - [`Type`](#accesslogs): string | `stdout` + - [`Path`](#accesslogs): string + - [`JSONFormat`](#accesslogs): string + - [`TextFormat`](#accesslogs): string -Configure the following parameters to define a `proxy-defaults` configuration entry: + + + +- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1` +- [`kind`](#kind): string | required | must be set to `ProxyDefaults` +- [`metadata`](#metadata): map | required + - [`name`](#metadata-name): string | required | must be set to `global` + - [`namespace`](#metadata-namespace): string | `default` | +- [`spec`](#spec): map | required + - [`config`](#spec-config): map + - [`EnvoyExtensions`](#spec-EnvoyExtensions): list of maps + - [`name`](#spec-EnvoyExtensions): string + - [`required`](#spec-EnvoyExtensions): string + - [`arguments`](#spec-EnvoyExtensions): string + - [`consulVersion`](#spec-EnvoyExtensions): string + - [`envoyVersion`](#spec-EnvoyExtensions): string + - [`mode`](#spec-mode): string + - [`transparentProxy`](#spec-transparentproxy): map + - [`outboundListenerPort`](#spec-transparentproxy): number | `15001` + - [`dialedDirectly`](#spec-transparentproxy): boolean | `false` + - [`mutualTLSMode`](#spec-mutualtlsmode): string + - [`meshGateway`](#spec-meshgateway): map + - [`mode`](#spec-meshgateway): string + - [`expose`](#spec-expose): map + - [`checks`](#spec-expose-checks): boolean | `false` + - [`paths`](#spec-expose-paths): list + - [`path`](#spec-expose-paths): string | must begin with `/` + - [`localPathPort`](#spec-expose-paths): number | `0` + - [`listenerPort`](#spec-expose-paths): number | `0` + - [`protocol`](#spec-expose-paths): string | `http` + - [`failoverPolicy`](#spec-failoverpolicy): map + - [`mode`](#spec-failoverpolicy-mode): string + - [`accessLogs`](#spec-accesslogs): map + - [`enabled`](#spec-accesslogs): boolean | `false` + - [`disableListenerLogs`](#spec-accesslogs): boolean | `false` + - [`type`](#spec-accesslogs): string | `stdout` + - [`path`](#spec-accesslogs): string + - [`jsonFormat`](#spec-accesslogs): string + - [`textFormat`](#spec-accesslogs): string + + + + + +## Complete configuration + +When every field is defined, a proxy defaults configuration entry has the following form: - - + ```hcl Kind = "proxy-defaults" Name = "global" +Namespace = "default" Meta { = "" } Config { = } +EnvoyExtensions = [ + { + Name= "" + Required = "required" + Arguments = "" + ConsulVersion = "" + EnvoyVersion = "" + } +] Mode = "" TransparentProxy { OutboundListenerPort = @@ -78,17 +160,27 @@ AccessLogs { TextFormat = "< text representation of access log format >" } ``` + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults metadata: name: global + namespace: default spec: meta: : config: : + EnvoyExtensions: + - name: + required: required + arguments: + consulVersion: + envoyVersion: mode: transparentProxy: outboundListenerPort: @@ -112,22 +204,36 @@ spec: textFormat: < text representation of access log format > ``` + + + + ```json { "Kind": "proxy-defaults", "Name": "global", + "Namespace": "default", "Meta": { "": "" }, "Config": { "": }, - "MutualTLSMode": "", + "EnvoyExtensions": [ + { + "Name": "", + "Required": "required", + "Arguments": "", + "ConsulVersion": "", + "EnvoyVersion": "" + } + ], "Mode": "", "TransparentProxy": { "OutboundListenerPort": , "DialedDirectly": }, + "MutualTLSMode": "", "MeshGateway": { "Mode": = "" }, @@ -153,415 +259,488 @@ spec: } ``` - + + + + +## Specification + +This section provides details about the fields you can configure in the proxy defaults configuration entry. + + + + + +### `Kind` + +Specifies the type of configuration entry to implement. Must be set to `proxy-defaults`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `proxy-defaults`. + +### `Name` + +Specifies a name for the configuration entry that is used to identify the configuration entry. Must be set to `global`. + +#### Values + +- Default: None +- This field is required. +- Data type: String that must be set to `global`. + +### `Namespace` + +Specifies the namespace that the proxy defaults apply to. You can only specify the `default` namespace. + +#### Values + +- Default: `default` +- Data type: String + +### `Partition` + +Specifies the local admin partition that the proxy defaults apply to. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. + +#### Values + +- Default: `default` +- Data type: String + +### `Meta` + +Specifies a set of custom key-value pairs to add the [Consul KV](#/consul/docs/dynamic-app-config/kv) store. + +#### Values + +- Default: None +- Data type: Map of one or more key-value pairs. + - Keys: String + - Values: String, integer, or float + +### `Config` + +Specifies an arbitrary map of configuration values used by service mesh proxies. The available configurations depend on the mesh proxy you use. You can configure any global values that your proxy allows in this field. Refer to the following topics for additional information: + +- [Envoy proxy configuration option](/consul/docs/connect/proxies/envoy#proxy-config-options) +- [Built-in proxy configuration options](/consul/docs/connect/proxies/built-in#proxy-config-key-reference) + +#### Values + +- Default: None +- Data type: Map + +### `EnvoyExtensions` + +Specifies a list of extensions that modify Envoy proxy configurations. Refer to [Envoy extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information. + +#### Values + +- Default: None +- Data type: List of maps containing the following fields: + - `Name` + - `Required` + - `Arguments` + - `ConsulVersion` + - `EnvoyVersion` + +The following table describes how to configure values in the `EnvoyExtensions` map: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `Name` | Specifies the name of the extension. | String | None | +| `Required` | Specify `true` to require Consul to implement the extension.

Use this parameter to ensure that extensions required for secure communication are not unintentionally bypassed.

Consul returns an error when `Required` is set to `true` and the extension does not update Envoy resources.

| String | None | +| `Arguments` | Specifies the arguments to pass to the extension executable. Refer to the documentation for the extension you want to implement for additional information. | Map | None | +| `ConsulVersion` | Specifies the version of Consul that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log.

The `ConsulVersion` and `EnvoyVersion` must both validate for Consul to implement the extension.

| String | None | +| `EnvoyVersion` | Specifies the version of Envoy that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log.

The `ConsulVersion` and `EnvoyVersion` must both validate for Consul to implement the extension.

| String | None | + +### `Mode` + +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 + +- Default: None +- Data type: String + +### `TransparentProxy` + +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 + +- Default: None +- Data type: Map of containing the following fields: + - `OutboundListenerPort` + - `DialedDirectly` + +The following table describes how to configure values in the `TransparentProxy` map: + +| 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` 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` + +Controls the default mutual TLS (mTLS) mode for all proxies. You can only set mutual TLS mode for services in transparent proxy mode. + +You can specify one of the following modes: + +`strict`: The sidecar proxy requires mTLS for incoming traffic. +`permissive`: The sidecar proxy accepts mTLS traffic on the sidecar proxy service port and accepts any traffic on the destination service port. We recommend only using permissive mode if necessary while onboarding services to the service mesh. + +#### Values + +- Default: `strict` +- Data type: One of the following string values: + - `strict` + - `permissive` + +### `MeshGateway` + +Sets the default mesh gateway `mode` field for all proxies. You can specify the following string values for the `mode` field: + +- `none`: The proxy does not make outbound connections through a mesh gateway. Instead, it makes outbound connections directly to the destination services. +- `local`: The proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The proxy makes an outbound connection to a gateway running in the destination datacenter. + +#### Values + +- Default: None +- Data type: Map containing the `mode` field + +### `Expose` + +Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to protect themselves by only listening on `localhost`. Applications that are not Consul service mesh-enabled are still able to contact an HTTP endpoint. + +Example use-cases include exposing the `/metrics` endpoint to a monitoring system, such as Prometheus, and exposing the `/healthz` endpoint to the kubelet for liveness checks. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/proxy-config-reference#expose-paths-configuration-reference) for additional information. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + - [`Checks`](#expose-checks) + - [`Paths`](#expose-paths) + +### `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 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. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `Expose{}.Paths[]` + +Specifies a list of configuration maps that define paths to expose through Envoy when `Expose.Checks` is set to `true`. + +#### Values + +- Default: None +- Data type: List of maps + +The following table describes the parameters for each map you can define in the list: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `Path` | Specifies the HTTP path to expose. You must prepend the path with a forward slash (`/`). | String | None | +| `LocalPathPort` | Specifies the port where the local service listens for connections to the path. | Integer | `0` | +| `ListenPort` | Specifies the port where the proxy listens for connections. The port must be available. If the port is unavailable, Envoy does not expose a listener for the path and the proxy registration still succeeds. | Integer | `0` | +| `Protocol` | Specifies the protocol of the listener. You can configure one of the following values:
  • `http`
  • `http2`: Use with gRPC traffic
    • | String | `http` | + +### `FailoverPolicy` + +Sets the failover policy `mode` field for all proxies. The failover policy mode defines how Consul directs traffic to failover service instances if the primary instance becomes unreachable. For example, you can direct Consul to send failover traffic to local service instances. Refer to [Failover overview](/consul/docs/connect/failover) for additional information. + +You can specify the following string values for the `mode` field: + +- `default`: Envoy sends failover traffic to the first failover target with healthy instances. +- `order-by-locality`: Envoy prioritizes failover targets that are closer to the downstream service. Envoy deterministically orders failover targets that are the same distance from the local proxy. + +#### Values + +- Default: None +- Data type: Map containing the `mode` field + +### `AccessLogs` + +Specifies [Envoy access logger](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging.html?highlight=access%20logs) configurations for all proxies in the service mesh, including gateways. This field also configures access logs on [Envoy's administration interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html?highlight=administration%20logs). + +#### Values + +- Default: None +- Data type: Map + +The following table describes the parameters you can define in the `AccessLogs` map: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `Enabled` | Enables Envoy to emit access logs for all proxies in the service mesh. | Boolean | `false` | +| `DisabledListenerLogs` | Disables access logs for traffic rejected at the listener level. Rejected traffic includes connections that do not match any of Envoy's configured filters, such as Consul upstream services. Set this option to `true` if you do not want to log unknown requests that Envoy is not forwarding. | Boolean | `false` | +| `Type` | Specifies the destination for access logs. You can specify one of the following types:
  • `stdout`
  • `stderr`
  • `file`
    • | String | None | +| `Path` | Specifies the destination for writing access logs to file when `Type` is set to `file`. | String | None | +| `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 |     - --> **NOTE:** The `proxy-defaults` config entry can only be created in the `default` -namespace and it will configure proxies in **all** namespaces. + - +### apiVersion -```hcl -Kind = "proxy-defaults" -Name = "global" -Namespace = "default" # Can only be set to "default". -Meta { - = "" -} -Config { - = -} -Mode = "" -TransparentProxy { - OutboundListenerPort = - DialedDirectly = -} -MutualTLSMode = "" -MeshGateway { - Mode = "" -} -Expose { - Checks = +Specifies the verion of the Consul API to use to apply the configuration entry. This must be set to `consul.hashicorp.com/v1alpha1`. - Paths = [ - { - Path = "" - LocalPathPort = - ListenerPort = - Protocol = "" - } - ] -} -AccessLogs { - Enabled = < true | false > - DisableListenerLogs = < true | false , disables listener access logs for unrecognized traffic> - Type = "< file | stdout | stdout, the destination for access logs >" - Path = "< set the output path for 'file' based access logs >" - JSONFormat = "< json representation of access log format >" - TextFormat = "< text representation of access log format >" -} -``` +#### Values -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ProxyDefaults -metadata: - name: global - namespace: default -spec: - meta: - : - config: - : - mode: - transparentProxy: - outboundListenerPort: - dialedDirectly: - mutualTLSMode: - meshGateway: - mode: - expose: - checks: - paths: - - path: - localPathPort: - listenerPort: - protocol:= - accessLogs: - enabled: < true | false > - disableListenerLogs: < true | false , disables listener access logs for unrecognized traffic> - type: < file | stdout | stdout, the destination for access logs > - path: < set the output path for 'file' based access logs > - jsonFormat: < json representation of access log format > - textFormat: < text representation of access log format > -``` +- Default: None +- This field is required. +- Data type: String value that must be set to `consul.hashicorp.com/v1alpha1`. -```json -{ - "Kind": "proxy-defaults", - "Name": "global", - "Namespace": "default", - "Meta": { - "": "" - }, - "Config": { - "": - }, - "Mode": "", - "TransparentProxy": { - "OutboundListenerPort": , - "DialedDirectly": - }, - "MutualTLSMode": "", - "MeshGateway": { - "Mode": = "" - }, - "Expose": { - "Checks": , - "Paths": [ - { - "Path": "", - "LocalPathPort": , - "ListenerPort": , - "Protocol": "" - } - ] - }, - "AccessLogs": { - "Enabled": < true | false >, - "DisableListenerLogs": < true | false , disables listener access logs for unrecognized traffic>, - "Type": "< file | stdout | stdout, the destination for access logs >", - "Path": "< set the output path for 'file' based access logs >", - "JSONFormat": "< json representation of access log format >", - "TextFormat": "< text representation of access log format >" - } -} -``` +### `kind` + +Specifies the type of configuration entry to implement. Must be set to `ProxyDefaults`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `ProxyDefaults`. + + +### `metadata` + +Map that contains the service name, namespace, and admin partition that the configuration entry applies to. + +#### Values + +- Default: none +- Map containing the following strings: + - `name` + - `namespace` + + +### `metadata.name` + +Specifies a name for the configuration entry that is used to identify the configuration entry. Must be set to `global`. + +#### Values + +- Default: None +- This field is required. +- Data type: String that must be set to `global`. + +### `metadata.namespace` + +Specifies the namespace that the proxy defaults apply to. If you are on the community version, Consul ignores the `namespace` field. Refer to [Kubernetes namespaces in Consul](/consul/docs/k8s/crds#consul-oss) for additional information. If you are on Consul Enterprise, refer to [Kubernetes namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for additional information. + +#### Values + +- Default: `default` +- Data type: String + +### `spec` + +Map that contains the details about the ProxyDefaults configuration entry. The `apiVersion`, `kind``, and `metadata` fields are siblings of the `spec` field. All other configurations are children. + +### `spec.config` + +Specifies an arbitrary map of configuration values used by service mesh proxies. The available configurations depend on the mesh proxy you use. You can configure any global values that your proxy allows in this field. Refer to the following topics for additional information: + +- [Envoy proxy configuration option](/consul/docs/connect/proxies/envoy#proxy-config-options) +- [Built-in proxy configuration options](/consul/docs/connect/proxies/built-in#proxy-config-key-reference) + +#### Values + +- Default: None +- Data type: Map + +### `spec.envoyExtensions` + +Specifies a list of extensions that modify Envoy proxy configurations. Refer to [Envoy extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information. + +#### Values + +- Default: None +- Data type: List of maps of containing the following fields: + - `name` + - `required` + - `arguments` + - `consulVersion` + - `envoyVersion` + +The following table describes how to configure values in the `EnvoyExtensions` map: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `name` | Specifies the name of the extension. | String | None | +| `required` | Specify `true` to require Consul to implement the extension.

    Use this parameter to ensure that extensions required for secure communication are not unintentionally bypassed.

    Consul returns an error when `Required` is set to `true` and the extension does not update Envoy resources.

    | String | None | +| `arguments` | Specifies the arguments to pass to the extension executable. Refer to the documentation for the extension you want to implement for additional information. | Map | None | +| `consulVersion` | Specifies the version of Consul that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log.

    The `consulVersion` and `envoyVersion` must both validate for Consul to implement the extension.

    | String | None | +| `envoyVersion` | Specifies the version of Envoy that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log.

    The `consulVersion` and `envoyVersion` must both validate for Consul to implement the extension.

    | String | None | + +### `spec.mode` + +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 + +- Default: None +- Data type: String + +### `spec.transparentProxy` + +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 + +- Default: None +- Data type: Map of containing the following fields: + - `outboundListenerPort` + - `dialedDirectly` + +The following table describes how to configure values in the `TransparentProxy` map: + +| 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` 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` + +Controls the default mutual TLS (mTLS) mode for all proxies. You can only set mutual TLS mode for services in transparent proxy mode. + +You can specify one of the following modes: + +`strict`: The sidecar proxy requires mTLS for incoming traffic. +`permissive`: The sidecar proxy accepts mTLS traffic on the sidecar proxy service port and accepts any traffic on the destination service port. We recommend only using permissive mode if necessary while onboarding services to the service mesh. + +#### Values + +- Default: `strict` +- Data type: One of the following string values: + - `strict` + - `permissive` + +### `spec.meshGateway` + +Sets the default mesh gateway `mode` field for all proxies. You can specify the following string values for the `mode` field: + +- `none`: The proxy does not make outbound connections through a mesh gateway. Instead, it makes outbound connections directly to the destination services. +- `local`: The proxy makes an outbound connection to a gateway running in the same datacenter. +- `remote`: The proxy makes an outbound connection to a gateway running in the destination datacenter. + +#### Values + +- Default: None +- Data type: Map containing the `mode` field + +### `spec.expose` + +Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to protect themselves by only listening on `localhost`. Applications that are not Consul service mesh-enabled are still able to contact an HTTP endpoint. + +Example use-cases include exposing the `/metrics` endpoint to a monitoring system, such as Prometheus, and exposing the `/healthz` endpoint to the kubelet for liveness checks. Refer to [Expose Paths Configuration Reference](/consul/docs/connect/proxy-config-reference#expose-paths-configuration-reference) for additional information. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + - [`checks`](#expose-checks) + - [`aths`](#expose-paths) + +### `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 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 + +### `spec.expose{}.paths[]` + +Specifies a list of configuration maps that define paths to expose through Envoy when `spec.expose.checks` is set to `true`. + +#### Values + +- Default: None +- Data type: List of maps. + +The following table describes the parameters for each map you can define in the list: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `path` | Specifies the HTTP path to expose. You must prepend the path with a forward slash (`/`). | String | None | +| `localPathPort` | Specifies the port where the local service listens for connections to the path. | Integer | `0` | +| `listenPort` | Specifies the port where the proxy listens for connections. The port must be available. If the port is unavailable, Envoy does not expose a listener for the path and the proxy registration still succeeds. | Integer | `0` | +| `protocol` | Specifies the protocol of the listener. You can configure one of the following values:
  • `http`
  • `http2`: Use with gRPC traffic
    • | String | `http` | + +### `spec.failoverPolicy` + +Sets the failover policy `mode` field for all proxies. The failover policy mode defines how Consul directs traffic to failover service instances if the primary instance becomes unreachable. For example, you can direct Consul to send failover traffic to local service instances. Refer to [Failover overview](/consul/docs/connect/failover) for additional information. + +You can specify the following string values for the `mode` field: + +- `default`: Envoy sends failover traffic to the first failover target with healthy instances. +- `order-by-locality`: Envoy prioritizes failover targets that are closer to the downstream service. Envoy deterministically orders failover targets that are the same distance from the local proxy. + +#### Values + +- Default: None +- Data type: Map containing the `mode` field + +### `spec.accessLogs` + +Specifies [Envoy access logger](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging.html?highlight=access%20logs) configurations for all proxies in the service mesh, including gateways. This field also configures access logs on [Envoy's administration interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html?highlight=administration%20logs). + +#### Values + +- Default: None +- Data type: Map + +The following table describes the parameters you can define in the `accessLogs` map: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `enabled` | Enables Envoy to emit access logs for all proxies in the service mesh. | Boolean | `false` | +| `disabledListenerLogs` | Disables access logs for traffic rejected at the listener level. Rejected traffic includes connections that do not match any of Envoy's configured filters, such as Consul upstream services. Set this option to `true` if you do not want to log unknown requests that Envoy is not forwarding. | Boolean | `false` | +| `type` | Specifies the destination for access logs. You can specify one of the following types:
  • `stdout`
  • `stderr`
  • `file`
    • | String | None | +| `path` | Specifies the destination for writing access logs to file when `type` is set to `file`. | String | None | +| `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 |     +     -### Configuration Parameters - -: nil', - description: - 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.', - yaml: false, - }, - { - name: 'metadata', - children: [ - { - name: 'name', - description: 'Must be set to `global`', - }, - { - name: 'namespace', - enterprise: true, - description: - 'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for more details.', - }, - ], - hcl: false, - }, - { - name: 'Config', - type: 'map[string]arbitrary', - description: `An arbitrary map of configuration values used by service mesh proxies. - The available configurations depend on the mesh proxy you use. - Any values that your proxy allows can be configured globally here. To explore these options please see the documentation for your chosen proxy. -
    • [Envoy](/consul/docs/connect/proxies/envoy#proxy-config-options)
      • -
    • [Consul's built-in proxy](/consul/docs/connect/proxies/built-in#proxy-config-key-reference)
    `, - }, - { - name: 'EnvoyExtensions', - type: 'array: []', - description: `A list of extensions to modify Envoy proxy configuration.

    - Applying \`EnvoyExtensions\` to \`ProxyDefaults\` may produce unintended consequences. We recommend enabling \`EnvoyExtensions\` with [\`ServiceDefaults\`](/consul/docs/connect/config-entries/service-defaults#envoyextensions) in most cases.`, - children: [ - { - name: 'Name', - type: `string: ""`, - description: `Name of the extension.`, - }, - { - name: 'Required', - type: `string: ""`, - description: `When \`Required\` is true and the extension does not update any Envoy resources, an error is - returned. Use this parameter to ensure that extensions required for secure communication are not unintentionally - bypassed.`, - }, - { - name: 'Arguments', - type: 'map: nil', - description: `Arguments to pass to the extension executable.`, - }, - ], - }, - { - name: 'Mode', - type: `string: ""`, - description: `One of \`direct\` or \`transparent\`. - \`transparent\` represents that inbound and outbound application traffic is being - captured and redirected through the proxy. This mode does not enable the traffic redirection - itself. Instead it signals Consul to configure Envoy as if traffic is already being redirected. - \`direct\` represents that the proxy's listeners must be dialed directly by the local - application and other proxies. - Added in v1.10.0.`, - }, - { - name: 'TransparentProxy', - type: 'TransparentProxyConfig: ', - description: `Controls configuration specific to proxies in transparent mode. Added in v1.10.0.`, - children: [ - { - name: 'OutboundListenerPort', - type: 'int: "15001"', - description: `The port the proxy should listen on for outbound traffic. This must be the port where - outbound application traffic is captured and redirected to.`, - }, - { - name: 'DialedDirectly', - type: 'bool: false', - description: `Determines whether this proxy instance's IP address can be dialed directly by transparent proxies. - Typically transparent proxies dial upstreams using the "virtual" tagged address, which load balances - across instances. Dialing individual instances can be helpful in cases like stateful services such - as a database cluster with a leader. `, - }, - ], - }, - { - name: 'MutualTLSMode', - type: 'string: ""', - description: `Controls the default mutual TLS mode for all proxies. This setting is only - supported for services with transparent proxy enabled. One of \`""\`, \`strict\`, or \`permissive\`. - When unset or \`""\`, the mode defaults to \`strict\`. When set to \`strict\`, the sidecar proxy - requires mutual TLS for incoming traffic. When set to \`permissive\`, the sidecar proxy accepts - mutual TLS traffic on the sidecar proxy service port and accepts any traffic on the destination - service port. We recommend only using \`permissive\` mode if necessary while onboarding services to - the service mesh. `, - }, - { - name: 'MeshGateway', - type: 'MeshGatewayConfig: ', - description: `Controls the default - [mesh gateway configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration) - for all proxies. Added in v1.6.0.`, - children: [ - { - name: 'Mode', - type: 'string: ""', - description: 'One of `none`, `local`, or `remote`.', - }, - ], - }, - { - name: 'Expose', - type: 'ExposeConfig: ', - description: `Controls the default - [expose path configuration](/consul/docs/connect/registration/service-registration#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. - Some examples include: exposing a \`/metrics\` path for Prometheus or \`/healthz\` for kubelet liveness checks.`, - children: [ - { - name: 'Checks', - type: 'bool: false', - description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. - Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/consul/docs/agent/config/config-files#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/consul/docs/agent/config/config-files#expose_min_port) to [expose_max_port](/consul/docs/agent/config/config-files#expose_max_port). - This flag is useful when a Consul client cannot reach registered services over localhost.`, - }, - { - name: 'Paths', - type: 'array: []', - description: 'A list of paths to expose through Envoy.', - children: [ - { - name: 'Path', - type: 'string: ""', - description: - 'The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.', - }, - { - name: 'LocalPathPort', - type: 'int: 0', - description: - 'The port where the local service is listening for connections to the path.', - }, - { - name: 'ListenerPort', - type: 'int: 0', - description: `The port where the proxy will listen for connections. This port must be available - for the listener to be set up. If the port is not free then Envoy will not expose a listener for the path, - but the proxy registration will not fail.`, - }, - { - name: 'Protocol', - type: 'string: "http"', - description: - 'Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.', - }, - ], - }, - ], - }, - { - name: 'FailoverPolicy', - type: 'ServiceResolverFailoverPolicy: ', - description: `Policy specifies the exact mechanism used for failover. - Added in v1.16.0.`, - children: [ - { - name: 'Mode', - type: 'string: ""', - description: 'One of `""`, `default`, or `order-by-locality`.', - }, - ], - }, - { - name: 'AccessLogs', - type: 'AccessLogsConfig: ', - description: `Controls the configuration of [Envoy's access logging](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging.html?highlight=access%20logs) - for all proxies in the mesh, including gateways. It also configures access logs on [Envoy's administration interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html?highlight=administration%20logs).`, - children: [ - { - name: 'Enabled', - type: 'bool: false', - description: 'When enabled, access logs are emitted for all proxies in the mesh, including gateways.', - }, - { - name: 'DisableListenerLogs', - type: 'bool: false', - description: `When enabled, access logs for traffic rejected at the listener-level are not emitted. - This traffic includes connections that do not match any of Envoy's configured filters, such as Consul upstream services. - Set this option to \`true\` if you do not want to log unknown requests that Envoy is not forwarding`, - }, - { - name: 'Type', - type: 'string: "stdout"', - description: 'The destination for access logs. One of \`stdout\`, \`stderr\`, or \`file\`.', - }, - { - name: 'Path', - type: 'string: ""', - description: 'The destination file for access logs. Only valid with \`Type\` set to \`file\`.', - }, - { - name: 'JSONFormat', - type: 'string: (default as follows)', - description: `A JSON-formatted string that represents the format of each emitted access log. - By default, it is set to the [default access log format](/consul/docs/connect/observability/access-logs#default-log-format). - 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. - Nesting is supported. - Invalid if a custom format is specified with TextFormat.`, - }, - { - name: 'TextFormat', - type: 'string: ""', - description: `A formatted string that represents the format of each emitted access log. - Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) can be used to customize the data emitted. - A new line is added to the string automatically. - Invalid when a custom JSONFormat is already specified.`, - } - ], - }, - ]} -/> ## Examples +The following examples demonstrate common patterns for configuring proxy defaults configuration entries. + ### Default protocol -The following example configures the default protocol for all proxies. +The following example sets the default protocol for all proxies to `http`. - + - +#### Community edition ```hcl Kind = "proxy-defaults" @@ -571,6 +750,24 @@ Config { } ``` +#### Consul Enterprise + +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" +Name = "global" +Namespace = "default" # Can only be set to "default". +Config { + protocol = "http" +} +``` + + + + +#### Community edition + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -581,34 +778,9 @@ spec: protocol: http ``` -```json -{ - "Kind": "proxy-defaults", - "Name": "global", - "Config": { - "protocol": "http" - } -} -``` +#### Consul Enterprise - - - - - --> **NOTE:** The `proxy-defaults` config entry can only be created in the `default` -namespace and it will configure proxies in **all** namespaces. - - - -```hcl -Kind = "proxy-defaults" -Name = "global" -Namespace = "default" # Can only be set to "default". -Config { - protocol = "http" -} -``` +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 @@ -621,27 +793,46 @@ spec: protocol: http ``` + + + + +#### Community edition + ```json { "Kind": "proxy-defaults", "Name": "global", - "Namespace": "default", "Config": { "protocol": "http" } } ``` +#### Consul Enterprise + +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 +{ + "Kind": "proxy-defaults", + "Name": "global", + "Namespace": "default", + "Config": { + "protocol": "http" + } +} +``` + ### Prometheus The following example configures all proxies to expose Prometheus metrics. - + + ```hcl Kind = "proxy-defaults" @@ -651,6 +842,11 @@ Config { } ``` + + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -661,6 +857,10 @@ spec: envoy_prometheus_bind_addr: '0.0.0.0:9102' ``` + + + + ```json { "Kind": "proxy-defaults", @@ -671,14 +871,17 @@ spec: } ``` - + + + ### Access Logs -The following example is a minimal configuration for enabling access logs for all proxies. -Refer to [access logs](/consul/docs/connect/observability/access-logs) for advanced configurations. +The following example enables access logs for all proxies. Refer to [access logs](/consul/docs/connect/observability/access-logs) for more detailed examples. + + + - ```hcl Kind = "proxy-defaults" @@ -688,6 +891,10 @@ AccessLogs { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -698,6 +905,10 @@ spec: enabled: true ``` + + + + ```json { "Kind": "proxy-defaults", @@ -708,13 +919,16 @@ spec: } ``` - + + + ### Proxy-specific defaults -The following example configures some custom default values for all proxies. +The following example configures custom default values for all proxies. - + + ```hcl Kind = "proxy-defaults" @@ -725,6 +939,10 @@ Config { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -736,6 +954,10 @@ spec: handshake_timeout_ms: 10000 ``` + + + + ```json { "Kind": "proxy-defaults", @@ -747,13 +969,6 @@ spec: } ``` - - -## ACLs - -Configuration entries may be protected by [ACLs](/consul/docs/security/acl). - -Reading a `proxy-defaults` config entry requires no specific privileges. + -Creating, updating, or deleting a `proxy-defaults` config entry requires -`operator:write`. + \ No newline at end of file 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 363cded6f7ad..ffe5ef033bb6 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 new file mode 100644 index 000000000000..630da4a131de --- /dev/null +++ b/website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx @@ -0,0 +1,79 @@ +--- +layout: docs +page_title: Deploy service mesh proxies +description: >- + Envoy and other proxies in Consul service mesh enable service-to-service communication across your network. Learn how to deploy service mesh proxies in this topic. +--- + +# 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 deploying proxies as sidecars for service instances, refer to [Deploy sidecar proxy services](/consul/docs/connect/proxies/deploy-sidecar-services). + +## Overview + +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. 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 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. 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` 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 +``` + +## Define service mesh proxy + +Create a service definition file and configure the following fields to define a service mesh proxy: + +1. Set the `kind` field to `connect-proxy`. Refer to the [services configuration reference](/consul/docs/services/configuration/services-configuration-reference#kind) for information about other kinds of proxies you can declare. +1. Specify a name for the proxy service in the `name` field. Consul applies the configurations to any proxies you bootstrap with the same name. +1. In the `proxy.destination_service_name` field, specify the name of the service that the proxy represents. +1. Configure any additional proxy behaviors that you want to implement in the `proxy` block. Refer to the [Service mesh proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference) for information about all parameters. +1. Specify a port number where other services registered with Consul can discover and connect to the proxies service in the `port` field. To ensure that services only allow external connections established through the service mesh protocol, you should configure all services to only accept connections on a loopback address. + +Refer to the [Service mesh proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference) for example configurations. + +## 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: + +- Place the service definition in a Consul agent's configuration directory and start, restart, or reload the agent. Use this method when implementing changes to an existing proxy service. +- Use the `consul services register` command to register the proxy service with a running Consul agent. +- Call the `/agent/service/register` HTTP API endpoint to register the proxy service with a running Consul agent. + +Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions. + +In the following example, the `consul services register` command registers a proxy service stored in `proxy.hcl`: + +```shell-session +$ consul services register proxy.hcl +``` + +## Start the proxy + +Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the proxy service. Specify the ID of the proxy you want to start with the `-proxy-id` option. + +The following example command starts an Envoy proxy for the `web-proxy` service: + +```shell-session +$ consul connect envoy -proxy-id=web-proxy +``` + +For details about operating an Envoy proxy in Consul, refer to the [Envoy proxy reference](/consul/docs/connect/proxies/envoy). diff --git a/website/content/docs/connect/proxies/deploy-sidecar-services.mdx b/website/content/docs/connect/proxies/deploy-sidecar-services.mdx new file mode 100644 index 000000000000..ad533b59468e --- /dev/null +++ b/website/content/docs/connect/proxies/deploy-sidecar-services.mdx @@ -0,0 +1,284 @@ +--- +layout: docs +page_title: Deploy proxies as sidecar services +description: >- + You can register a service instance and its sidecar proxy at the same time. Learn about default settings, customizable parameters, limitations, and lifecycle behaviors of the sidecar proxy. +--- + +# 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'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 + +Sidecar proxies run on the same node as the single service instance that they handle traffic for. +They may be on the same VM or running as a separate container in the same network namespace. + +You can attach a sidecar proxy to a service you want to deploy to your mesh: + +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 the service definition and include the `connect` block. The `connect` block contains the sidecar proxy configurations that allow the service to interact with other services in the mesh. +1. Register the service using either the API or CLI. +1. Start the sidecar proxy service. + +## Requirements + +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 + +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. + +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: + +```shell-session +$ consul config write proxy-defaults.hcl +``` + +## Define service mesh proxy + +Create a service definition and configure the following fields: + +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: + + + + + +```hcl +service = { + name = "web" + port = 8080 + connect = { sidecar_service = {} } +} +``` + + + + + +```json + +{ + "service": { + "name": "web", + "port": 8080, + "connect": { "sidecar_service": {} } + } +} + +``` + + + + + +When Consul processes the service definition, it generates the following configuration in place of the `sidecar_service` macro. Note that sidecar proxies services are based on the `connect-proxy` type: + + + + + +```hcl +services = [ + { + name = "web" + port = 8080 + } + checks = { + Interval = "10s" + Name = "Connect Sidecar Listening" + TCP = "127.0.0.1:20000" + } + checks = { + alias_service = "web" + name = "Connect Sidecar Aliasing web" + } + kind = "connect-proxy" + name = "web-sidecar-proxy" + port = 20000 + proxy = { + destination_service_id = "web" + destination_service_name = "web" + local_service_address = "127.0.0.1" + local_service_port = 8080 + } +] + +``` + + + + + +```json +{ + "services": [ + { + "name": "web", + "port": 8080 + }, + { + "name": "web-sidecar-proxy", + "port": 20000, + "kind": "connect-proxy", + "checks": [ + { + "Name": "Connect Sidecar Listening", + "TCP": "127.0.0.1:20000", + "Interval": "10s" + }, + { + "name": "Connect Sidecar Aliasing web", + "alias_service": "web" + } + ], + "proxy": { + "destination_service_name": "web", + "destination_service_id": "web", + "local_service_address": "127.0.0.1", + "local_service_port": 8080 + } + } + ] +} + +``` + + + + + +## 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: + +- Place the service definition in a Consul agent's configuration directory and start, restart, or reload the agent. Use this method when implementing changes to an existing proxy service. +- Use the `consul services register` command to register the proxy service with a running Consul agent. +- Call the `/agent/service/register` HTTP API endpoint to register the proxy service with a running Consul agent. + +Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions. + +In the following example, the `consul services register` command registers a proxy service stored in `proxy.hcl`: + +```shell-session +$ consul services register proxy.hcl +``` + +## Start the proxy + +Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the proxy service. Specify the name of the service with the attached proxy with the `-sidecar-for` option. + +The following example command starts an Envoy sidecar proxy for the `web` service: + +```shell-session +$ consul connect envoy -sidecar-for=web +``` + +For details about operating an Envoy proxy in Consul, refer to [](/consul/docs/connect/proxies/envoy) + +## Configuration reference + +The `sidecar_service` block is a service definition that can contain most regular service definition fields. Refer to [Limitations](#limitations) for information about unsupported service definition fields for sidecar proxies. + +Consul treats sidecar proxy service definitions as a root-level service definition. All fields are optional in nested definitions, which default to opinionated settings that are intended to reduce burden of setting up a sidecar proxy. + +## Sidecar service defaults + +The following fields are set by default on a sidecar service registration. With +[the exceptions noted](#limitations) any field may be overridden explicitly in +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 `-sidecar-proxy`. This value cannot + be overridden as it is used to [manage the lifecycle](#lifecycle) of the + registration. +- `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 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 + `check` or `checks` fields are set, only the provided checks are registered. +- `proxy.destination_service_name` - Defaults to the parent service name. +- `proxy.destination_service_id` - Defaults to the parent service ID. +- `proxy.local_service_address` - Defaults to `127.0.0.1`. +- `proxy.local_service_port` - Defaults to the parent service port. + +### Example with overwritten configurations + +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: + +```json +{ + "name": "web", + "port": 8080, + "connect": { + "sidecar_service": { + "proxy": { + "upstreams": [ + { + "destination_name": "db", + "local_bind_port": 9191 + } + ], + "config": { + "handshake_timeout_ms": 1000 + } + } + } + } +} +``` + +## Limitations + +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 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 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 + +Sidecar service registration is mostly a configuration syntax helper to avoid +adding lots of boiler plate for basic sidecar options, however the agent does +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, which enables the following behavior. + +- 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 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 are + registered. The old instance and proxy are removed because they are no longer found in + the configuration files. \ No newline at end of file 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 ff344e56d2d2..f5e334876c12 100644 --- a/website/content/docs/connect/proxies/index.mdx +++ b/website/content/docs/connect/proxies/index.mdx @@ -1,29 +1,77 @@ --- layout: docs -page_title: Service Mesh Proxy Overview +page_title: Service mesh proxy overview description: >- In Consul service mesh, each service has a sidecar proxy that secures connections with other services in the mesh without modifying the underlying application code. You can use the built-in proxy, Envoy, or a custom proxy to handle communication and verify TLS connections. --- -# Service Mesh Proxy Overview +# Service mesh proxy overview -Proxies enable unmodified applications to connect to other services in the service mesh. A -per-service proxy sidecar transparently handles inbound and outbound service -connections, automatically wrapping and verifying TLS connections. Consul -ships with a built-in L4 proxy and has first class support for Envoy. You -can plug other proxies into your environment as well. This section describes how to -configure Envoy or the built-in proxy using Consul service mesh, and how to integrate the -proxy of your choice. +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. -To ensure that services only allow external connections established through -the service mesh protocol, you should configure all services to only accept connections on a loopback address. +## Proxy use cases -## Dynamic upstreams require native integration +You can configure proxies to perform several different types of functions in Consul. -Service mesh proxies do not support dynamic upstreams. +### Service mesh proxies -If an application requires dynamic dependencies that are only available -at runtime, you must [natively integrate](/consul/docs/connect/native) -the application with Consul service mesh. After natively integrating, the HTTP API or -[DNS interface](/consul/docs/services/discovery/dns-static-lookups#service-mesh-enabled-service-lookups) -can be used. \ No newline at end of file +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 + +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 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. + +## Supported proxies + +Consul has first-class support for Envoy proxies, which is a highly configurable open source edge service. Consul configures Envoy by optionally exposing a gRPC service on the local agent that serves Envoy's xDS configuration API. Refer to the following documentation for additional information: + +- [Envoy proxy reference](/consul/docs/connect/proxies/envoy) +- [Envoy API documentation](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-docs/xds_protocol) + +You can use Consul's built-in proxy service that supports L4 network traffic, which is suitable for testing and development but not recommended for production environments. Refer to the [built-in proxy reference](/consul/docs/connect/proxies/built-in) for additional information. + +## Workflow + +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**. 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 + +Service mesh proxies do not support dynamic upstreams. If an application requires dynamic dependencies that are only available at runtime, you must [natively integrate](/consul/docs/connect/native) the application with Consul service mesh. After integration, the application can use the HTTP API or [DNS interface](/consul/docs/services/discovery/dns-static-lookups#service-mesh-enabled-service-lookups) to connect to other services in the mesh. + +## Proxies in Kubernetes-orchestrated networks + +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 + +Refer to the following resources for help using service mesh proxies: + +### Tutorial + +- [Using Envoy with Consul service mesh](/consul/tutorials/developer-mesh/service-mesh-with-envoy-proxy) + +### Usage documentation + +- [Deploy service mesh proxies](/consul/docs/connect/proxies/deploy-service-mesh-proxies) +- [Deploy sidecar proxies](/consul/docs/connect/proxies/deploy-sidecar-services) +- [Extend Envoy proxies](/consul/docs/connect/proxies/envoy-extensions) +- [Integrate custom proxies](/consul/docs/connect/proxies/integrate) + +### Reference documentation + +- [Proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) for additional information. +- [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/registration/service-registration.mdx b/website/content/docs/connect/proxies/proxy-config-reference.mdx similarity index 92% rename from website/content/docs/connect/registration/service-registration.mdx rename to website/content/docs/connect/proxies/proxy-config-reference.mdx index 57050476dcf4..8c2b5fb5c8e7 100644 --- a/website/content/docs/connect/registration/service-registration.mdx +++ b/website/content/docs/connect/proxies/proxy-config-reference.mdx @@ -1,15 +1,14 @@ --- layout: docs -page_title: Register a Service Mesh Proxy Outside of a Service Registration +page_title: Service mesh proxy configuration reference description: >- You can register a service mesh sidecar proxy separately from the registration of the service instance it fronts. Learn about proxy configuration options and how to format them with examples. --- -# Register a Service Mesh Proxy Outside of a Service Registration +# Service mesh proxy configuration This topic describes how to declare a service mesh proxy in a service definition. The `kind` must be declared and information about the service they represent must be provided to function as a Consul service mesh proxy. - ## Configuration Configure a service mesh proxy using the following syntax: @@ -79,7 +78,7 @@ proxy = { -### Sidecar Proxy Configuration +### Sidecar proxy configuration Many service mesh proxies are deployed as sidecars. Sidecar proxies are co-located with the single service instance they represent and proxy all inbound traffic to. @@ -90,9 +89,9 @@ 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 +### Complete configuration example The following example includes values for all available options when registering a proxy instance. @@ -140,7 +139,7 @@ proxy = { -### Proxy Parameters +### Proxy parameters The following table describes all parameters that can be defined in the `proxy` block. @@ -158,7 +157,7 @@ The following table describes all parameters that can be defined in the `proxy` | `mesh_gateway` | Object value that specifies the mesh gateway configuration for the proxy. Refer to [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference) for details. | Optional | None | | `expose` | Object value that specifies a configuration for exposing HTTP paths through the proxy.
    This parameter is only compatible with Envoy proxies.
    Refer to [Expose Paths Configuration Reference](#expose-paths-configuration-reference) for details. | Optional | None | -### Upstream Configuration Reference +### Upstream configuration reference You can configure the service mesh proxy to create listeners for upstream services. The listeners enable the upstream service to accept requests. You can specify the following parameters to configure upstream service listeners. @@ -177,7 +176,7 @@ You can configure the service mesh proxy to create listeners for upstream servic | `config` | Object value that specifies opaque configuration options that will be provided to the proxy instance for the upstream.
    Valid JSON objects are also supported.
    The `config` parameter can specify timeouts, retries, and other proxy-specific features for the given upstream.
    See the [built-in proxy configuration reference](/consul/docs/connect/proxies/built-in#proxy-upstream-config-key-reference) for configuration options when using the built-in proxy.
    If using Envoy as a proxy, see [Envoy configuration reference](/consul/docs/connect/proxies/envoy#proxy-upstream-config-options) | Optional | None | | `mesh_gateway` | Object that defines the mesh gateway configuration for the proxy. Refer to the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference) for configuration details. | Optional | None | -### Upstream Configuration Examples +### Upstream configuration examples Upstreams support multiple destination types. The following examples include information about each implementation. Note that the examples in this topic use snake case, which is a convention that separates words with underscores, because the format is supported in configuration files and API registrations. @@ -280,7 +279,7 @@ local_bind_port = 9090     -## Proxy Modes +## Proxy modes You can configure which mode a proxy operates in by specifying `"direct"` or `"transparent"` in the `mode` parameter. The proxy mode determines the how proxies direct traffic. This feature was added in Consul 1.10.0. @@ -295,7 +294,7 @@ You can also specify an empty string (`""`), which configures the proxy to opera The proxy will default to `direct` mode if a mode cannot be determined from the parent parameters. -### Transparent Proxy Configuration Reference +### Transparent proxy configuration reference The following examples show additional configuration for transparent proxies. @@ -320,13 +319,13 @@ Note that the examples in this topic use snake case, which is a convention that ~> **Note:** Dynamic routing rules such as failovers and redirects do not apply to services dialed directly. Additionally, the connection is proxied using a TCP proxy with a connection timeout of 5 seconds. -### Mesh Gateway Configuration Reference +### Mesh gateway configuration reference The following examples show all possible mesh gateway configurations. Note that the examples in this topic use snake case, which is a convention that separates words with underscores, because the format is supported in configuration files and API registrations. -#### Using a Local/Egress Gateway in the Local Datacenter +#### Using local and egress gateways in the local datacenter ```json { @@ -334,7 +333,7 @@ The following examples show all possible mesh gateway configurations. } ``` -#### Direct to a Remote/Ingress in a Remote Datacenter +#### Direct to remote and ingress services in a remote datacenter ```json { @@ -342,7 +341,7 @@ The following examples show all possible mesh gateway configurations. } ``` -#### Prevent Using a Mesh Gateway +#### Disable a mesh gateway ```json { @@ -350,7 +349,7 @@ The following examples show all possible mesh gateway configurations. } ``` -#### Default Mesh Gateway Mode +#### Specify the default mesh gateway mode ```json { @@ -373,7 +372,7 @@ The following examples show all possible mesh gateway configurations. 3. The `service-defaults` configuration for the service. 4. The `global` `proxy-defaults`. -### Expose Paths Configuration Reference +### Expose paths configuration reference The following examples show possible configurations to expose HTTP paths through Envoy. @@ -383,7 +382,9 @@ Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` f Note that the examples in this topic use snake case, which is a convention that separates words with underscores, because the format is supported in configuration files and API registrations. -#### Expose listeners in Envoy for HTTP and GRPC checks registered with the local Consul agent +#### Expose listeners in Envoy for health checks + +The following example exposes Envoy listeners to HTTP and GRPC checks registered with the local Consul agent: ```json { @@ -393,7 +394,9 @@ Note that the examples in this topic use snake case, which is a convention that } ``` -#### Expose an HTTP listener in Envoy at port 21500 that routes to an HTTP server listening at port 8080 +#### Expose an HTTP listener + +The following example exposes and HTTP listener in Envoy at port `21500` that routes to an HTTP server listening at port `8080`: ```json { @@ -409,7 +412,9 @@ Note that the examples in this topic use snake case, which is a convention that } ``` -#### Expose an HTTP2 listener in Envoy at port 21501 that routes to a gRPC server listening at port 9090 +#### Expose an HTTP2 listener + +The following example expose an HTTP2 listener in Envoy at port `21501` that routes to a gRPC server listening at port `9090`: ```json { @@ -440,15 +445,9 @@ Note that the examples in this topic use snake case, which is a convention that but the proxy registration will not fail. - `protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`. -### Unix Domain Sockets - -The following examples show additional configuration for Unix domain sockets. - -Added in v1.10.0. +### Unix domain sockets -To connect to a service via local Unix Domain Socket instead of a -port, add `local_bind_socket_path` and optionally `local_bind_socket_mode` -to the upstream config for a service: +To connect to a service using a local Unix domain socket instead of a port, add `local_bind_socket_path` and optionally `local_bind_socket_mode` to the upstream config for a service. The following examples show additional configurations for Unix domain sockets: @@ -474,11 +473,9 @@ upstreams = [ -This will cause Envoy to create a socket with the path and mode -provided, and connect that to service-1. +Envoy creates a socket with the specified path and mode and connects to `service-1`. -The mode field is optional, and if omitted will use the default mode -for Envoy. This is not applicable for abstract sockets. See the +The `mode` field is optional. When omitted, Envoy uses the default mode. This is not applicable for abstract sockets. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#envoy-v3-api-msg-config-core-v3-pipe) for details. diff --git a/website/content/docs/connect/registration/index.mdx b/website/content/docs/connect/registration/index.mdx deleted file mode 100644 index 96db32788776..000000000000 --- a/website/content/docs/connect/registration/index.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: docs -page_title: Service Mesh Proxy Registration Overview -description: >- - To make Consul aware of proxies in your service mesh, you must register them. Learn about methods for configuring and registering sidecar proxies. ---- - -# Service Mesh Proxy Overview - -To enable service mesh proxies, you must define and register them with Consul. Proxies are a type of service in Consul that facilitate highly secure communication between services in a service mesh. The topics in the section outline your options for registering service mesh proxies. You can register proxies independently or nested inside a sidecar service registration. - -## Proxy service registration - -To register proxies with independent proxy service registrations, you can define them in either in config files or via the API just like any other service. Learn more about all of the options you can define when registering your proxy service in the [proxy registration documentation](/consul/docs/connect/registration/service-registration). - -## Sidecar service registration - -To reduce the amount of boilerplate needed for a sidecar proxy, -application service definitions may define an inline sidecar service block. This is an opinionated -shorthand for a separate full proxy registration as described above. For a -description of how to configure the sidecar proxy as well as the opinionated defaults, see the [sidecar service registrations -documentation](/consul/docs/connect/registration/sidecar-service). diff --git a/website/content/docs/connect/registration/sidecar-service.mdx b/website/content/docs/connect/registration/sidecar-service.mdx deleted file mode 100644 index 46e14869c31e..000000000000 --- a/website/content/docs/connect/registration/sidecar-service.mdx +++ /dev/null @@ -1,175 +0,0 @@ ---- -layout: docs -page_title: Register a Service Mesh Proxy in a Service Registration -description: >- - You can register a service instance and its sidecar proxy at the same time. Learn about default settings, customizable parameters, limitations, and lifecycle behaviors of the sidecar proxy. ---- - -# Register a Service Mesh Proxy in a Service Registration - -This topic describes how to declare a proxy as a _sidecar_ proxy. -Sidecar proxies run on the same node as the single service instance that they handle traffic for. -They may be on the same VM or running as a separate container in the same network namespace. - -## Configuration - -Add the `connect.sidecar_service` block to your service definition file and specify the parameters to configure sidecar proxy behavior. The `sidecar_service` block is a service definition that can contain most regular service definition fields. Refer to [Limitations](#limitations) for information about unsupported service definition fields for sidecar proxies. - -Consul treats sidecar proxy service definitions as a root-level service definition. All fields are optional in nested -definitions, which default to opinionated settings that are intended to reduce burden of setting up a sidecar proxy. - -## Minimal Example - -To register a service instance with a sidecar, all that's needed is: - -```json -{ - "service": { - "name": "web", - "port": 8080, - "connect": { "sidecar_service": {} } - } -} -``` - -This will register the `web` service as normal, but will also register another -[proxy service](/consul/docs/connect/proxies) with defaults values used. - -The above expands out to be equivalent to the following explicit service -definitions: - -```json -{ - "services": [ - { - "name": "web", - "port": 8080 - }, - { - "name": "web-sidecar-proxy", - "port": 20000, - "kind": "connect-proxy", - "checks": [ - { - "Name": "Connect Sidecar Listening", - "TCP": "127.0.0.1:20000", - "Interval": "10s" - }, - { - "name": "Connect Sidecar Aliasing web", - "alias_service": "web" - } - ], - "proxy": { - "destination_service_name": "web", - "destination_service_id": "web", - "local_service_address": "127.0.0.1", - "local_service_port": 8080 - } - } - ] -} -``` - -Details on how the defaults are determined are [documented -below](#sidecar-service-defaults). - --> **Note:** Sidecar service registrations are only a shorthand for registering -multiple services. Consul will not start up or manage the actual proxy processes -for you. - -## Overridden Example - -The following example shows a service definition where some fields are -overridden to customize the proxy configuration. - -```json -{ - "name": "web", - "port": 8080, - "connect": { - "sidecar_service": { - "proxy": { - "upstreams": [ - { - "destination_name": "db", - "local_bind_port": 9191 - } - ], - "config": { - "handshake_timeout_ms": 1000 - } - } - } - } -} -``` - -This example customizes the [proxy -upstreams](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) -and some [built-in proxy -configuration](/consul/docs/connect/proxies/built-in). - -## Sidecar Service Defaults - -The following fields are set by default on a sidecar service registration. With -[the exceptions noted](#limitations) any field may be overridden explicitly in -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 - be overridden as it is used to [manage the lifecycle](#lifecycle) of the - registration. -- `name` - Defaults to being `-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. -- `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 - `check` or `checks` fields are set, only the provided checks are registered. -- `proxy.destination_service_name` - Defaults to the parent service name. -- `proxy.destination_service_id` - Defaults to the parent service ID. -- `proxy.local_service_address` - Defaults to `127.0.0.1`. -- `proxy.local_service_port` - Defaults to the parent service port. - -## Limitations - -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 - 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 - an error to register a `connect-proxy` that is also service mesh-native. - -## Lifecycle - -Sidecar service registration is mostly a configuration syntax helper to avoid -adding lots of boiler plate for basic sidecar options, however the agent does -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. - -- 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 - one. - - If a service registration removes the nested `sidecar_service` then the - previously registered sidecar for that service will be 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. 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 4614a4b26808..7c6a522df547 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 f1e7c590c455..ce09e9d1c441 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 diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 8bb99505b7c9..d72338edfe41 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -479,15 +479,19 @@ ] }, { - "title": "Supported Proxies", + "title": "Proxies", "routes": [ { "title": "Overview", "path": "connect/proxies" }, { - "title": "Envoy", - "path": "connect/proxies/envoy" + "title": "Deploy service mesh proxies", + "path": "connect/proxies/deploy-service-mesh-proxies" + }, + { + "title": "Deploy sidecar services", + "path": "connect/proxies/deploy-sidecar-services" }, { "title": "Envoy Extensions", @@ -549,29 +553,24 @@ ] }, { - "title": "Built-in Proxy", - "path": "connect/proxies/built-in" + "title": "Proxy integration", + "path": "connect/proxies/integrate" }, { - "title": "Proxy Integration", - "path": "connect/proxies/integrate" - } - ] - }, - { - "title": "Registering Proxies", - "routes": [ + "title": "Proxy defaults configuration reference", + "href": "/consul/docs/connect/config-entries/proxy-defaults" + }, { - "title": "Overview", - "path": "connect/registration" + "title": "Envoy proxies reference", + "path": "connect/proxies/envoy" }, { - "title": "Proxy Service Registration", - "path": "connect/registration/service-registration" + "title": "Built-in proxy reference", + "path": "connect/proxies/built-in" }, { - "title": "Sidecar Service Registration", - "path": "connect/registration/sidecar-service" + "title": "Service mesh proxy configuration reference", + "path": "connect/proxies/proxy-config-reference" } ] }, diff --git a/website/redirects.js b/website/redirects.js index bfb3cb693d74..1bf907feff0f 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -61,8 +61,7 @@ module.exports = [ permanent: true, }, { - source: - '/consul/docs/enterprise/sentinel', + source: '/consul/docs/enterprise/sentinel', destination: '/consul/docs/dynamic-app-config/kv#using-sentinel-to-apply-policies-for-consul-kv', permanent: true, @@ -70,8 +69,22 @@ module.exports = [ { source: '/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters', - destination: - '/consul/docs/k8s/deployment-configurations/multi-cluster', + destination: '/consul/docs/k8s/deployment-configurations/multi-cluster', + permanent: true, + }, + { + source: '/consul/docs/connect/registration/service-registration', + destination: '/consul/docs/connect/proxies/proxy-config-reference', + permanent: true, + }, + { + source: '/consul/docs/connect/registration', + destination: '/consul/docs/connect/proxies/', + permanent: true, + }, + { + source: '/consul/docs/connect/registration/sidecar-service', + destination: '/consul/docs/connect/proxies/deploy-sidecar-services', permanent: true, - } + }, ]