open-consul/website/content/docs/connect/registration/service-registration.mdx

489 lines
17 KiB
Plaintext
Raw Normal View History

[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
---
2020-04-07 18:55:19 +00:00
layout: docs
page_title: Connect - Service Registration
description: >-
A per-service proxy sidecar transparently handles inbound and outbound service
connections. You can register these sidecars with reasonable defaults by nesting
2020-04-07 18:55:19 +00:00
their definitions in the service definition.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
---
# Proxy Service Registration
To function as a Connect proxy, proxies must be declared as a proxy types in
their service definitions, and provide information about the service they
represent.
To declare a service as a proxy, the service definition must contain
the following fields:
2020-04-06 20:27:35 +00:00
- `kind` `(string)` must be set to `connect-proxy`. This declares that the
service is a proxy type.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
2020-04-06 20:27:35 +00:00
- `proxy.destination_service_name` `(string)` must be set to the service that
this proxy is representing. Note that this replaces `proxy_destination` in
versions 1.2.0 to 1.3.0.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
2020-04-06 20:27:35 +00:00
~> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was
specified using `proxy_destination` at the top level. This will continue to work
until at least 1.5.0 but it's highly recommended to switch to using
`proxy.destination_service_name`.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
2020-04-06 20:27:35 +00:00
- `port` `(int)` must be set so that other Connect services can discover the
exact address for connections. `address` is optional if the service is being
registered against an agent, since it'll inherit the node address.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
Minimal Example:
```json
{
"name": "redis-proxy",
"kind": "connect-proxy",
"proxy": {
"destination_service_name": "redis"
},
"port": 8181
}
```
With this service registered, any Connect clients searching for a
Connect-capable endpoint for "redis" will find this proxy.
### Sidecar Proxy Fields
Most Connect proxies are deployed as "sidecars" which means they are co-located
with a single service instance which they represent and proxy all inbound
traffic to. In this case the following fields should also be set if you are deploying your proxy as a sidecar but defining it in its own service registration:
2020-04-06 20:27:35 +00:00
- `proxy.destination_service_id` `(string: <required>)` is set to the _id_
(and not the _name_ if they are different) of the specific service instance
that is being proxied. The proxied service is assumed to be registered on
the same agent although it's not strictly validated to allow for
un-coordinated registrations.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
2020-04-06 20:27:35 +00:00
- `proxy.local_service_port` `(int: <required>)` must specify the port the
proxy should use to connect to the _local_ service instance.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
2020-04-06 20:27:35 +00:00
- `proxy.local_service_address` `(string: "")` can be set to override the IP or
hostname the proxy should use to connect to the _local_ service. Defaults to
`127.0.0.1`.
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
### Complete Configuration Example
The following is a complete example showing all the options available when
registering a proxy instance.
```json
{
"name": "redis-proxy",
"kind": "connect-proxy",
"proxy": {
"destination_service_name": "redis",
"destination_service_id": "redis1",
"local_service_address": "127.0.0.1",
"local_service_port": 9090,
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-05 01:54:31 +00:00
"local_service_socket_path": "/tmp/redis.sock",
"mode": "transparent",
"transparent_proxy": {},
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
"config": {},
2019-07-08 23:40:57 +00:00
"upstreams": [],
"mesh_gateway": {},
"expose": {}
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
},
"port": 8181
}
```
#### Proxy Parameters
2020-04-06 20:27:35 +00:00
- `destination_service_name` `(string: <required>)` - Specifies the _name_ of the
service this instance is proxying. Both side-car and centralized
load-balancing proxies must specify this. It is used during service
discovery to find the correct proxy instances to route to for a given service
name.
- `destination_service_id` `(string: "")` - Specifies the _ID_ of a single
specific service instance that this proxy is representing. This is only valid
for side-car style proxies that run on the same node. It is assumed that the
service instance is registered via the same Consul agent so the ID is unique
and has no node qualifier. This is useful to show in tooling which proxy
instance is a side-car for which application instance and will enable
fine-grained analysis of the metrics coming from the proxy.
- `local_service_address` `(string: "")` - Specifies the address a side-car
proxy should attempt to connect to the local application instance on.
Defaults to 127.0.0.1.
- `local_service_port` `(int: <optional>)` - Specifies the port a side-car
proxy should attempt to connect to the local application instance on.
Defaults to the port advertised by the service instance identified by
`destination_service_id` if it exists otherwise it may be empty in responses.
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-05 01:54:31 +00:00
- `local_service_socket_path` - The path of a Unix domain socket to connect to the local application
instance. This is created by the application. This conflicts with `local_service_address`
and `local_service_port`. This is only supported when using Envoy for the proxy.
- `mode` `(string: "")` - One of \`direct\` or \`transparent\`. Added in v1.10.0.
- `"transparent"` - represents that inbound and outbound application traffic is being
captured and redirected through the proxy. This mode does not enable the traffic redirection
itself. Instead it signals Consul to configure Envoy as if traffic is already being redirected.
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-05 01:54:31 +00:00
- `"direct"` - represents that the proxy's listeners must be dialed directly by the local
application and other proxies.
- `""` - Default mode. The default mode will be `"direct"` if no other configuration
applies. The order of precedence for setting the mode is
1. Proxy Service's `Proxy` configuration
2. The `service-defaults` configuration for the service.
3. The `global` `proxy-defaults`.
- `transparent_proxy` `(object: {})` - Specifies the configuration specific to proxies in `transparent` mode.
The format is defined in the [Transparent Proxy Configuration Reference](#transparent-proxy-configuration-reference).
Added in v1.10.0.
2020-04-06 20:27:35 +00:00
- `config` `(object: {})` - Specifies opaque config JSON that will be
stored and returned along with the service instance from future API calls.
- `upstreams` `(array<Upstream>: [])` - Specifies the upstream services
this proxy should create listeners for. The format is defined in
[Upstream Configuration Reference](#upstream-configuration-reference).
- `mesh_gateway` `(object: {})` - Specifies the mesh gateway configuration
for this proxy. The format is defined in the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference).
- `expose` `(object: {})` - Specifies the configuration to expose HTTP paths through this proxy.
The format is defined in the [Expose Paths Configuration Reference](#expose-paths-configuration-reference),
and is only compatible with an Envoy proxy.
2019-07-08 23:40:57 +00:00
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
### Upstream Configuration Reference
The following examples show all possible upstream configuration parameters.
-> Note that `snake_case` is used here as it works in both [config file and API
2020-04-09 23:46:54 +00:00
registrations](/docs/agent/services#service-definition-parameter-case).
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
Upstreams support multiple destination types. Both examples are shown below
followed by documentation for each attribute.
#### Service Destination
```json
{
"destination_type": "service",
"destination_name": "redis",
"datacenter": "dc1",
"local_bind_address": "127.0.0.1",
"local_bind_port": 1234,
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-05 01:54:31 +00:00
"local_bind_socket_path": "/tmp/redis_5678.sock",
"local_bind_socket_mode": "0700",
2019-07-08 23:40:57 +00:00
"config": {},
"mesh_gateway": {
"mode": "local"
}
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
},
```
#### Prepared Query Destination
```json
{
"destination_type": "prepared_query",
"destination_name": "database",
"local_bind_address": "127.0.0.1",
"local_bind_port": 1234,
"config": {}
},
```
2020-04-06 20:27:35 +00:00
- `destination_name` `(string: <required>)` - Specifies the name of the service
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
or prepared query to route connect to. The prepared query should be the name
or the ID of the prepared query.
- `destination_namespace` `(string: "")` - <EnterpriseAlert inline />
Specifies the namespace of the upstream service.
2020-04-06 20:27:35 +00:00
- `local_bind_port` `(int: <required>)` - Specifies the port to bind a local
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
listener to for the application to make outbound connections to this upstream.
2020-04-06 20:27:35 +00:00
- `local_bind_address` `(string: "")` - Specifies the address to bind a
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
local listener to for the application to make outbound connections to this
upstream. Defaults to `127.0.0.1`.
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-05 01:54:31 +00:00
- `local_bind_socket_path` `(string: "")` - Specifies the path at which to bind a Unix
domain socket listener for the application to make outbound connections to
this upstream. This conflicts with specifying the local_bind_port
or local_bind_address. This is only supported when using Envoy as a proxy.
- `local_bind_socket_mode` `(string: "")` - Specifies the (optional) Unix octal
file permissions to use for the socket.
2020-04-06 20:27:35 +00:00
- `destination_type` `(string: "")` - Specifies the type of discovery
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
query to use to find an instance to connect to. Valid values are `service` or
`prepared_query`. Defaults to `service`.
2020-04-06 20:27:35 +00:00
- `datacenter` `(string: "")` - Specifies the datacenter to issue the
discovery query to. Defaults to the local datacenter.
2020-04-06 20:27:35 +00:00
- `config` `(object: {})` - Specifies opaque configuration options that
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
will be provided to the proxy instance for this specific upstream. Can contain
any valid JSON object. This might be used to configure proxy-specific features
like timeouts or retries for the given upstream. See the [built-in proxy
configuration
2020-04-09 23:46:54 +00:00
reference](/docs/connect/proxies/built-in#proxy-upstream-config-key-reference) for
[docs] Reorganize connect documentation for clarity (#5864) * clarify possibilities for centralized proxy configuration * add line breaks to config entries file * add info about centralized config to built in proxy doc * mondify connect landing page to help with navigation * move internals details to its own page * link fixes and shortening text on main page * put built-in proxy options on its own page * add configuration details for connect * clarify security title and add observability page * reorganize menu * remove observability from configuration section * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/index.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/agent/config_entries.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * rename connect section to include service mesh * reorganize sections per suggestions from paul * add configuration edits from paul * add internals edits from paul * add observability edits from paul * reorganize pages and menu * Update website/source/docs/connect/configuration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * menu corrections and edits * incorporate some of pauls comments * incorporate more of pauls comments * Update website/source/docs/connect/configuration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/index.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/connect/registration.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * incorporate kaitlin and pavanni feedback * add redirect * fix conflicts in index file * Resolve conflicts in index file * correct links for new organization * Update website/source/docs/connect/proxies.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * Update website/source/docs/connect/registration.html.md Co-Authored-By: Paul Banks <banks@banksco.de> * add title to service registration page
2019-06-14 05:52:50 +00:00
options available when using the built-in proxy. If using Envoy as a proxy,
see [Envoy configuration
2020-04-09 23:46:54 +00:00
reference](/docs/connect/proxies/envoy#proxy-upstream-config-options)
2020-04-06 20:27:35 +00:00
- `mesh_gateway` `(object: {})` - Specifies the mesh gateway configuration
for this proxy. The format is defined in the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference).
2019-07-08 23:40:57 +00:00
### Transparent Proxy Configuration Reference
The following examples show additional configuration for transparent proxies.
Added in v1.10.0.
-> Note that `snake_case` is used here as it works in both [config file and API
registrations](/docs/agent/services#service-definition-parameter-case).
#### Configure a proxy listener for outbound traffic on port 22500
```json
{
"outbound_listener_port": 22500,
"dialed_directly": true
}
```
- `outbound_listener_port` `(int: 15001)` - The port the proxy should listen on for outbound traffic.
This must be the port where outbound application traffic is captured and redirected to.
- `dialed_directly` `(bool: false)` - Determines whether this proxy instance's IP address can be dialed
directly by transparent proxies. Typically transparent proxies dial upstreams using the "virtual"
tagged address, which load balances across instances. Dialing individual instances can be helpful
in cases like stateful services such as a database cluster with a leader.
~> **Note:** Dynamic routing rules such as failovers and redirects do not apply to services dialed directly.
Additionally, the connection is proxied using a TCP proxy with a connection timeout of 5 seconds.
### Mesh Gateway Configuration Reference
2019-07-08 23:40:57 +00:00
The following examples show all possible mesh gateway configurations.
-> Note that `snake_case` is used here as it works in both [config file and API
2020-04-09 23:46:54 +00:00
registrations](/docs/agent/services#service-definition-parameter-case).
2019-07-08 23:40:57 +00:00
#### Using a Local/Egress Gateway in the Local Datacenter
```json
{
"mode": "local"
}
```
#### Direct to a Remote/Ingress in a Remote Datacenter
2020-04-06 20:27:35 +00:00
2019-07-08 23:40:57 +00:00
```json
{
"mode": "remote"
}
```
#### Prevent Using a Mesh Gateway
2020-04-06 20:27:35 +00:00
2019-07-08 23:40:57 +00:00
```json
{
"mode": "none"
}
```
#### Default Mesh Gateway Mode
2020-04-06 20:27:35 +00:00
2019-07-08 23:40:57 +00:00
```json
{
"mode": ""
}
```
2020-04-06 20:27:35 +00:00
- `mode` `(string: "")` - This defines the mode of operation for how
2019-07-08 23:40:57 +00:00
upstreams with a remote destination datacenter get resolved.
- `"local"` - Mesh gateway services in the local datacenter will be used
2020-04-06 20:27:35 +00:00
as the next-hop destination for the upstream connection.
2019-07-08 23:40:57 +00:00
- `"remote"` - Mesh gateway services in the remote/target datacenter will
2020-04-06 20:27:35 +00:00
be used as the next-hop destination for the upstream connection.
2019-07-08 23:40:57 +00:00
- `"none"` - No mesh gateway services will be used and the next-hop destination
2020-04-06 20:27:35 +00:00
for the connection will be directly to the final service(s).
2019-07-08 23:40:57 +00:00
- `""` - Default mode. The default mode will be `"none"` if no other configuration
2020-04-06 20:27:35 +00:00
enables them. The order of precedence for setting the mode is
1. Upstream
2. Proxy Service's `Proxy` configuration
3. The `service-defaults` configuration for the service.
4. The `global` `proxy-defaults`.
### Expose Paths Configuration Reference
The following examples show possible configurations to expose HTTP paths through Envoy.
2020-04-06 20:27:35 +00:00
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
non-Connect-enabled applications to contact an HTTP endpoint.
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks.
-> Note that `snake_case` is used here as it works in both [config file and API
2020-04-09 23:46:54 +00:00
registrations](/docs/agent/services#service-definition-parameter-case).
#### Expose listeners in Envoy for HTTP and GRPC checks registered with the local Consul agent
```json
{
"expose": {
"checks": true
2020-04-06 20:27:35 +00:00
}
}
```
#### Expose an HTTP listener in Envoy at port 21500 that routes to an HTTP server listening at port 8080
```json
{
"expose": {
"paths": [
{
"path": "/healthz",
"local_path_port": 8080,
"listener_port": 21500
}
]
2020-04-06 20:27:35 +00:00
}
}
```
#### Expose an HTTP2 listener in Envoy at port 21501 that routes to a gRPC server listening at port 9090
```json
{
"expose": {
"paths": [
{
"path": "/grpc.health.v1.Health/Check",
"protocol": "http2",
"local_path_port": 9090,
"listener_port": 21501
}
]
2020-04-06 20:27:35 +00:00
}
}
```
2020-04-06 20:27:35 +00:00
- `checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
2020-04-09 23:46:54 +00:00
[advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port).
2020-04-06 20:27:35 +00:00
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
Consul on Kubernetes, and Consul agents run in their own pods.
2020-04-06 20:27:35 +00:00
- `paths` `array<Path>: []` - A list of paths to expose through Envoy.
- `path` `(string: "")` - The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.
- `local_path_port` `(int: 0)` - The port where the local service is listening for connections to the path.
2020-04-06 20:27:35 +00:00
- `listener_port` `(int: 0)` - The port where the proxy will listen for connections. This port must be available for
the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
but the proxy registration will not fail.
- `protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.
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-05 01:54:31 +00:00
### Unix Domain Sockets
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-05 01:54:31 +00:00
The following examples show additional configuration for Unix domain sockets.
Added in v1.10.0.
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:
<CodeTabs>
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-05 01:54:31 +00:00
```hcl
upstreams = [
{
destination_name = "service-1"
local_bind_socket_path = "/tmp/socket_service_1"
local_bind_socket_mode = "0700"
}
]
```
```json
"upstreams": [
{
"destination_name": "service-1",
"local_bind_socket_path": "/tmp/socket_service_1",
"local_bind_socket_mode": "0700"
}
]
```
</CodeTabs>
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-05 01:54:31 +00:00
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 the
[Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#envoy-v3-api-msg-config-core-v3-pipe)
for details.
-> These options conflict with the `local_bind_socket_port` and
`local_bind_socket_address` options. For a given upstream the proxy can bind either to an IP port or
a Unix socket, but not both.
Similarly 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.
<CodeTabs>
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-05 01:54:31 +00:00
```hcl
services {
name = "service-2"
socket_path = "/tmp/socket_service_2"
}
```
```json
"services": {
"name": "service-2",
"socket_path": "/tmp/socket_service_2"
}
```
</CodeTabs>
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-05 01:54:31 +00:00
Or in the proxy definition:
<CodeTabs>
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-05 01:54:31 +00:00
```hcl
services {
name = "socket_service_2"
connect {
sidecar_service {
proxy {
name = "service-2"
local_service_socket_path = "/tmp/socket_service_2"
...
}
}
}
}
```
```json
"services": {
"name": "socket_service_2",
"connect": {
"sidecar_service": {
"proxy": {
"name": "service-2",
"local_service_socket_path": "/tmp/socket_service_2"
...
}
}
}
}
```
</CodeTabs>
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-05 01:54:31 +00:00
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 options.