Skip to content

Commit

Permalink
docs: update service mesh integration docs for transparent proxy
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@tgross
tgross committed Apr 3, 2024
1 parent 7eb911a commit 88b853a
Showing 1 changed file with 109 additions and 17 deletions.
126 changes: 109 additions & 17 deletions website/content/docs/integrations/consul/service-mesh.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -170,7 +193,11 @@ job "countdash" {
port = "9001"
connect {
sidecar_service {}
sidecar_service {
proxy {
transparent_proxy {}
}
}
}
}
Expand Down Expand Up @@ -200,10 +227,7 @@ job "countdash" {
connect {
sidecar_service {
proxy {
upstreams {
destination_name = "count-api"
local_bind_port = 8080
}
transparent_proxy {}
}
}
}
Expand All @@ -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 {
Expand All @@ -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" {
Expand All @@ -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 {}
}
}
}
}
Expand Down Expand Up @@ -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"
Expand All @@ -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

Expand Down Expand Up @@ -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

0 comments on commit 88b853a

Please sign in to comment.