consul/website/content/docs/discovery
Mark Anderson 1bf3dc5a5f
Docs for Unix Domain Sockets (#10252)
* Docs for Unix Domain Sockets

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
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.
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.
Set up a simple service mesh with dummy services:
socat -d UNIX-LISTEN:/tmp/downstream.sock,fork UNIX-CONNECT:/tmp/upstream.sock
socat -v tcp-l:4444,fork exec:/bin/cat
services {
  name = "sock_forwarder"
  id = "sock_forwarder.1"
  socket_path = "/tmp/downstream.sock"
  connect {
    sidecar_service {
      proxy {
	upstreams = [
	  {
	    destination_name = "echo-service"
	    local_bind_socket_path = "/tmp/upstream.sock"
	    config {
	      passive_health_check {
		interval = "10s"
		max_failures = 42
	      }
	    }
	  }
	]
      }
    }
  }
}
services {
  name = "echo-service"
  port = 4444
  connect = { sidecar_service {} }
Kind = "ingress-gateway"
Name = "ingress-service"
Listeners = [
 {
   Port = 8080
   Protocol = "tcp"
   Services = [
     {
       Name = "sock_forwarder"
     }
   ]
 }
]
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
netcat 127.0.0.1 4444
netcat 127.0.0.1 8080

Signed-off-by: Mark Anderson <manderson@hashicorp.com>

* fixup Unix capitalization

Signed-off-by: Mark Anderson <manderson@hashicorp.com>

* Update website/content/docs/connect/registration/service-registration.mdx

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>

* Provide examples in hcl and json

Signed-off-by: Mark Anderson <manderson@hashicorp.com>

* Apply suggestions from code review

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>

* One more fixup for docs

Signed-off-by: Mark Anderson <manderson@hashicorp.com>

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
2021-06-04 18:54:31 -07:00
..
checks.mdx add http2 ping health checks (#8431) 2021-04-09 15:12:10 -04:00
dns.mdx
services.mdx Docs for Unix Domain Sockets (#10252) 2021-06-04 18:54:31 -07:00