Docs for Unix Domain Sockets

[markan]

This is a starting point for docs for the Unix Domain Sockets work

Most of the below writeup has been incorporated in the docs text, but a few issues remain:

1. It might be nice to incorporate the example at the end into the docs somehow, but wasn't sure how.
2. I didn't update the sample fields in the API docs; wasn't sure how to do that without confusion.

There are a number of cases where a user might wish to either 1)
expose a service through a Unix Domain Socket in the filesystem
('downstream') or 2) connect to an upstream service by a local unix
domain socket (upstream).
As of Consul (1.10-beta2) we've added new syntax and support to configure
the Envoy proxy to support this

Upstream sockets:

To connect to a service via local Unix Domain Socket instead of a
port, add local_bind_socket_path and optionally local_bind_socket_mode
to the upstream config for a service:

    upstreams = [
      {
         destination_name = "service-1"
         local_bind_socket_path = "/tmp/socket_service_1"
         local_bind_socket_mode = "0700" 
	 ...
      }
      ...
    ] 

This will cause Envoy to create a socket with the path and mode
provided, and connect that to service-1
The mode field is optional, and if omitted will use the default mode
for Envoy. This is not applicable for abstract sockets. See
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#envoy-v3-api-msg-config-core-v3-pipe
for details
NOTE: These options conflict the local_bind_socket_port and
local_bind_socket_address options. We can bind to an port or we can
bind to a socket, but not both.

Downstream sockets:

To expose a service listening on a Unix Domain socket to the service
mesh use either the 'socket_path' field in the service definition or the
'local_service_socket_path' field in the proxy definition. These
fields are analogous to the 'port' and 'service_port' fields in their
respective locations.

    services {
      name = "service-2"
      socket_path = "/tmp/socket_service_2"
      ...
    }

OR

    proxy {
      local_service_socket_path = "/tmp/socket_service_2"
      ...
    }

There is no mode field since the service is expected to create the
socket it is listening on, not the Envoy proxy.
Again, the socket_path and local_service_socket_path fields conflict
with address/port and local_service_address/local_service_port
configuration entries.

Example:

Set up a simple service mesh with dummy services:

FORWARDER

socat -d UNIX-LISTEN:/tmp/downstream.sock,fork UNIX-CONNECT:/tmp/upstream.sock

ECHO SERVICE

socat -v tcp-l:4444,fork exec:/bin/cat

Define the sock_forwarder service (consul.d/sock_forwarder.hcl)

services {
  name = "sock_forwarder"
  id = "sock_forwarder.1"
  socket_path = "/tmp/downstream.sock"
  connect {
    sidecar_service {
      proxy {
#	local_service_socket_path = "/tmp/downstream.sock"
	upstreams = [
	  {
	    destination_name = "echo-service"
	    local_bind_socket_path = "/tmp/upstream.sock"  
	    config {
	      passive_health_check {
		interval = "10s"
		max_failures = 42
	      }
	    }	    
	  }
	]
      }
    }
  }
}

define the echo service (consul.d/echo_service.hcl)

services {
  name = "echo-service"
  port = 4444
  connect = { sidecar_service {} }

define the ingress gateway (ingress_gateway.hcl)

Kind = "ingress-gateway"
Name = "ingress-service"
Listeners = [
 {
   Port = 8080
   Protocol = "tcp"
   Services = [
     {
       Name = "sock_forwarder"
     }
   ]
 }
]

# start the consul daemon:
consul agent -dev -enable-script-checks -config-dir=./consul.d
consul connect envoy -sidecar-for sock_forwarder.1
consul connect envoy -sidecar-for echo-service -admin-bind localhost:19001
consul config write ingress-gateway.hcl
consul connect envoy -gateway=ingress -register -service ingress-service -address '{{ GetInterfaceIP "eth0" }}:8888' -admin-bind localhost:19002
# test the echo service directly
netcat 127.0.0.1 4444               
# test the echo service behind the ingress gateway
netcat 127.0.0.1 8080  

Signed-off-by: Mark Anderson [email protected]

[hashicorp-ci]

🤔 This PR has changes in the website/ directory but does not have a type/docs-cherrypick label. If the changes are for the next version, this can be ignored. If they are updates to current docs, attach the label to auto cherrypick to the stable-website branch after merging.

[thomashashi]

Both unix and Unix are used — do we have a stylistic guide which recommends one over the other, for consistency?

[thomashashi]

I made one stylistic comment, otherwise looks good to me. I feel like an example of use would belong on the Learn website, maybe with a link in any relevant place from the consul.io docs.

[blake]

Looks good! I made a few suggestions.

Also a couple of the code examples were in JSON, while others were in HCL. May I suggest using the Tabs component to add examples for both? For example:

<Tabs>

<Tab heading="HCL">
destination_name =  "service-1"
local_bind_socket_path = "/tmp/socket_service_1"
</Tab>

<Tab heading="JSON">
{
  "destination_name": "service-1",
  "local_bind_socket_path": "/tmp/socket_service_1"
}
</Tab>

</Tabs>

[blake]

Suggested change

	Again, the socket_path and local_service_socket_path fields conflict
	with address/port and local_service_address/local_service_port
	configuration entries.
	Again, the `socket_path` and `local_service_socket_path` fields conflict
	with `address`/`port` and `local_service_address`/`local_service_port`
	configuration options.

[markan]

@hashicorp/consul-docs team. I've listed this option because 'this shows all the options available'. However it conflicts with local_service_address, so this actual example doesn't work. I think this could generate confusion, but I don't have a great idea how to handle this.

[blake]

I left one minor comment, but otherwise this looks good to me!

[blake]

Suggested change

	https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#envoy-v3-api-msg-config-core-v3-pipe
	<https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#envoy-v3-api-msg-config-core-v3-pipe>

Is this automatically rendered as a link on the site? If not, adding the angle brackets should do this in markdown.

[hc-github-team-consul-core]

🍒 If backport labels were added before merging, cherry-picking will start automatically.

To retroactively trigger a backport after merging, add backport labels and re-run https://circleci.com/gh/hashicorp/consul/381445.

[hc-github-team-consul-core]

🍒✅ Cherry pick of commit 1bf3dc5 onto stable-website succeeded!

[hc-github-team-consul-core]

🍒✅ Cherry pick of commit 1bf3dc5 onto release/1.10.x succeeded!