From e27d1eb12c575c1940d58fa5567b6879fe840ad3 Mon Sep 17 00:00:00 2001 From: "Chris S. Kim" Date: Mon, 8 Aug 2022 18:24:43 -0400 Subject: [PATCH] Update docs for peered transparent proxy --- .../registration/service-registration.mdx | 32 ++++++++++++++++--- .../docs/connect/transparent-proxy.mdx | 14 ++++---- website/content/docs/discovery/dns.mdx | 11 +++---- 3 files changed, 40 insertions(+), 17 deletions(-) diff --git a/website/content/docs/connect/registration/service-registration.mdx b/website/content/docs/connect/registration/service-registration.mdx index 66b1aa96f7..5b6e8ef598 100644 --- a/website/content/docs/connect/registration/service-registration.mdx +++ b/website/content/docs/connect/registration/service-registration.mdx @@ -115,6 +115,7 @@ proxy = { mode = "transparent" transparent_proxy = {} upstreams = [] +} ``` ```json @@ -167,7 +168,7 @@ You can configure the service mesh proxy to create listeners for upstream servic |`destination_name` | String value that specifies the name of the service or prepared query to route the service mesh to. The prepared query should be the name or the ID of the prepared query. | Required | None | | `destination_namespace` | String value that specifies the namespace containing the upstream service. | Optional | `default` | | `destination_peer` | String value that specifies the name of the peer cluster containing the upstream service. | Optional | None | -| `destination_partition` | String value that specifies the name of the admin partition containing the upstream service. | Optional | `default` | +| `destination_partition` | String value that specifies the name of the admin partition containing the upstream service. If `destination_peer` is set, `destination_partition` refers to the local admin partition in which the peering was established. | Optional | `default` | | `local_bind_port` | Integer value that specifies the port to bind a local listener to. The application will make outbound connections to the upstream from the local port. | Required | None | | `local_bind_address` | String value that specifies the address to bind a local listener to. The application will make outbound connections to the upstream service from the local bind address. | Optional | `127.0.0.1` | | `local_bind_socket_path` | String value that specifies the path at which to bind a Unix domain socket listener. The application will make outbound connections to the upstream from the local bind socket path.
This parameter conflicts with the `local_bind_port` or `local_bind_address` parameters.
Supported when using Envoy as a proxy. | Optional | None| @@ -195,7 +196,7 @@ local_bind_socket_path = "/tmp/redis_5678.sock" local_bind_socket_mode = "0700" mesh_gateway = { mode = "local" - } +} ``` ```json @@ -257,6 +258,29 @@ local_bind_port = 9090 } ``` + + + +```hcl +destination_peer = "cloud-services" +destination_partition = "finance" +destination_namespace = "default" +destination_type = "service" +destination_name = "api" +local_bind_port = 9090 +``` + +```json +{ + "destination_peer": "cloud-services", + "destination_partition": "finance", + "destination_namespace": "default", + "destination_type": "service", + "destination_name": "api", + "local_bind_port": 9090 +} +``` + ## Proxy Modes @@ -297,7 +321,7 @@ registrations](/docs/discovery/services#service-definition-parameter-case). - `dialed_directly` `(bool: false)` - Determines whether this proxy instance's IP address can be dialed directly by transparent proxies. Transparent proxies typically dial upstreams using the "virtual" tagged address, which load balances across instances. A database cluster with a leader is an example - where dialing individual instances can be helpful. + where dialing individual instances can be helpful. Cannot be used with upstreams which define a `destination_peer`. ~> **Note:** Dynamic routing rules such as failovers and redirects do not apply to services dialed directly. Additionally, the connection is proxied using a TCP proxy with a connection timeout of 5 seconds. @@ -521,7 +545,7 @@ services { "proxy": { "name": "service-2", "local_service_socket_path": "/tmp/socket_service_2" - ... + ... } } } diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx index 1091091cfb..93bbadb231 100644 --- a/website/content/docs/connect/transparent-proxy.mdx +++ b/website/content/docs/connect/transparent-proxy.mdx @@ -29,8 +29,8 @@ Without transparent proxy, application owners need to: With transparent proxy: -1. Upstreams are inferred from service intentions, so no explicit configuration - is needed. +1. Upstreams are inferred from service intentions and/or imported services, + so no explicit configuration is needed. 1. Outbound connections pointing to a KubeDNS name "just work" — network rules redirect them through the proxy. 1. Inbound traffic is forced to go through the proxy to prevent unauthorized @@ -45,15 +45,15 @@ and only reaches intended destinations since the proxy can enforce security and 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 +implicitly from Service Intentions and imported services from a peer. Explicit upstreams are still supported in the [proxy service registration](/docs/connect/registration/service-registration) on VMs and via the [annotation](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) in Kubernetes. To support transparent proxying, Consul's CLI now has a command [`consul connect redirect-traffic`](/commands/connect/redirect-traffic) to redirect traffic through an inbound and -outbound listener on the sidecar. Consul 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. +outbound listener on the sidecar. Consul also watches Service Intentions and imported services then 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 @@ -62,7 +62,7 @@ the traffic redirection command is automatically set up via an init container. * To use transparent proxy on Kubernetes, Consul-helm >= `0.32.0` and Consul-k8s >= `0.26.0` are required in addition to Consul >= `1.10.0`. * 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. -* If using Transparent Proxy, all worker nodes within a Kubernetes cluster must have the `ip_tables` kernel module running, e.g. `modprobe ip_tables`. +* If using Transparent Proxy, all worker nodes within a Kubernetes cluster must have the `ip_tables` kernel module running, e.g. `modprobe ip_tables`. The Kubernetes integration takes care of registering Kubernetes services with Consul, injecting a sidecar proxy, and enabling traffic redirection. diff --git a/website/content/docs/discovery/dns.mdx b/website/content/docs/discovery/dns.mdx index 471b9f9a20..f08a43c6ed 100644 --- a/website/content/docs/discovery/dns.mdx +++ b/website/content/docs/discovery/dns.mdx @@ -488,18 +488,17 @@ fields must be present: * `partition` * `datacenter` -For node lookups, only the partition and datacenter need to be specified as nodes cannot be -namespaced. +For imported lookups, only the namespace and peer need to be specified as the partition can be inferred from the peering: ```text -[tag.].service..ap..dc. +.virtual[.namespace][.peer]. ``` -For node lookups, only the partition and datacenter need to be specified (nodes cannot be -namespaced): +For node lookups, only the partition and datacenter need to be specified as nodes cannot be +namespaced. ```text -[tag.].service..ap..dc. +[tag.].node..ap..dc. ``` ## DNS with ACLs