luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Add docs for transparent proxy mode and config (#10038) 

Add docs for transparent proxy mode and config

Co-authored-by: Nitya Dhanushkodi <nitya@hashicorp.com>
Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
Co-authored-by: Iryna Shustava <ishustava@users.noreply.github.com>
Co-authored-by: Jeff Escalante <jescalan@users.noreply.github.com>
This commit is contained in:
Freddy 2021-04-16 13:50:02 -06:00 committed by GitHub
parent 1758a6dc54
commit ba055db83d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 955 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/api-docs/agent/service.mdx
View File

@ -88,7 +88,7 @@ The filter is executed against each value in the service mapping with the
following selectors and filter operations being supported:
| Selector | Supported Operations |
| -------------------------------------- | -------------------------------------------------- |
| --------------------------------------------- | -------------------------------------------------- |
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Connect.Native` | Equal, Not Equal |
| `EnableTagOverride` | Equal, Not Equal |
@ -101,6 +101,8 @@ following selectors and filter operations being supported:
| `Proxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.LocalServicePort` | Equal, Not Equal |
| `Proxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
| `Proxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.Upstreams` | Is Empty, Is Not Empty |
| `Proxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
@ -196,6 +198,10 @@ $ curl \
"DestinationServiceID": "web",
"LocalServiceAddress": "127.0.0.1",
"LocalServicePort": 8080,
"Mode": "transparent",
"TransparentProxy": {
"OutboundListenerPort": 22500
},
"Config": {
"foo": "bar"
},

42
website/content/api-docs/catalog.mdx
View File

@ -104,7 +104,7 @@ and vice versa. A catalog entry can have either, neither, or both.
{
"Datacenter": "dc1",
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Node": "t2.320",
"Address": "192.168.10.10",
"TaggedAddresses": {
"lan": "192.168.10.10",
@ -135,7 +135,7 @@ and vice versa. A catalog entry can have either, neither, or both.
"Namespace": "default"
},
"Check": {
"Node": "foobar",
"Node": "t2.320",
"CheckID": "service:redis1",
"Name": "Redis health check",
"Notes": "Script based health check",
@ -211,14 +211,14 @@ The behavior of the endpoint depends on what keys are provided.
```json
{
"Datacenter": "dc1",
"Node": "foobar"
"Node": "t2.320"
}
```
```json
{
"Datacenter": "dc1",
"Node": "foobar",
"Node": "t2.320",
"CheckID": "service:redis1",
"Namespace": "team-1"
}
@ -227,7 +227,7 @@ The behavior of the endpoint depends on what keys are provided.
```json
{
"Datacenter": "dc1",
"Node": "foobar",
"Node": "t2.320",
"ServiceID": "redis1",
"Namespace": "team-1"
}
@ -344,7 +344,7 @@ $ curl \
},
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Node": "foobar",
"Node": "t2.320",
"Address": "10.1.10.12",
"Datacenter": "dc2",
"TaggedAddresses": {
@ -485,7 +485,7 @@ The table below shows this endpoint's support for
```shell-session
$ curl \
http://127.0.0.1:8500/v1/catalog/service/my-service?ns=default
http://127.0.0.1:8500/v1/catalog/service/web?ns=default
```
### Sample Response
@ -494,7 +494,7 @@ $ curl \
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Node": "t2.320",
"Address": "192.168.10.10",
"Datacenter": "dc1",
"TaggedAddresses": {
@ -509,10 +509,10 @@ $ curl \
"ServiceAddress": "172.17.0.3",
"ServiceEnableTagOverride": false,
"ServiceID": "32a2a47f7992:nodea:5000",
"ServiceName": "foobar",
"ServiceName": "web",
"ServicePort": 5000,
"ServiceMeta": {
"foobar_meta_value": "baz"
"web_meta_value": "baz"
},
"ServiceTaggedAddresses": {
"lan": {
@ -524,7 +524,7 @@ $ curl \
"port": 512
}
},
"ServiceTags": ["tacos"],
"ServiceTags": ["prod"],
"ServiceProxy": {
"DestinationServiceName": "",
"DestinationServiceID": "",
@ -597,7 +597,7 @@ Filtering is executed against each entry in the top level result list with the
following selectors and filter operations being supported:
| Selector | Supported Operations |
| --------------------------------------------- | -------------------------------------------------- |
| ---------------------------------------------------- | -------------------------------------------------- |
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
@ -617,6 +617,8 @@ following selectors and filter operations being supported:
| `ServiceProxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceProxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceProxy.LocalServicePort` | Equal, Not Equal |
| `ServiceProxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceProxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
| `ServiceProxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceProxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceProxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
@ -698,7 +700,7 @@ $ curl \
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Node": "t2-node",
"Address": "10.1.10.12",
"Datacenter": "dc1",
"TaggedAddresses": {
@ -747,7 +749,7 @@ The filter will be executed against each value in the `Services` mapping within
top level Node object. The following selectors and filter operations are supported:
| Selector | Supported Operations |
| -------------------------------------- | -------------------------------------------------- |
| --------------------------------------------- | -------------------------------------------------- |
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Connect.Native` | Equal, Not Equal |
| `EnableTagOverride` | Equal, Not Equal |
@ -760,6 +762,8 @@ top level Node object. The following selectors and filter operations are support
| `Proxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.LocalServicePort` | Equal, Not Equal |
| `Proxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
| `Proxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.Upstreams` | Is Empty, Is Not Empty |
| `Proxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |
@ -817,7 +821,7 @@ The table below shows this endpoint's support for
```shell-session
$ curl \
http://127.0.0.1:8500/v1/catalog/node-services/my-node
http://127.0.0.1:8500/v1/catalog/node-services/t2-node
```
### Sample Response
@ -826,7 +830,7 @@ $ curl \
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Node": "t2-node",
"Address": "10.1.10.12",
"Datacenter": "dc1",
"TaggedAddresses": {
@ -851,7 +855,7 @@ $ curl \
"TaggedAddresses": {
"lan": {
"address": "10.1.10.12",
"port": 8000,
"port": 8000
},
"wan": {
"address": "198.18.1.2",
@ -877,7 +881,7 @@ The filter will be executed against each value in the `Services` list within the
top level object. The following selectors and filter operations are supported:
| Selector | Supported Operations |
| -------------------------------------- | -------------------------------------------------- |
| --------------------------------------------- | -------------------------------------------------- |
| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Connect.Native` | Equal, Not Equal |
| `EnableTagOverride` | Equal, Not Equal |
@ -890,6 +894,8 @@ top level object. The following selectors and filter operations are supported:
| `Proxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.LocalServicePort` | Equal, Not Equal |
| `Proxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
| `Proxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Proxy.Upstreams` | Is Empty, Is Not Empty |
| `Proxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |

4
website/content/api-docs/health.mdx
View File

@ -345,7 +345,7 @@ The filter will be executed against each entry in the top level results list wit
following selectors and filter operations being supported:
| Selector | Supported Operations |
| ---------------------------------------------- | -------------------------------------------------- |
| ----------------------------------------------------- | -------------------------------------------------- |
| `Checks` | Is Empty, Is Not Empty |
| `Checks.CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Checks.Name` | Equal, Not Equal, In, Not In, Matches, Not Matches |
@ -376,6 +376,8 @@ following selectors and filter operations being supported:
| `Service.Proxy.DestinationServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Service.Proxy.LocalServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Service.Proxy.LocalServicePort` | Equal, Not Equal |
| `Service.Proxy.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Service.Proxy.TransparentProxy.OutboundListenerPort` | Equal, Not Equal |
| `Service.Proxy.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Service.Proxy.Upstreams` | Is Empty, Is Not Empty |
| `Service.Proxy.Upstreams.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches |

2
website/content/commands/connect/redirect-traffic.mdx
View File

@ -32,7 +32,7 @@ Usage: `consul connect redirect-traffic [options]`
#### API Options
@include 'http_api_options_client.mdx'
@include 'http_api_options_client.mdx'
#### Options for Traffic Redirection Rules

77
website/content/docs/connect/config-entries/cluster.mdx Normal file
View File

@ -0,0 +1,77 @@
---
layout: docs
page_title: 'Configuration Entry Kind: Cluster'
description: >-
The cluster config entry kind allows for globally defining default
configuration across all services mesh proxies.
Settings in this config entry apply across all namespaces and federated datacenters.
Currently, only one cluster entry is supported.
---
# Cluster <sup>Beta</sup>
-> **v1.10.0+:** This config entry is supported in Consul versions 1.10.0+.
The `cluster` config entry kind allows for globally defining
default configuration that applies to all service mesh proxies.
Settings in this config entry apply across all namespaces and federated datacenters.
## Sample Config Entries
### Proxy traffic to catalog destinations only
<Tabs>
<Tab heading="HCL">
```hcl
Kind = "cluster"
Name = "cluster"
TransparentProxy {
CatalogDestinationsOnly = true
}
```
</Tab>
<Tab heading="HCL (Consul Enterprise)">
**NOTE:** The `cluster` config entry can only be created in the `default`
namespace and it will apply to proxies across **all** namespaces.
```hcl
Kind = "cluster"
Name = "cluster"
Namespace = "default" # Can only be set to "default".
TransparentProxy {
CatalogDestinationsOnly = true
}
```
</Tab>
</Tabs>
## Available Fields
- `Kind` - Must be set to `cluster`
- `Name` `(string: <required>)` - Must be set to `cluster`
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to.
Must be set to `default`
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs.
- `TransparentProxy` `(TransparentProxyConfig: <optional>)` - Controls configuration specific to proxies in
`transparent` [mode](/docs/connect/config-entries/service-defaults#mode). Added in v1.10.0.
- `CatalogDestinationsOnly` `(bool: false)` - Determines whether sidecar proxies operating in transparent mode can
proxy traffic to IP addresses not registered in Consul's catalog. If enabled, traffic will only be proxied
to upstreams with service registrations in the catalog.
## ACLs
Configuration entries may be protected by [ACLs](/docs/security/acl).
Reading a `cluster` config entry requires no specific privileges.
Creating, updating, or deleting a `cluster` config entry requires
`operator:write`.

3
website/content/docs/connect/config-entries/index.mdx
View File

@ -12,6 +12,9 @@ Configuration entries can be used to configure the behavior of Consul Connect.
The following configuration entries are supported:
- [Cluster](/docs/connect/config-entries/cluster) <sup>Beta</sup> - controls
cluster-wide configuration that applies across namespaces and federated datacenters.
- [Ingress Gateway](/docs/connect/config-entries/ingress-gateway) - defines the
configuration for an ingress gateway

26
website/content/docs/connect/config-entries/proxy-defaults.mdx
View File

@ -210,6 +210,32 @@ spec:
<ul><li>[Envoy](/docs/connect/proxies/envoy#bootstrap-configuration)</li>
<li>[Consul's built-in proxy](/docs/connect/proxies/built-in)</li></ul>`,
},
{
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.`,
yaml: false,
},
{
name: 'TransparentProxy',
type: 'TransparentProxyConfig: <optional>',
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.`,
},
],
yaml: false,
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',

347
website/content/docs/connect/config-entries/service-defaults.mdx
View File

@ -47,6 +47,81 @@ spec:
</Tab>
</Tabs>
### Upstream configuration <sup>Beta</sup>
<Tabs>
<Tab heading="HCL">
Set default connection limits and mesh gateway mode across all upstreams
of "counting" and also override the mesh gateway mode used when dialing
the "dashboard" service in the "frontend" namespace.
```hcl
Kind = "service-defaults"
Name = "counting"
UpstreamConfig = {
Defaults = {
MeshGateway = {
Mode = "local"
}
Limits = {
MaxConnections = 512
MaxPendingRequests = 512
MaxConcurrentRequests = 512
}
}
Overrides = [
{
Name = "dashboard"
MeshGateway = {
Mode = "remote"
}
}
]
}
```
</Tab>
<Tab heading="HCL (Consul Enterprise)">
Set default connection limits and mesh gateway mode across all upstreams
of "counting" and also override the mesh gateway mode used when dialing
the "dashboard" service in the "frontend" namespace.
```hcl
Kind = "service-defaults"
Name = "counting"
Namespace = "product"
UpstreamConfig = {
Defaults = {
MeshGateway = {
Mode = "local"
}
Limits = {
MaxConnections = 512
MaxPendingRequests = 512
MaxConcurrentRequests = 512
}
}
Overrides = [
{
Name = "dashboard"
Namespace = "frontend"
MeshGateway = {
Mode = "remote"
}
}
]
}
```
</Tab>
</Tabs>
## Available Fields
<ConfigEntryReference
@ -109,6 +184,278 @@ spec:
[\`service-intentions\`](/docs/connect/config-entries/service-intentions).
Supported values are one of \`tcp\`, \`http\`, \`http2\`, or \`grpc\`.`,
},
{
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.`,
yaml: false,
},
{
name: 'UpstreamConfig',
type: 'UpstreamConfiguration: <optional>',
description: `Controls default configuration settings that apply across all upstreams, and per-upstream
configuration overrides. Note that per-upstream configuration applies across all federated datacenters
to the pairing of source and upstream destination services.
Added in v1.10.0.`,
children: [
{
name: 'Overrides',
type: 'array<UpstreamConfig>: []',
description: `A list of optional overrides for per-upstream configuration.`,
children: [
{
name: 'Name',
type: 'string: ""',
description:
'The upstream name to apply the configuration to.',
},
{
name: 'Namespace',
type: 'string: ""',
description:
'The namespace of the upstream.',
},
{
name: 'Protocol',
type: 'string: ""',
description:
`The protocol for the upstream listener.
NOTE: The protocol of a service should ideally be configured via the
[\`protocol\`](/docs/connect/config-entries/service-defaults#protocol)
field of a
[\`service-defaults\`](/docs/connect/config-entries/service-defaults)
config entry for the upstream destination service. Configuring it in a
proxy upstream config will not fully enable some
[L7 features](/docs/connect/l7-traffic-management).
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
`,
},
{
name: 'ConnectTimeoutMs',
type: 'int: 5000',
description:
`The number of milliseconds to allow when making upstream connections before timing out.
NOTE: The connect timeout of a service should ideally be configured via the
[\`connect_timeout\`](/docs/connect/config-entries/service-resolver#connecttimeout)
field of a
[\`service-resolver\`](/docs/connect/config-entries/service-resolver)
config entry for the upstream destination service.
Configuring it in a proxy upstream config will not fully enable some
[L7 features](/docs/connect/l7-traffic-management).
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
`,
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',
description: `Controls the default
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration)
for this upstream.`,
children: [
{
name: 'Mode',
type: 'string: ""',
description: 'One of `none`, `local`, or `remote`.',
},
],
},
{
name: 'Limits',
type: 'Limits: <optional>',
description: `A set of limits to apply when connecting to the upstream service.
These limits are applied on a per-service-instance basis.
The following limits are respected.`,
children: [
{
name: 'MaxConnections',
type: 'int: 0',
description: `The maximum number of connections a service instance
will be allowed to establish against the given upstream. Use this to limit
HTTP/1.1 traffic, since HTTP/1.1 has a request per connection.`,
},
{
name: 'MaxPendingRequests',
type: 'int: 0',
description: `The maximum number of requests that will be queued
while waiting for a connection to be established. For this configuration to
be respected, a L7 protocol must be defined in the \`protocol\` field.`,
},
{
name: 'MaxConcurrentRequests',
type: 'int: 0',
description: `The maximum number of concurrent requests that
will be allowed at a single point in time. Use this to limit HTTP/2 traffic,
since HTTP/2 has many requests per connection. For this configuration to be
respected, a L7 protocol must be defined in the \`protocol\` field.`,
},
],
},
{
name: 'PassiveHealthCheck',
type: 'PassiveHealthCheck: <optional>',
description: `Passive health checks are used to remove hosts from
the upstream cluster which are unreachable or are returning errors..`,
children: [
{
name: 'Interval',
type: 'duration: 0s',
description: `The time between checks. Each check will cause hosts which
have exceeded \`max_failures\` to be removed from the load balancer, and
any hosts which have passed their ejection time to be returned to the
load balancer.`,
},
{
name: 'MaxFailures',
type: 'int: 0',
description: `The number of consecutive failures which cause a host to be
removed from the load balancer.`,
},
],
},
],
},
{
name: 'Defaults',
type: 'UpstreamConfig: <optional>',
description: `Default configuration that applies to all upstreams of the given service.`,
children: [
{
name: 'Name',
type: 'string: ""',
description:
'The upstream name to apply the configuration to.',
},
{
name: 'Namespace',
type: 'string: ""',
description:
'The namespace of the upstream.',
},
{
name: 'Protocol',
type: 'string: ""',
description:
`The protocol for the upstream listener.
NOTE: The protocol of a service should ideally be configured via the
[\`protocol\`](/docs/connect/config-entries/service-defaults#protocol)
field of a
[\`service-defaults\`](/docs/connect/config-entries/service-defaults)
config entry for the upstream destination service. Configuring it in a
proxy upstream config will not fully enable some
[L7 features](/docs/connect/l7-traffic-management).
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
`,
},
{
name: 'ConnectTimeoutMs',
type: 'int: 5000',
description:
`The number of milliseconds to allow when making upstream connections before timing out.
NOTE: The connect timeout of a service should ideally be configured via the
[\`connect_timeout\`](/docs/connect/config-entries/service-resolver#connecttimeout)
field of a
[\`service-resolver\`](/docs/connect/config-entries/service-resolver)
config entry for the upstream destination service.
Configuring it in a proxy upstream config will not fully enable some
[L7 features](/docs/connect/l7-traffic-management).
It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
`,
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',
description: `Controls the default
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration)
for this upstream.`,
children: [
{
name: 'Mode',
type: 'string: ""',
description: 'One of `none`, `local`, or `remote`.',
},
],
},
{
name: 'Limits',
type: 'Limits: <optional>',
description: `A set of limits to apply when connecting to the upstream service.
These limits are applied on a per-service-instance basis.
The following limits are respected.`,
children: [
{
name: 'MaxConnections',
type: 'int: 0',
description: `The maximum number of connections a service instance
will be allowed to establish against the given upstream. Use this to limit
HTTP/1.1 traffic, since HTTP/1.1 has a request per connection.`,
},
{
name: 'MaxPendingRequests',
type: 'int: 0',
description: `The maximum number of requests that will be queued
while waiting for a connection to be established. For this configuration to
be respected, a L7 protocol must be defined in the \`protocol\` field.`,
},
{
name: 'MaxConcurrentRequests',
type: 'int: 0',
description: `The maximum number of concurrent requests that
will be allowed at a single point in time. Use this to limit HTTP/2 traffic,
since HTTP/2 has many requests per connection. For this configuration to be
respected, a L7 protocol must be defined in the \`protocol\` field.`,
},
],
},
{
name: 'PassiveHealthCheck',
type: 'PassiveHealthCheck: <optional>',
description: `Passive health checks are used to remove hosts from
the upstream cluster which are unreachable or are returning errors..`,
children: [
{
name: 'Interval',
type: 'duration: 0s',
description: `The time between checks. Each check will cause hosts which
have exceeded \`max_failures\` to be removed from the load balancer, and
any hosts which have passed their ejection time to be returned to the
load balancer.`,
},
{
name: 'MaxFailures',
type: 'int: 0',
description: `The number of consecutive failures which cause a host to be
removed from the load balancer.`,
},
],
},
],
},
],
},
{
name: 'TransparentProxy',
type: 'TransparentProxyConfig: <optional>',
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 redirected to.`,
},
],
yaml: false,
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',

38
website/content/docs/connect/registration/service-registration.mdx
View File

@ -81,6 +81,8 @@ registering a proxy instance.
"destination_service_id": "redis1",
"local_service_address": "127.0.0.1",
"local_service_port": 9090,
"mode": "transparent",
"transparent_proxy": {},
"config": {},
"upstreams": [],
"mesh_gateway": {},
@ -115,6 +117,22 @@ registering a proxy instance.
Defaults to the port advertised by the service instance identified by
`destination_service_id` if it exists otherwise it may be empty in responses.
- `mode` `(string: "")` <sup>Beta</sup> - One of \`direct\` or \`transparent\`. Added in v1.10.0.
- `"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.
- `""` - Default mode. The default mode will be `"direct"` if no other configuration
applies. The order of precedence for setting the mode is
1. Proxy Service's `Proxy` configuration
2. The `service-defaults` configuration for the service.
3. The `global` `proxy-defaults`.
- `transparent_proxy` `(object: {})` <sup>Beta</sup> - Specifies the configuration specific to proxies in `transparent` mode.
The format is defined in the [Transparent Proxy Configuration Reference](#transparent-proxy-configuration-reference).
Added in v1.10.0.
- `config` `(object: {})` - Specifies opaque config JSON that will be
stored and returned along with the service instance from future API calls.
@ -194,6 +212,26 @@ followed by documentation for each attribute.
- `mesh_gateway` `(object: {})` - Specifies the mesh gateway configuration
for this proxy. The format is defined in the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference).
### Transparent Proxy Configuration Reference <sup>Beta</sup>
The following examples show additional configuration for transparent proxies.
Added in v1.10.0.
-> Note that `snake_case` is used here as it works in both [config file and API
registrations](/docs/agent/services#service-definition-parameter-case).
#### Configure a proxy listener for outbound traffic on port 22500
```json
{
"outbound_listener_port": 22500
}
```
- `outbound_listener_port` `(int: 15001)` - The port the proxy should listen on for outbound traffic.
This must be the port where outbound application traffic is captured and redirected to.
### Mesh Gateway Configuration Reference
The following examples show all possible mesh gateway configurations.

238
website/content/docs/connect/transparent-proxy.mdx Normal file
View File

@ -0,0 +1,238 @@
---
layout: docs
page_title: Connect - Transparent Proxy
sidebar_title: Transparent Proxy <sup>Beta</sup>
description: |-
Transparent proxy is used to direct inbound and outbound traffic to services via the Envoy proxy and configure
upstreams via intentions.
---
# Transparent Proxy <sup>Beta</sup>
Transparent proxy allows users to reach other services in the service mesh while ensuring that inbound and outbound
traffic for services in the mesh are directed through the sidecar proxy. This makes it more likely that traffic is secure
and only reaches intended destinations since the proxy can enforce security and policy like TLS and Service Intentions.
Previously, service mesh users would need to explicitly define upstreams for a service as a local listener on the sidecar
proxy, and dial the local listener to reach the appropriate upstream. Users would also have to set intentions to allow
specific services to talk to one another. Transparent proxying reduces this duplication, by determining upstreams
implicitly from Service Intentions. Explicit upstreams are still supported in the [proxy service
registration](/docs/connect/registration/service-registration) on VMs and via the
[annotation](/docs/k8s/connect#consul-hashicorp-com-connect-service-upstreams) in Kubernetes.
To support transparent proxying, Consul now supports a command
[`consul connect redirect-traffic`](/commands/connect/redirect-traffic) to redirect traffic through an inbound and
outbound listener on the sidecar. It also watches Service Intentions and configures the Envoy proxy with the appropriate
upstream IPs. If the default ACL policy is "allow", then Service Intentions are not required. In Consul on Kubernetes,
the traffic redirection command is automatically set up via an init container.
## Prerequisites
Transparent proxy requires Consul >= `1.10.0`.
### Kubernetes
* To use transparent proxy on Kubernetes, Consul-helm >= `0.32.0` and Consul-k8s >= `0.26.0` are required in addition to
the Consul version requirements.
* If the default policy for ACLs is "deny", then Service Intentions should be set up to allow intended services to connect to each other.
Otherwise, all Connect services can talk to all other services.
The Kubernetes integration takes care of registering Kubernetes services with Consul, injecting a sidecar proxy, and
enabling traffic redirection.
### VMs
* For a service on a VM to be a part of the service mesh, it needs to run a Connect sidecar proxy.
* The [`consul connect redirect-traffic`](/commands/connect/redirect-traffic) command needs to be run on the VM to
set it up to redirect all inbound and outbound traffic to that VM through the sidecar proxy. Note that this will modify
iptables rules on the host which can affect reachability of the VM unless the command is run within a network namespace.
* Services need to be registered with Consul.
* If the default policy for ACLs is "deny", then Service Intentions should be set up to allow intended services to connect to each other.
Otherwise, all Connect services can talk to all other services.
## Configuration
### Kubernetes
Transparent proxy can be enabled in Kubernetes on the whole cluster via the Helm value:
```yaml
connectInject:
transparentProxy:
defaultEnabled: true
```
It can also be enabled on a per service basis via the annotation `consul.hashicorp.com/transparent-proxy=true` on the
Pod for each service:
```yaml
apiVersion: v1
kind: Service
metadata:
name: static-server
spec:
selector:
app: static-server
ports:
- protocol: TCP
port: 80
targetPort: 8080
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: static-server
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: static-server
spec:
replicas: 1
selector:
matchLabels:
app: static-server
template:
metadata:
name: static-server
labels:
app: static-server
annotations:
'consul.hashicorp.com/connect-inject': 'true'
'consul.hashicorp.com/transparent-proxy': 'true'
spec:
containers:
- name: static-server
image: hashicorp/http-echo:latest
args:
- -text="hello world"
- -listen=:8080
ports:
- containerPort: 8080
name: http
serviceAccountName: static-server
```
### VMs
In other environments, transparent proxy can be enabled via Proxy Defaults and Service Defaults config entries, or via
the proxy service registration:
```
# Proxy defaults apply to all proxies.
kind = "proxy-defaults"
name = "global"
mode = "transparent"
transparent_proxy {
outbound_listener_port = 15001
}
```
```
# Service defaults apply to all instances of the web service.
kind = "service-defaults"
name = "web"
mode = "transparent"
transparent_proxy {
outbound_listener_port = 15001
}
```
```
# Proxy service registrations apply to a single proxy instance.
name = "web-sidecar-proxy"
kind = "connect-proxy"
proxy {
mode = "transparent"
transparent_proxy {
outbound_listener_port = 15001
}
destination_service_name = "web"
local_service_port = 8080
}
port = 20000
```
Similar to `mesh_gateway.mode`, the new proxy mode will have the following string values:
* "" - The empty string represents the default value for the feature, and allows for the mode to be overridden by
central configuration, like “service-defaults”.
* "direct" - Explicitly disables configuring transparent proxy, falling back to only configuring explicit upstreams.
* "transparent" - Explicitly enables configuring transparent proxy.
Additionally, the new Cluster config entry is scoped to the set of federated Consul datacenters and can be used to allow or block
traffic to external destinations. This example shows blocking traffic to external destinations (outside of Consul's catalog):
```
kind = "cluster"
name = "cluster"
transparent_proxy {
catalog_destinations_only = true
}
```
## Known Limitations
* For services on VMs, transparent proxy only supports one service per VM, or per network namespace. This is
because the traffic redirection rules are applicable to the entire namespace (including the default namespace) and will
direct all outbound traffic from the service to it’s sidecar proxy.
* Currently transparent proxy is only supported for services within a single Consul datacenter.
## Using Transparent Proxy
### Kubernetes
In Kubernetes, services can reach other services via their
[KubeDNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) address or via Pod IPs, and that
traffic will be transparently sent through the proxy. Connect services in Kubernetes are required to have a Kubernetes
service selecting the Pods.
~> Note: In order to use KubeDNS, the Kubernetes service name will need to match the Consul service name. This will be the
case by default, unless the service Pods have the annotation `consul.hashicorp.com/connect-service` overriding the
Consul service name.
Transparent proxy is enabled by default in Consul-helm >=`0.32.0`. The Helm value used to enable/disable transparent
proxy for all applications in a Kubernetes cluster is `connectInject.transparentProxy.defaultEnabled`.
Each Pod for the service will be configured with iptables rules to direct all inbound and outbound traffic through an
inbound and outbound listener on the sidecar proxy. The proxy will be configured to know how to route traffic to the
appropriate upstream services based on [Service
Intentions](/docs/connect/config-entries/service-intentions). This means Connect services no longer
need to use the `consul.hashicorp.com/connect-service-upstreams` annotation to configure upstreams explicitly. Once the
Service Intentions are set, they can simply address the upstream services using KubeDNS.
As of Consul-k8s >= `0.26.0` and Consul-helm >= `0.32.0`, a Kubernetes service that selects application pods is required
for Connect applications, i.e:
```yaml
apiVersion: v1
kind: Service
metadata:
name: sample-app
namespace: default
spec:
selector:
app: sample-app
ports:
- protocol: TCP
port: 80
```
In the example above, if another service wants to reach `sample-app` via transparent proxying,
it can dial `sample-app.default.svc.cluster.local`, using
[KubeDNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/).
If ACLs with default "deny" policy are enabled, it also needs a
[ServiceIntention](/docs/connect/config-entries/service-intentions) allowing it to talk to
`sample-app`.
### VMs
To use transparent proxy on VMs, the service needs to be registered with Consul and a connect proxy needs to be added to
the mesh on the VM. Then, traffic redirection rules need to be set up to direct inbound and outbound traffic through the
sidecar connect proxy. Then, to enable transparent proxy mode to reach this service, you can set apply a service defaults
config entry to configure the mode to be transparent as shown above in the [Configuration section](#configuration).
Now, once Service Intentions are set up, other services can reach this service's address via an address known to Consul,
and the traffic will go through the proxy.
~> **Note** Only one service is supported per VM, or per network namespace. See [Known Limitations](#known-limitations)

4
website/content/docs/discovery/services.mdx
View File

@ -68,6 +68,10 @@ example shows all possible fields, but note that only a few are required.
"destination_service_id": "redis1",
"local_service_address": "127.0.0.1",
"local_service_port": 9090,
"mode": "transparent",
"transparent_proxy": {
"outbound_listener_port": 22500
}
"config": {},
"upstreams": [],
"mesh_gateway": {

4
website/data/commands-nav-data.json
View File

@ -245,6 +245,10 @@
{
"title": "expose",
"path": "connect/expose"
},
{
"title": "redirect-traffic",
"path": "connect/redirect-traffic"
}
]
},

12
website/data/docs-nav-data.json
View File

@ -141,6 +141,10 @@
"title": "Overview",
"path": "connect/config-entries"
},
{
"title": "Cluster",
"path": "connect/config-entries/cluster"
},
{
"title": "Ingress Gateway",
"path": "connect/config-entries/ingress-gateway"
@ -221,6 +225,10 @@
"title": "Service-to-service permissions - Intentions (Legacy Mode)",
"path": "connect/intentions-legacy"
},
{
"title": "Transparent Proxy <sup>Beta</sup>",
"path": "connect/transparent-proxy"
},
{
"title": "Observability",
"routes": [
@ -419,6 +427,10 @@
"title": "Overview",
"path": "k8s/connect"
},
{
"title": "Transparent Proxy",
"href": "/docs/connect/transparent-proxy"
},
{
"title": "Ingress Gateways",
"path": "k8s/connect/ingress-gateways"