diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index 1d94a79389b6..05e5de30f7e8 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -1,178 +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. - -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). +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). -## Usage +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. -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 model -## Configuration - -Configure the following parameters to define a `proxy-defaults` configuration entry: +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. - - - -```hcl -Kind = "proxy-defaults" -Name = "global" -Meta { - = "" -} -Config { - = -} -Mode = "" -TransparentProxy { - OutboundListenerPort = - DialedDirectly = -} -MutualTLSMode = "" -MeshGateway { - Mode = "" -} -Expose { - Checks = + + +- [`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 - 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 >" -} -``` + + + +- [`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 -```yaml -apiVersion: consul.hashicorp.com/v1alpha1 -kind: ProxyDefaults -metadata: - name: global -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 > -``` + -```json -{ - "Kind": "proxy-defaults", - "Name": "global", - "Meta": { - "": "" - }, - "Config": { - "": - }, - "MutualTLSMode": "", - "Mode": "", - "TransparentProxy": { - "OutboundListenerPort": , - "DialedDirectly": - }, - "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 >" - } -} -``` + - +## Complete configuration - - +When every field is defined, a proxy defaults configuration entry has the following form: --> **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". +Namespace = "default" Meta { = "" } Config { = } +EnvoyExtensions = [ + { + Name= "" + Required = "required" + Arguments = "" + ConsulVersion = "" + EnvoyVersion = "" + } +] Mode = "" TransparentProxy { OutboundListenerPort = @@ -203,6 +160,9 @@ AccessLogs { TextFormat = "< text representation of access log format >" } ``` + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 @@ -215,6 +175,12 @@ spec: : config: : + EnvoyExtensions: + - name: + required: required + arguments: + consulVersion: + envoyVersion: mode: transparentProxy: outboundListenerPort: @@ -238,6 +204,10 @@ spec: textFormat: < text representation of access log format > ``` + + + + ```json { "Kind": "proxy-defaults", @@ -249,6 +219,15 @@ spec: "Config": { "": }, + "EnvoyExtensions": [ + { + "Name": "", + "Required": "required", + "Arguments": "", + "ConsulVersion": "", + "EnvoyVersion": "" + } + ], "Mode": "", "TransparentProxy": { "OutboundListenerPort": , @@ -280,288 +259,486 @@ spec: } ``` - - + -### Configuration Parameters +## Specification -: 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. - `, - }, - { - 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.`, - } - ], - }, - ]} -/> +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 of + +### `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: Map 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 | + +### `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. 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`](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual) tagged address, which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader. | Boolean | `false` | + +### `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 Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. + +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 + +### `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 | + +
    + + + +### apiVersion + +Specifies the verion of the Consul API to use to apply the configuration entry. This must be set to `consul.hashicorp.com/v1alpha1`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `consul.hashicorp.com/v1alpha1`. + +### `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: Map 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. 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`](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual) tagged address, which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader. | Boolean | `false` | + +### `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 Consul's [`advertise_addr`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the agent's [`expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations. + +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 | + +
    + +
    ## 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 +748,24 @@ Config { } ``` +#### Consul Enterprise + +For Consul Enterprise, you can only create the configuration entry in the `default` namespace. The namepace configuration applies to proxies in all namespaces. + +```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 +776,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" -} -``` +For Consul Enterprise, you can only create the configuration entry in the `default` namespace. The namepace configuration applies to proxies in all namespaces. ```yaml apiVersion: consul.hashicorp.com/v1alpha1 @@ -621,27 +791,46 @@ spec: protocol: http ``` + + + + +#### Community edition + ```json { "Kind": "proxy-defaults", "Name": "global", - "Namespace": "default", "Config": { "protocol": "http" } } ``` +#### Consul Enterprise + +For Consul Enterprise, you can only create the configuration entry in the `default` namespace. The namepace configuration applies to proxies in all namespaces. - +```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 +840,11 @@ Config { } ``` + + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -661,6 +855,10 @@ spec: envoy_prometheus_bind_addr: '0.0.0.0:9102' ``` + + + + ```json { "Kind": "proxy-defaults", @@ -671,14 +869,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. efer to [access logs](/consul/docs/connect/observability/access-logs) for more detailed examples. + + + - ```hcl Kind = "proxy-defaults" @@ -688,6 +889,10 @@ AccessLogs { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -698,6 +903,10 @@ spec: enabled: true ``` + + + + ```json { "Kind": "proxy-defaults", @@ -708,13 +917,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 +937,10 @@ Config { } ``` + + + + ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ProxyDefaults @@ -736,6 +952,10 @@ spec: handshake_timeout_ms: 10000 ``` + + + + ```json { "Kind": "proxy-defaults", @@ -747,13 +967,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/proxies/deploy-service-mesh-proxies.mdx b/website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx new file mode 100644 index 000000000000..60d9cc5ab745 --- /dev/null +++ b/website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx @@ -0,0 +1,77 @@ +--- +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 deployed sidecar proxies, 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. + +## Requirements + +If [ACLs](/consul/docs/security/acl) are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information. + +## 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 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..23e7a6238aa1 --- /dev/null +++ b/website/content/docs/connect/proxies/deploy-sidecar-services.mdx @@ -0,0 +1,286 @@ +--- +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 functionalities. 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](/consul/docs/security/acl) are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information. + +## 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. Specify a name for the service you want to attach a sidecar proxy to in the `name` field. This field is required for all services you want to register in Consul. +1. Specify a port number where other services registered with Consul can discover and connect to the service in the `port` field. This field is required for all services you want to register in Consul. +1. Set the `connect` field to `{ sidecar_service: {} }`. The `{ sidecar_service: {} }` value is a macro that applies a set of default configurations that enable you to quickly implement a sidecar. Refer to [Sidecar service defaults](#sidecar-service-defaults) for additional information. +1. 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 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. + +### Example with overwritten configurations + +In the following example, but 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. 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. \ No newline at end of file diff --git a/website/content/docs/connect/proxies/index.mdx b/website/content/docs/connect/proxies/index.mdx index ff344e56d2d2..eeea3305f214 100644 --- a/website/content/docs/connect/proxies/index.mdx +++ b/website/content/docs/connect/proxies/index.mdx @@ -1,29 +1,73 @@ --- 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 +_Proxies_ are services that you can configure to perform several different types of functions in Consul. -Service mesh proxies do not support dynamic upstreams. +### Sidecars -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 +You can configure proxies to operate as sidecar services transparently handles inbound and outbound service connections. Sidecars also automatically wrap and verify TLS connections. Each service in your mesh should have its own sidecar proxy. + +Refer to [Deploy sidecar services](/consul/docs/connect/proxies/deploy-sidecar-services) for additional information. + +### Gateways + +You can configure proxies to operate as gateway services, which allow service-to-service traffic across different network areas, including peered clusters, WAN-federated datacenters, and nodes outside the mesh. Consul ships with several types of gateway capabilities, but gateways deliver the underlying functionality. + +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**. + +### 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 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 93% rename from website/content/docs/connect/registration/service-registration.mdx rename to website/content/docs/connect/proxies/proxy-config-reference.mdx index 57050476dcf4..dc3765b8cdb5 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. @@ -92,7 +91,7 @@ Specify the following parameters in the `proxy` code block to configure a sideca See [Sidecar Service Registration](/consul/docs/connect/registration/sidecar-service) 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/data/docs-nav-data.json b/website/data/docs-nav-data.json index 6d8926592c4e..5cd454d4f9e1 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", @@ -541,29 +545,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 52712feeed5a..c6dde36160ea 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -69,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, + }, ]