docs: update service mesh integration docs for transparent proxy

Update the service mesh integration docs to explain how Consul needs to be
configured for transparent proxy. Update the walkthrough to assume that
`transparent_proxy` mode is the best approach, and move the manually-configured
`upstreams` to a separate section for users who don't want to use Consul DNS.

Ref: #20175
Ref: #20241

website/content/docs/integrations/consul/service-mesh.mdx

@@ -134,6 +134,25 @@ service_prefix "" { policy = "read" }
 node_prefix    "" { policy = "read" }
 ```
 
+#### Consul DNS For Transparent Proxy
+
+To use Consul's [transparent proxy][] mode with virtual IP addresses, you'll
+need to configure Consul's DNS listener to be exposed to the workload network
+namespace. You can do this without exposing the Consul agent on a public IP by
+setting the Consul `bind_addr` to bind on a private IP address.
+
+If you want workloads to be able to use both Consul DNS and query external DNS
+entries, you'll need to add [`recursors`][] for the external nameservers.
+
+For example, a HCL configuration with a [go-sockaddr/template][] binding to the
+subnet `10.37.105.0/20`, with recursive DNS set to OpenDNS nameservers:
+
+```hcl
+bind_addr   = "{{ GetPrivateInterfaces | include \"network\" \"10.37.105.0/20\" | limit 1 | attr \"address\" }}"
+
+recursors = ["208.67.222.222", "208.67.220.220"]
+```
+
 ### Nomad
 
 Nomad must schedule onto a routable interface in order for the proxies to
@@ -150,10 +169,14 @@ Nomad uses CNI reference plugins to configure the network namespace used to secu
 Consul service mesh sidecar proxy. All Nomad client nodes using network namespaces
 must have these CNI plugins [installed][cni_install].
 
+To use [`transparent_proxy`][] mode, Nomad client nodes will also need the
+[`consul-cni`][] plugin installed.
+
 ## Run the Service Mesh-enabled Services
 
-Once Nomad and Consul are running, submit the following service mesh-enabled services
-to Nomad by copying the HCL into a file named `servicemesh.nomad.hcl` and running:
+Once Nomad and Consul are running, with Consul DNS enabled for transparent proxy
+mode as described above, submit the following service mesh-enabled services to
+Nomad by copying the HCL into a file named `servicemesh.nomad.hcl` and running:
 `nomad job run servicemesh.nomad.hcl`
 
 ```hcl
@@ -170,7 +193,11 @@ job "countdash" {
       port = "9001"
 
       connect {
-        sidecar_service {}
+        sidecar_service {
+          proxy {
+            transparent_proxy {}
+          }
+        }
       }
     }
 
@@ -200,10 +227,7 @@ job "countdash" {
       connect {
         sidecar_service {
           proxy {
-            upstreams {
-              destination_name = "count-api"
-              local_bind_port  = 8080
-            }
+            transparent_proxy {}
           }
         }
       }
@@ -213,7 +237,7 @@ job "countdash" {
       driver = "docker"
 
       env {
-        COUNTING_SERVICE_URL = "http://${NOMAD_UPSTREAM_ADDR_count_api}"
+        COUNTING_SERVICE_URL = "http://count-api.virtual.consul:9001"
       }
 
       config {
@@ -240,8 +264,10 @@ The API service is defined as a task group with a bridge network:
   }
 ```
 
-Since the API service is only accessible via Consul service mesh, it does not define
-any ports in its network. The service block enables service mesh.
+Since the API service is only accessible via Consul service mesh, it does not
+define any ports in its network. The `connect` block enables the service mesh
+and the `transparent_proxy` block ensures that the service will be reachable via
+a virtual IP address when used with Consul DNS.
 
 ```hcl
   group "api" {
@@ -253,7 +279,11 @@ any ports in its network. The service block enables service mesh.
       port = "9001"
 
       connect {
-        sidecar_service {}
+        sidecar_service {
+          proxy {
+            transparent_proxy {}
+          }
+        }
       }
     }
 
@@ -299,6 +329,64 @@ This allows you to connect to the web frontend in a browser by visiting
 
 The web frontend connects to the API service via Consul service mesh.
 
+```hcl
+    service {
+      name = "count-dashboard"
+      port = "http"
+
+      connect {
+        sidecar_service {
+          proxy {
+            transparent_proxy {}
+          }
+        }
+      }
+    }
+```
+
+The `connect` block with `transparent_proxy` configures the web frontend's
+network namespace to route all access to the `count-api` service through the
+Envoy proxy.
+
+The web frontend is configured to communicate with the API service with an
+environment variable `$COUNTING_SERVICE_URL`:
+
+```hcl
+      env {
+        COUNTING_SERVICE_URL = "http://count-api.virtual.consul:9001"
+      }
+```
+
+The `transparent_proxy` block ensures that DNS queries are made to Consul so
+that the `count-api.virtual.consul` name resolves to a virtual IP address.
+
+### Manually Configured Upstreams
+
+If you don't want to use Consul DNS and `transparent_proxy` mode, you can add
+`upstream` blocks to the job spec. In that case, you don't need the
+`transparent_proxy` block for the `count-api` service:
+
+```hcl
+  group "api" {
+
+    # ...
+
+    service {
+      name = "count-api"
+      port = "9001"
+
+      connect {
+        sidecar_service {}
+      }
+    }
+
+    # ...
+
+  }
+```
+
+But you'll need to add an `upstreams` block to the `count-dashboard` service:
+
 ```hcl
     service {
       name = "count-dashboard"
@@ -320,19 +408,18 @@ The web frontend connects to the API service via Consul service mesh.
 The `upstreams` block defines the remote service to access (`count-api`) and
 what port to expose that service on inside the network namespace (`8080`).
 
-The web frontend is configured to communicate with the API service with an
-environment variable:
+The web frontend will also need to use an environment variable to communicate
+with the API service:
 
 ```hcl
       env {
         COUNTING_SERVICE_URL = "http://${NOMAD_UPSTREAM_ADDR_count_api}"
       }
 ```
 
-The web frontend is configured via the `$COUNTING_SERVICE_URL`, so you must
-interpolate the upstream's address into that environment variable. Note that
-dashes (`-`) are converted to underscores (`_`) in environment variables so
-`count-api` becomes `count_api`.
+This environment variable value gets interpolated with the upstream's
+address. Note that dashes (`-`) are converted to underscores (`_`) in
+environment variables so `count-api` becomes `count_api`.
 
 ## Limitations
 
@@ -377,3 +464,8 @@ filesystem.
 [consul_ports]: /consul/docs/agent/config/config-files#ports
 [consul_grpc_tls]: /consul/docs/upgrading/upgrade-specific#changes-to-grpc-tls-configuration
 [cni_install]: /nomad/docs/install#post-installation-steps
+[transparent proxy]: /consul/docs/k8s/connect/transparent-proxy
+[go-sockaddr/template]: https://godoc.org/github.com/hashicorp/go-sockaddr/template
+[`recursors`]: /consul/docs/agent/config/config-files#recursors
+[`transparent_proxy`]: /nomad/docs/job-specification/transparent_proxy
+[`consul-cni`]: https://releases.hashicorp.com/consul-cni