transparent_proxy Block
Placement | job -> group -> service -> connect -> sidecar_service -> proxy -> transparent_proxy |
The transparent_proxy
block configures the Envoy sidecar proxy to act as a
Consul Connect transparent proxy. This simplifies the configuration of
Consul Connect by eliminating the need to configure upstreams
blocks in
Nomad. Instead, the Envoy proxy will takes its configuration entirely from
Consul service intentions. When transparent proxy is enabled:
- Nomad will invoke the
consul-cni
CNI plugin to configureiptables
rules in the network namespace to force outbound traffic from an allocation to flow through the proxy. - If the local Consul agent is serving DNS, Nomad set the IP address of the
Consul agent as the nameserver in the task's
/etc/resolv.conf
. - Consul will provide a virtual IP for any upstream service the workload has access to, based on the service intentions.
Using transparent proxy has several important requirements:
- You must have the
consul-cni
CNI plugin installed on the client host along with the usual required CNI plugins. - You can only have a single
connect
block in any task group that uses transparent proxy. - To use Consul DNS and virtual IPs, you must set the Consul agent's
ports.dns
configuration to an IP other than localhost (the default is to use theclient_addr
). - The Consul agent must be configured with
recursors
if you want allocations to make DNS queries for applications outside the service mesh.
transparent_proxy
Parameters
exclude_inbound_ports
([]string: nil)
- A list of inbound ports to exclude from the IP tables redirect rule. These ports can be specified as either network port labels or as numeric ports. Nomad will automatically add the following to this list:- The
local_path_port
of anyexpose
block. - The port of any service check with
expose=true
set. - The port of any
network.port
with astatic
value.
- The
exclude_outbound_cidrs
([]string: nil)
- A list of CIDR subnets that should be excluded from outbound traffic redirection. This allows traffic to these subnets to bypass the Envoy proxy.exclude_outbound_ports
([]int: nil)
- A list of port numbers that should be excluded from outbound traffic redirection. This allows traffic to these subnets to bypass the Envoy proxy.exclude_uids
([]string: nil)
- A list of Unix user IDs (UIDs) that should be excluded from outbound traffic redirection. When unset, only the Envoy proxy's user will be allowed to bypass the iptables rule.no_dns
(bool: false)
- When set to true, do not set Consul as the nameserver for the workload and do not create IP tables rules to allow DNS to bypass the Envoy proxy. If you want DNS to work inside the allocation withno_dns=true
, you will need to add your own CIDR and port exclusions for your DNS nameserver.outbound_port
(int: 15001)
- The port that Envoy will bind on inside the network namespace. The iptables rules created byconsul-cni
will force traffic to flow to this port. You should only set this value if you have specifically set theoutbound_listener_port
in your Consul proxy configuration. You can change the default value for a given node via [client metadata][#client-metadata] (see below).uid
(string "101")
- The Unix user ID (UID) used by the Envoy proxy. You should only set this value if you have a custom build of the Envoy container image which uses a different UID. You can change the default value for a given node via [client metadata][#client-metadata] (see below).
Client Metadata
You can change the default [outbound_port
][#outbound_port] and [uid
][#uid]
for a given client node by updating the node metadata via the nomad node meta
apply
command. The attributes that can be updated are:
connect.transparent_proxy.default_uid
: Sets the default value of [uid
][#uid] for this node.connect.transparent_proxy.default_outbound_port
: Sets the default value of [outbound_port
][#outbound_port] for this node.
For example, to set the default value for the uid
field to 120:
You should not normally need to set these values unless you are using custom Envoy images.
Examples
Minimal Example
The following example is a minimal transparent proxy specification. Note that
with transparent proxy, you will not need to configure an upstreams
block.
If you had a downstream task group count-dashboard
that needed to connect to
an upstream task group count-api
listening on port 9001, you could create a
Consul service intention with the following specification:
And then the downstream service count-dashboard
could reach the count-api
service by making requests to http://count-api.virtual.consul:9001
.
External DNS
The following example is a transparent proxy specification where external DNS is
used. To find the address of other allocations in this configuration, you will
need to use a template
block to query Consul.