From ba055db83d2e76714af816fdc0841f4f025de02e Mon Sep 17 00:00:00 2001 From: Freddy Date: Fri, 16 Apr 2021 13:50:02 -0600 Subject: [PATCH] Add docs for transparent proxy mode and config (#10038) Add docs for transparent proxy mode and config Co-authored-by: Nitya Dhanushkodi Co-authored-by: Blake Covarrubias Co-authored-by: Iryna Shustava Co-authored-by: Jeff Escalante --- website/content/api-docs/agent/service.mdx | 66 ++-- website/content/api-docs/catalog.mdx | 232 ++++++------ website/content/api-docs/health.mdx | 98 ++--- .../commands/connect/redirect-traffic.mdx | 2 +- .../docs/connect/config-entries/cluster.mdx | 77 ++++ .../docs/connect/config-entries/index.mdx | 3 + .../connect/config-entries/proxy-defaults.mdx | 26 ++ .../config-entries/service-defaults.mdx | 347 ++++++++++++++++++ .../registration/service-registration.mdx | 38 ++ .../docs/connect/transparent-proxy.mdx | 238 ++++++++++++ website/content/docs/discovery/services.mdx | 4 + website/data/commands-nav-data.json | 4 + website/data/docs-nav-data.json | 12 + 13 files changed, 955 insertions(+), 192 deletions(-) create mode 100644 website/content/docs/connect/config-entries/cluster.mdx create mode 100644 website/content/docs/connect/transparent-proxy.mdx diff --git a/website/content/api-docs/agent/service.mdx b/website/content/api-docs/agent/service.mdx index 5ea91f717..26e727853 100644 --- a/website/content/api-docs/agent/service.mdx +++ b/website/content/api-docs/agent/service.mdx @@ -87,36 +87,38 @@ $ curl \ 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 | -| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Meta` | Is Empty, Is Not Empty, In, Not In | -| `Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Port` | Equal, Not Equal | -| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `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.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 | -| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | -| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | -| `TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `TaggedAddresses..Port` | Equal, Not Equal | -| `Tags` | In, Not In, Is Empty, Is Not Empty | -| `Weights.Passing` | Equal, Not Equal | -| `Weights.Warning` | Equal, Not Equal | +| Selector | Supported Operations | +| --------------------------------------------- | -------------------------------------------------- | +| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Connect.Native` | Equal, Not Equal | +| `EnableTagOverride` | Equal, Not Equal | +| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Meta` | Is Empty, Is Not Empty, In, Not In | +| `Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Port` | Equal, Not Equal | +| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `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 | +| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | +| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | +| `TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `TaggedAddresses..Port` | Equal, Not Equal | +| `Tags` | In, Not In, Is Empty, Is Not Empty | +| `Weights.Passing` | Equal, Not Equal | +| `Weights.Warning` | Equal, Not Equal | ## Get Service Configuration @@ -196,6 +198,10 @@ $ curl \ "DestinationServiceID": "web", "LocalServiceAddress": "127.0.0.1", "LocalServicePort": 8080, + "Mode": "transparent", + "TransparentProxy": { + "OutboundListenerPort": 22500 + }, "Config": { "foo": "bar" }, diff --git a/website/content/api-docs/catalog.mdx b/website/content/api-docs/catalog.mdx index 484bf56a1..187a03769 100644 --- a/website/content/api-docs/catalog.mdx +++ b/website/content/api-docs/catalog.mdx @@ -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": "", @@ -596,44 +596,46 @@ $ curl \ 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 | -| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `NodeMeta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `NodeMeta` | Is Empty, Is Not Empty, In, Not In | -| `ServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceConnect.Native` | Equal, Not Equal | -| `ServiceEnableTagOverride` | Equal, Not Equal | -| `ServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceKind` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceMeta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceMeta` | Is Empty, Is Not Empty, In, Not In | -| `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServicePort` | Equal, Not Equal | -| `ServiceProxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `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.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 | -| `ServiceProxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceProxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceProxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceProxy.Upstreams.LocalBindPort` | Equal, Not Equal | -| `ServiceProxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceProxy.Upstreams` | Is Empty, Is Not Empty | -| `ServiceTaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `ServiceTaggedAddresses..Port` | Equal, Not Equal | -| `ServiceTaggedAddresses` | Is Empty, Is Not Empty, In, Not In | -| `ServiceTags` | In, Not In, Is Empty, Is Not Empty | -| `ServiceWeights.Passing` | Equal, Not Equal | -| `ServiceWeights.Warning` | Equal, Not Equal | -| `TaggedAddresses.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | +| 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 | +| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `NodeMeta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `NodeMeta` | Is Empty, Is Not Empty, In, Not In | +| `ServiceAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceConnect.Native` | Equal, Not Equal | +| `ServiceEnableTagOverride` | Equal, Not Equal | +| `ServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceKind` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceMeta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceMeta` | Is Empty, Is Not Empty, In, Not In | +| `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServicePort` | Equal, Not Equal | +| `ServiceProxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `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 | +| `ServiceProxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceProxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceProxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceProxy.Upstreams.LocalBindPort` | Equal, Not Equal | +| `ServiceProxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceProxy.Upstreams` | Is Empty, Is Not Empty | +| `ServiceTaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `ServiceTaggedAddresses..Port` | Equal, Not Equal | +| `ServiceTaggedAddresses` | Is Empty, Is Not Empty, In, Not In | +| `ServiceTags` | In, Not In, Is Empty, Is Not Empty | +| `ServiceWeights.Passing` | Equal, Not Equal | +| `ServiceWeights.Warning` | Equal, Not Equal | +| `TaggedAddresses.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | ## List Nodes for Connect-capable Service @@ -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": { @@ -746,36 +748,38 @@ $ curl \ The filter will be executed against each value in the `Services` mapping within the 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 | -| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Meta` | Is Empty, Is Not Empty, In, Not In | -| `Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Port` | Equal, Not Equal | -| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `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.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 | -| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | -| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | -| `TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `TaggedAddresses..Port` | Equal, Not Equal | -| `Tags` | In, Not In, Is Empty, Is Not Empty | -| `Weights.Passing` | Equal, Not Equal | -| `Weights.Warning` | Equal, Not Equal | +| Selector | Supported Operations | +| --------------------------------------------- | -------------------------------------------------- | +| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Connect.Native` | Equal, Not Equal | +| `EnableTagOverride` | Equal, Not Equal | +| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Meta` | Is Empty, Is Not Empty, In, Not In | +| `Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Port` | Equal, Not Equal | +| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `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 | +| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | +| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | +| `TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `TaggedAddresses..Port` | Equal, Not Equal | +| `Tags` | In, Not In, Is Empty, Is Not Empty | +| `Weights.Passing` | Equal, Not Equal | +| `Weights.Warning` | Equal, Not Equal | ## List Services for Node @@ -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", @@ -876,36 +880,38 @@ $ curl \ 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 | -| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Meta` | Is Empty, Is Not Empty, In, Not In | -| `Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Port` | Equal, Not Equal | -| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `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.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 | -| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | -| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | -| `TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `TaggedAddresses..Port` | Equal, Not Equal | -| `Tags` | In, Not In, Is Empty, Is Not Empty | -| `Weights.Passing` | Equal, Not Equal | -| `Weights.Warning` | Equal, Not Equal | +| Selector | Supported Operations | +| --------------------------------------------- | -------------------------------------------------- | +| `Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Connect.Native` | Equal, Not Equal | +| `EnableTagOverride` | Equal, Not Equal | +| `ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Meta` | Is Empty, Is Not Empty, In, Not In | +| `Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Port` | Equal, Not Equal | +| `Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `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 | +| `Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | +| `Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | +| `TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `TaggedAddresses..Port` | Equal, Not Equal | +| `Tags` | In, Not In, Is Empty, Is Not Empty | +| `Weights.Passing` | Equal, Not Equal | +| `Weights.Warning` | Equal, Not Equal | ## List Services for Gateway diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx index c8bf233e5..4a3f1b759 100644 --- a/website/content/api-docs/health.mdx +++ b/website/content/api-docs/health.mdx @@ -344,54 +344,56 @@ $ curl \ The filter will be executed against each entry in the top level results list with the 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 | -| `Checks.Node` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Checks.Notes` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Checks.Output` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Checks.ServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Checks.ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Checks.ServiceTags` | In, Not In, Is Empty, Is Not Empty | -| `Checks.Status` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Node.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Node.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Node.ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Node.Meta` | Is Empty, Is Not Empty, In, Not In | -| `Node.Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Node.Node` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Node.TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | -| `Node.TaggedAddresses.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Connect.Native` | Equal, Not Equal | -| `Service.EnableTagOverride` | Equal, Not Equal | -| `Service.ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Meta` | Is Empty, Is Not Empty, In, Not In | -| `Service.Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Port` | Equal, Not Equal | -| `Service.Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `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.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 | -| `Service.Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | -| `Service.Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | -| `Service.TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | -| `Service.TaggedAddresses..Port` | Equal, Not Equal | -| `Service.Tags` | In, Not In, Is Empty, Is Not Empty | -| `Service.Weights.Passing` | Equal, Not Equal | -| `Service.Weights.Warning` | Equal, Not Equal | +| 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 | +| `Checks.Node` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Checks.Notes` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Checks.Output` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Checks.ServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Checks.ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Checks.ServiceTags` | In, Not In, Is Empty, Is Not Empty | +| `Checks.Status` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Node.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Node.Datacenter` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Node.ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Node.Meta` | Is Empty, Is Not Empty, In, Not In | +| `Node.Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Node.Node` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Node.TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | +| `Node.TaggedAddresses.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Connect.Native` | Equal, Not Equal | +| `Service.EnableTagOverride` | Equal, Not Equal | +| `Service.ID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Kind` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Meta` | Is Empty, Is Not Empty, In, Not In | +| `Service.Meta.` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Port` | Equal, Not Equal | +| `Service.Proxy.DestinationServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `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 | +| `Service.Proxy.Upstreams.DestinationName` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Proxy.Upstreams.DestinationNamespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Proxy.Upstreams.DestinationType` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Proxy.Upstreams.LocalBindAddress` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Proxy.Upstreams.LocalBindPort` | Equal, Not Equal | +| `Service.Proxy.Upstreams.MeshGateway.Mode` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.Service` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.TaggedAddresses` | Is Empty, Is Not Empty, In, Not In | +| `Service.TaggedAddresses..Address` | Equal, Not Equal, In, Not In, Matches, Not Matches | +| `Service.TaggedAddresses..Port` | Equal, Not Equal | +| `Service.Tags` | In, Not In, Is Empty, Is Not Empty | +| `Service.Weights.Passing` | Equal, Not Equal | +| `Service.Weights.Warning` | Equal, Not Equal | ## List Nodes for Connect-capable Service diff --git a/website/content/commands/connect/redirect-traffic.mdx b/website/content/commands/connect/redirect-traffic.mdx index 618f155f7..5564b943a 100644 --- a/website/content/commands/connect/redirect-traffic.mdx +++ b/website/content/commands/connect/redirect-traffic.mdx @@ -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 diff --git a/website/content/docs/connect/config-entries/cluster.mdx b/website/content/docs/connect/config-entries/cluster.mdx new file mode 100644 index 000000000..cab611edb --- /dev/null +++ b/website/content/docs/connect/config-entries/cluster.mdx @@ -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 Beta + +-> **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 + + + + +```hcl +Kind = "cluster" +Name = "cluster" +TransparentProxy { + CatalogDestinationsOnly = true +} +``` + + + + +**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 +} +``` + + + + +## Available Fields + +- `Kind` - Must be set to `cluster` + +- `Name` `(string: )` - Must be set to `cluster` + +- `Namespace` `(string: "default")` - Specifies the namespace the config entry will apply to. + Must be set to `default` + +- `Meta` `(map: nil)` - Specifies arbitrary KV metadata pairs. + +- `TransparentProxy` `(TransparentProxyConfig: )` - 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`. diff --git a/website/content/docs/connect/config-entries/index.mdx b/website/content/docs/connect/config-entries/index.mdx index 18657d80a..92e5dc463 100644 --- a/website/content/docs/connect/config-entries/index.mdx +++ b/website/content/docs/connect/config-entries/index.mdx @@ -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) Beta - 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 diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index 1b5ebbd43..4009d925d 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -210,6 +210,32 @@ spec:
  • [Envoy](/docs/connect/proxies/envoy#bootstrap-configuration)
  • [Consul's built-in proxy](/docs/connect/proxies/built-in)
`, }, + { + 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: ', + 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: ', diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index b7121c779..96a5ef0f2 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -47,6 +47,81 @@ spec: +### Upstream configuration Beta + + + + +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" + } + } + ] +} +``` + + + + +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" + } + } + ] +} +``` + + + + ## Available Fields ', + 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: []', + 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: ', + 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: ', + 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: ', + 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: ', + 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: ', + 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: ', + 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: ', + 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: ', + 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: ', diff --git a/website/content/docs/connect/registration/service-registration.mdx b/website/content/docs/connect/registration/service-registration.mdx index 361fb277d..496387b6f 100644 --- a/website/content/docs/connect/registration/service-registration.mdx +++ b/website/content/docs/connect/registration/service-registration.mdx @@ -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: "")` Beta - 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: {})` Beta - 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 Beta + +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. diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx new file mode 100644 index 000000000..00331f1e3 --- /dev/null +++ b/website/content/docs/connect/transparent-proxy.mdx @@ -0,0 +1,238 @@ +--- +layout: docs +page_title: Connect - Transparent Proxy +sidebar_title: Transparent Proxy Beta +description: |- + Transparent proxy is used to direct inbound and outbound traffic to services via the Envoy proxy and configure + upstreams via intentions. +--- + +# Transparent Proxy Beta + +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) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 79266c0da..dd15629b0 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -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": { diff --git a/website/data/commands-nav-data.json b/website/data/commands-nav-data.json index 329287d52..16f149e5c 100644 --- a/website/data/commands-nav-data.json +++ b/website/data/commands-nav-data.json @@ -245,6 +245,10 @@ { "title": "expose", "path": "connect/expose" + }, + { + "title": "redirect-traffic", + "path": "connect/redirect-traffic" } ] }, diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index b524b3b9e..946bbbd68 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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 Beta", + "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"