mirror of
https://github.com/status-im/consul.git
synced 2025-01-13 07:14:37 +00:00
Ingress and Terminating Gateway docs (#7710)
This PR contains documentation additions for ingress and terminating gateways. New pages for the config-entries and overall feature description were added, as well as various additions to related pages. Co-authored-by: Jono Sosulska <42216911+jsosulska@users.noreply.github.com> Co-authored-by: freddygv <gh@freddygv.xyz> Co-authored-by: Freddy <freddygv@users.noreply.github.com> Co-authored-by: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
This commit is contained in:
Chris Piraino
GitHub
parent
f1bc1ff0dc
commit
98005a79c4
@ -115,11 +115,13 @@ export default [
|
||||
{
|
||||
category: 'config-entries',
|
||||
content: [
|
||||
'ingress-gateway',
|
||||
'proxy-defaults',
|
||||
'service-defaults',
|
||||
'service-resolver',
|
||||
'service-router',
|
||||
'service-splitter',
|
||||
'service-resolver',
|
||||
'service-defaults',
|
||||
'proxy-defaults',
|
||||
'terminating-gateway',
|
||||
],
|
||||
},
|
||||
'cloud-auto-join',
|
||||
@ -156,6 +158,8 @@ export default [
|
||||
},
|
||||
'mesh_gateway',
|
||||
'wan-federation-via-mesh-gateways',
|
||||
'ingress_gateway',
|
||||
'terminating_gateway',
|
||||
{
|
||||
category: 'registration',
|
||||
content: ['service-registration', 'sidecar-service'],
|
||||
|
||||
@ -513,13 +513,14 @@ service definition keys for compatibility with the config file format.
|
||||
|
||||
- `Kind` `(string: "")` - The kind of service. Defaults to "" which is a
|
||||
typical Consul service. This value may also be "connect-proxy" for
|
||||
services that are [Connect-capable](/docs/connect)
|
||||
proxies representing another service or "mesh-gateway" for instances of
|
||||
a [mesh gateway](/docs/connect/mesh_gateway)
|
||||
[Connect](/docs/connect) proxies representing another service,
|
||||
"mesh-gateway" for instances of a [mesh gateway](/docs/connect/mesh_gateway),
|
||||
"terminating-gateway" for instances of a [terminating gateway](/docs/connect/terminating_gateway),
|
||||
or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/ingress_gateway).
|
||||
|
||||
- `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a
|
||||
Connect proxy instance. This is only valid if `Kind == "connect-proxy"` or
|
||||
`Kind == "mesh-gateway"`. See the [Proxy documentation](/docs/connect/registration/service-registration)
|
||||
Connect service proxy instance. This is only valid if `Kind` defines a proxy or gateway.
|
||||
See the [Proxy documentation](/docs/connect/registration/service-registration)
|
||||
for full details.
|
||||
|
||||
- `Connect` `(Connect: nil)` - Specifies the
|
||||
|
||||
@ -575,7 +575,7 @@ $ curl \
|
||||
service instance. This includes both the address as well as the port.
|
||||
|
||||
- `ServiceKind` is the kind of service, usually "". See the Agent
|
||||
registration API for more information.
|
||||
[service registration API](/api/agent/service#kind) for more information.
|
||||
|
||||
- `ServiceProxy` is the proxy config as specified in
|
||||
[Connect Proxies](/docs/connect/proxies).
|
||||
|
||||
@ -25,20 +25,26 @@ Name = "<name of entry>"
|
||||
|
||||
The supported `Kind` names for configuration entries are:
|
||||
|
||||
- [`ingress-gateway`](/docs/agent/config-entries/ingress-gateway) - defines the
|
||||
configuration for an ingress gateway
|
||||
|
||||
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls
|
||||
proxy configuration
|
||||
|
||||
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
|
||||
defaults for all the instances of a given service
|
||||
|
||||
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
|
||||
service instances with a specific Connect upstream discovery requests
|
||||
|
||||
- [`service-router`](/docs/agent/config-entries/service-router) - defines
|
||||
where to send layer 7 traffic based on the HTTP route
|
||||
|
||||
- [`service-splitter`](/docs/agent/config-entries/service-splitter) - defines
|
||||
how to divide requests for a single HTTP route based on percentages
|
||||
|
||||
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
|
||||
service instances with a specific Connect upstream discovery requests
|
||||
|
||||
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
|
||||
defaults for all the instances of a given service
|
||||
|
||||
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls
|
||||
proxy configuration
|
||||
|
||||
- [`terminating-gateway`](/docs/agent/config-entries/terminating-gateway) - defines the
|
||||
services associated with terminating gateway
|
||||
|
||||
## Managing Configuration Entries
|
||||
|
||||
|
||||
159
website/pages/docs/agent/config-entries/ingress-gateway.mdx
Normal file
159
website/pages/docs/agent/config-entries/ingress-gateway.mdx
Normal file
@ -0,0 +1,159 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: 'Configuration Entry Kind: Ingress Gateway'
|
||||
sidebar_title: ingress-gateway
|
||||
description: >-
|
||||
The `ingress-gateway` config entry kind allows for configuring Ingress gateways
|
||||
with listeners that expose a set of services outside the Consul service mesh.
|
||||
---
|
||||
|
||||
# Ingress Gateway
|
||||
|
||||
-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer.
|
||||
|
||||
The `ingress-gateway` config entry kind allows you to configure ingress gateways
|
||||
with listeners that expose a set of services outside the Consul service mesh.
|
||||
See [Ingress Gateway](/docs/connect/ingress_gateway) for more information.
|
||||
|
||||
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
|
||||
across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different
|
||||
sets of services within their datacenter then the ingress gateways **must** be registered with different names.
|
||||
|
||||
See [Ingress Gateway](/docs/connect/ingress_gateway) for more information.
|
||||
|
||||
## Wildcard service specification
|
||||
|
||||
Ingress gateways can optionally target all services within a Consul namespace by
|
||||
specifying a wildcard `*` as the service name. A wildcard specifier allows
|
||||
for a single listener to route traffic to all available services on the
|
||||
Consul service mesh, differentiating between the services by their host/authority
|
||||
header.
|
||||
|
||||
A wildcard specifier provides the following properties for an ingress
|
||||
gateway:
|
||||
- All services with the same
|
||||
[protocol](/docs/agent/config-entries/ingress-gateway#protocol) as the
|
||||
listener will be routable.
|
||||
- The ingress gateway will route traffic based on the host/authority header,
|
||||
expecting a value matching `<service-name>.*`, or if using namespaces,
|
||||
`<service-name>.ingress.<namespace>.*`.
|
||||
|
||||
A wildcard specifier cannot be set on a listener of protocol `tcp`.
|
||||
|
||||
## Sample Config Entries
|
||||
|
||||
Set up a TCP listener for a single service:
|
||||
|
||||
```hcl
|
||||
Kind = "ingress-gateway"
|
||||
Name = "ingress-service"
|
||||
|
||||
Listeners = [
|
||||
{
|
||||
Port = 3456
|
||||
Protocol = "tcp"
|
||||
Services = [
|
||||
{
|
||||
Name = "db"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Set up a wildcard HTTP listener to proxy traffic to all available services,
|
||||
make two services available over a custom port with user-provided hosts, and
|
||||
enable TLS on every listener:
|
||||
|
||||
```hcl
|
||||
Kind = "ingress-gateway"
|
||||
Name = "ingress-service"
|
||||
|
||||
TLS {
|
||||
Enabled = true
|
||||
}
|
||||
|
||||
Listeners = [
|
||||
{
|
||||
Port = 8080
|
||||
Protocol = "http"
|
||||
Services = [
|
||||
{
|
||||
Name = "*"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
Port = 4567
|
||||
Protocol = "http"
|
||||
Services = [
|
||||
{
|
||||
Name = "api"
|
||||
Hosts = ["foo.example.com"]
|
||||
},
|
||||
{
|
||||
Name = "web"
|
||||
Hosts = ["website.example.com"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Available Fields
|
||||
|
||||
- `Kind` - Must be set to `ingress-gateway`
|
||||
|
||||
- `Name` `(string: <required>)` - Set to the name of the gateway being configured.
|
||||
|
||||
- `Namespace` `(string: "default")` - <EnterpriseAlert inline /> Specifies
|
||||
the namespace the config entry will apply to. This must be the namespace
|
||||
the gateway is registered in. If omitted, the namespace will be inherited
|
||||
from [the request](/api/config#ns) or will default to the `default` namespace.
|
||||
|
||||
- `TLS` `(TLSConfig: <optional>)` - TLS configuration for this gateway.
|
||||
|
||||
- `Enabled` `(bool: false)` - Set this configuration to enable TLS for
|
||||
every listener on the gateway.
|
||||
|
||||
- `Listeners` `(array<IngressListener>: <optional>)` - A list of listeners that
|
||||
the ingress gateway should setup, uniquely identified by their port number.
|
||||
|
||||
- `Port` `(int: 0)` - The port that the listener should receive traffic on.
|
||||
|
||||
- `Protocol` `(string: "tcp")` - The protocol associated with the listener.
|
||||
This can be any protocol supported by
|
||||
[service-defaults](/docs/agent/config-entries/service-defaults#protocol).
|
||||
|
||||
- `Services` `(array<IngressService>: <optional>)` - A list of services to be
|
||||
exposed via this listener. For "tcp" listeners, only a single service is
|
||||
allowed.
|
||||
|
||||
- `Name` `(string: "")` - The name of the service that should be exposed
|
||||
through this listener. This can be either a service registered in the
|
||||
catalog, or a service defined only by [other config
|
||||
entries](/docs/connect/l7-traffic-management). If the wildcard specifier,
|
||||
`*`, is provided, then ALL services will be exposed through the listener.
|
||||
This is not supported for listener's with protocol "tcp".
|
||||
|
||||
- `Namespace` `(string: "")` - <EnterpriseAlert inline /> The namespace to resolve the service from
|
||||
instead of the current namespace. If empty the current namespace is
|
||||
assumed.
|
||||
|
||||
- `Hosts` `(array<string>: <optional>)` - A list of hosts that specify what
|
||||
requests will match to this service. This cannot be used with a `tcp`
|
||||
listener, and cannot be specified alongside a `*` service name.
|
||||
|
||||
If TLS is enabled, then each host will be added as a DNSSAN to the
|
||||
gateway's x509 certificate.
|
||||
|
||||
## ACLs
|
||||
|
||||
Configuration entries may be protected by
|
||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
|
||||
|
||||
Reading an `ingress-gateway` config entry requires `service:read` on the `Name`
|
||||
field of the config entry.
|
||||
|
||||
Creating, updating, or deleting an `ingress-gateway` config entry requires
|
||||
`operator:write`.
|
||||
158
website/pages/docs/agent/config-entries/terminating-gateway.mdx
Normal file
158
website/pages/docs/agent/config-entries/terminating-gateway.mdx
Normal file
@ -0,0 +1,158 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: 'Configuration Entry Kind: Terminating Gateway'
|
||||
sidebar_title: terminating-gateway
|
||||
description: >-
|
||||
The `terminating-gateway` config entry kind allows for configuring terminating gateways
|
||||
to proxy traffic from services in the Consul service mesh to services outside the mesh.
|
||||
---
|
||||
|
||||
# Terminating Gateway
|
||||
|
||||
-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer.
|
||||
|
||||
The `terminating-gateway` config entry kind you to configure terminating gateways
|
||||
to proxy traffic from services in the Consul service mesh to services registered with Consul that do not have a
|
||||
[Connect service sidecar proxy](/docs/connect/proxies). The configuration is associated with the name of a gateway service
|
||||
and will apply to all instances of the gateway with that name.
|
||||
|
||||
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
|
||||
across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different
|
||||
sets of services within their datacenter then the ingress gateways **must** be registered with different names.
|
||||
|
||||
See [Terminating Gateway](/docs/connect/terminating_gateway) for more information.
|
||||
|
||||
## TLS Origination
|
||||
By specifying a path to a [CA file](/docs/agent/config-entries/terminating-gateway#cafile) connections
|
||||
from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a
|
||||
[client certificate](/docs/agent/config-entries/terminating-gateway#certfile)
|
||||
and [private key](/docs/agent/config-entries/terminating-gateway#keyfile) are also specified connections
|
||||
from the terminating gateway will be encrypted using mutual TLS authentication.
|
||||
|
||||
If none of these are provided, Consul will **only** encrypt connections to the gateway and not
|
||||
from the gateway to the destination service.
|
||||
|
||||
## Wildcard service specification
|
||||
|
||||
Terminating gateways can optionally target all services within a Consul namespace by specifying a wildcard "*"
|
||||
as the service name. Configuration options set on the wildcard act as defaults that can be overridden
|
||||
by options set on a specific service name.
|
||||
|
||||
Note that if the wildcard specifier is used, and some services in that namespace have a Connect sidecar proxy,
|
||||
traffic from the mesh to those services will be evenly load-balanced between the gateway and their sidecars.
|
||||
|
||||
## Sample Config Entries
|
||||
|
||||
Link gateway "us-west-gateway" with the billing service:
|
||||
|
||||
```hcl
|
||||
Kind = "terminating-gateway"
|
||||
Name = "us-west-gateway"
|
||||
Services = [
|
||||
{
|
||||
Name = "billing"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Link gateway "us-west-gateway" with the api service and specify a CA file for one-way TLS authentication:
|
||||
|
||||
```hcl
|
||||
Kind = "terminating-gateway"
|
||||
Name = "us-west-gateway"
|
||||
Services = [
|
||||
{
|
||||
Name = "api"
|
||||
CAFile = "/etc/certs/ca-chain.cert.pem"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Link gateway "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication:
|
||||
|
||||
```hcl
|
||||
Kind = "terminating-gateway"
|
||||
Name = "us-west-gateway"
|
||||
Services = [
|
||||
{
|
||||
Name = "payments"
|
||||
CAFile = "/etc/certs/ca-chain.cert.pem"
|
||||
KeyFile = "/etc/certs/gateway.key.pem"
|
||||
CertFile = "/etc/certs/gateway.cert.pem"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Link gateway "us-west-gateway" with all services in the finance namespace, and configure default certificates for mutual TLS.
|
||||
Also override the SNI and CA file used for connections to the billing service:
|
||||
|
||||
```hcl
|
||||
Kind = "terminating-gateway"
|
||||
Name = "us-west-gateway"
|
||||
Namespace = "default"
|
||||
Services = [
|
||||
{
|
||||
Namespace = "finance"
|
||||
Name = "*"
|
||||
CAFile = "/etc/common-certs/ca-chain.cert.pem"
|
||||
KeyFile = "/etc/common-certs/gateway.key.pem"
|
||||
CertFile = "/etc/common-certs/gateway.cert.pem"
|
||||
},
|
||||
{
|
||||
Namespace = "finance"
|
||||
Name = "billing"
|
||||
CAFile = "/etc/billing-ca/ca-chain.cert.pem"
|
||||
SNI = "billing.service.com"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Available Fields
|
||||
|
||||
- `Kind` - Must be set to `terminating-gateway`
|
||||
|
||||
- `Name` `(string: <required>)` - Set to the name of the gateway being configured.
|
||||
|
||||
- `Namespace` `(string: "default")` - <EnterpriseAlert inline /> Specifies the namespace
|
||||
the config entry will apply to. This must be the namespace the gateway is registered in.
|
||||
If omitted, the namespace will be inherited from [the request](/api/config#ns)
|
||||
or will default to the `default` namespace.
|
||||
|
||||
- `Services` `(array<LinkedService>: <optional>)` - A list of services to link
|
||||
with the gateway. The gateway will proxy traffic to these services. These linked services
|
||||
must be registered with Consul for the gateway to discover their addresses. They must also
|
||||
be registered in the same Consul datacenter as the terminating gateway.
|
||||
|
||||
- `Name` `(string: "")` - The name of the service to link with the gateway.
|
||||
If the wildcard specifier, `*`, is provided, then ALL services within the namespace
|
||||
will be linked with the gateway.
|
||||
|
||||
- `Namespace` `(string: "")` - <EnterpriseAlert inline /> The namespace of the service.
|
||||
If omitted, the namespace will be inherited from the config entry.
|
||||
|
||||
- `CAFile` `(string: "")` - A file path to a PEM-encoded certificate authority.
|
||||
The file must be present on the proxy's filesystem.
|
||||
The certificate authority is used to verify the authenticity of the service linked with the gateway.
|
||||
It can be provided along with a CertFile and KeyFile for mutual TLS authentication, or on its own
|
||||
for one-way TLS authentication. If none is provided the gateway **will not** encrypt the traffic to the destination.
|
||||
|
||||
- `CertFile` `(string: "")` - A file path to a PEM-encoded certificate.
|
||||
The file must be present on the proxy's filesystem.
|
||||
The certificate is provided servers to verify the gateway's authenticity. It must be provided if a KeyFile was specified.
|
||||
|
||||
- `KeyFile` `(string: "")` - A file path to a PEM-encoded private key.
|
||||
The file must be present on the proxy's filesystem.
|
||||
The key is used with the certificate to verify the gateway's authenticity. It must be provided along if a CertFile was specified.
|
||||
|
||||
- `SNI` `(string: "")` - An optional hostname or domain name to specify during the TLS handshake.
|
||||
|
||||
## ACLs
|
||||
|
||||
Configuration entries may be protected by
|
||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
|
||||
|
||||
Reading a `terminating-gateway` config entry requires `service:read` on the `Name`
|
||||
field of the config entry.
|
||||
|
||||
Creating, updating, or deleting a `terminating-gateway` config entry requires
|
||||
`operator:write`.
|
||||
@ -256,6 +256,22 @@ and doesn't support tags. This DNS interface will be expanded over time.
|
||||
If you need more complex behavior, please use the
|
||||
[catalog API](/api/catalog).
|
||||
|
||||
### Ingress Service Lookups
|
||||
|
||||
To find ingress-enabled services:
|
||||
|
||||
```text
|
||||
<service>.ingress.<domain>
|
||||
```
|
||||
|
||||
This will find all [ingress gateway](/docs/connect/ingress_gateway)
|
||||
endpoints for the given `service`.
|
||||
|
||||
This endpoint currently only finds services within the same datacenter
|
||||
and doesn't support tags. This DNS interface will be expanded over time.
|
||||
If you need more complex behavior, please use the
|
||||
[catalog API](/api/catalog).
|
||||
|
||||
### UDP Based DNS Queries
|
||||
|
||||
When the DNS query is performed using UDP, Consul will truncate the results
|
||||
|
||||
@ -189,11 +189,14 @@ for the available configuration options.
|
||||
### Connect
|
||||
|
||||
The `kind` field is used to optionally identify the service as a [Connect
|
||||
proxy](/docs/connect/proxies) instance with the value `connect-proxy` or
|
||||
a [Mesh Gateway](/docs/connect/mesh_gateway) instance with the value `mesh-gateway`. For
|
||||
typical non-proxy instances the `kind` field must be omitted. The `proxy` field
|
||||
proxy](/docs/connect/proxies) instance. This value may be "connect-proxy" for
|
||||
[Connect-capable](/docs/connect) proxies representing another service,
|
||||
"mesh-gateway" for instances of a [mesh gateway](/docs/connect/mesh_gateway),
|
||||
"terminating-gateway" for instances of a [terminating gateway](/docs/connect/terminating_gateway),
|
||||
or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/ingress_gateway).
|
||||
For typical non-proxy instances the `kind` field must be omitted. The `proxy` field
|
||||
is also required for Connect proxy registrations and is only valid if `kind` is
|
||||
`connect-proxy`. The only required `proxy` field is `destination_service_name`.
|
||||
`connect-proxy`. The only required `proxy` field for a `connect-proxy` is `destination_service_name`.
|
||||
For more detail please see [complete proxy configuration
|
||||
example](/docs/connect/registration/service-registration#complete-configuration-example)
|
||||
|
||||
|
||||
@ -103,7 +103,7 @@ proxy configuration needed.
|
||||
#### Envoy Gateway Options
|
||||
|
||||
- `-gateway` - Flag to indicate that Envoy should be configured as a Gateway.
|
||||
Must be one of: `terminating` or `mesh`.
|
||||
Must be one of: `terminating`, `ingress`, or `mesh`.
|
||||
If multiple gateways are managed by the same local agent then
|
||||
`-proxy-id` should be used as well to specify the instance this represents.
|
||||
|
||||
@ -127,12 +127,6 @@ proxy configuration needed.
|
||||
- `-deregister-after-critical` - The amount of time the gateway services health check can
|
||||
be failing before being deregistered. This flag is used in combination with `-register`
|
||||
|
||||
-> **Note:** If ACLs are enabled, a token granting `service:write` for the
|
||||
gateway's service name must be passed using the `-token` option or
|
||||
`CONSUL_HTTP_TOKEN` environment variable. This token authorizes the proxy
|
||||
to obtain receive and route communications for other Connect services but
|
||||
does not allow decrypting any of their communications.
|
||||
|
||||
## Examples
|
||||
|
||||
Assume a local service instance is registered on the local agent with a
|
||||
@ -180,7 +174,7 @@ $ consul connect envoy -sidecar-for db -admin-bind localhost:19001
|
||||
|
||||
### Mesh Gateways
|
||||
|
||||
The mesh gateway Envoy process can be started with.
|
||||
The mesh gateway Envoy process can be auto-registered and started with the following command.
|
||||
|
||||
```shell
|
||||
$ consul connect envoy -gateway=mesh -register \
|
||||
@ -190,13 +184,22 @@ $ consul connect envoy -gateway=mesh -register \
|
||||
|
||||
### Terminating Gateways
|
||||
|
||||
The terminating gateway Envoy process can be started with.
|
||||
The terminating gateway Envoy process can be auto-registered and started with the following command.
|
||||
|
||||
```shell
|
||||
$ consul connect envoy -gateway=terminating -register \
|
||||
$ consul connect envoy -gateway=terminating -register -service my-gateway \
|
||||
-address '{{ GetInterfaceIP "eth0" }}:8443'
|
||||
```
|
||||
|
||||
### Ingress Gateways
|
||||
|
||||
The ingress gateway Envoy process can be auto-registered and started with the following command.
|
||||
|
||||
```shell
|
||||
$ consul connect envoy -gateway=ingress -register -service ingress-service \
|
||||
-address '{{ GetInterfaceIP "eth0" }}:8888'
|
||||
```
|
||||
|
||||
## Exec Security Details
|
||||
|
||||
The command needs to pass the bootstrap config through to Envoy. Envoy currently
|
||||
|
||||
@ -46,6 +46,13 @@ Create an intention to allow "web" to talk to "db":
|
||||
$ consul intention create web db
|
||||
```
|
||||
|
||||
Create an intention to deny "db" from initiating connections to _any_ service:
|
||||
|
||||
```shell
|
||||
$ consul intention create -deny db '*'
|
||||
Created: db => * (deny)
|
||||
```
|
||||
|
||||
Test whether a "web" is allowed to connect to "db":
|
||||
|
||||
```shell
|
||||
|
||||
83
website/pages/docs/connect/ingress_gateway.mdx
Normal file
83
website/pages/docs/connect/ingress_gateway.mdx
Normal file
@ -0,0 +1,83 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Connect - Ingress Gateways
|
||||
sidebar_title: Ingress Gateways
|
||||
description: >-
|
||||
An ingress gateway enables ingress traffic from services outside the Consul
|
||||
service mesh to services inside the Consul service mesh. This section details
|
||||
how to use Envoy and describes how you can plug in a gateway of your choice.
|
||||
---
|
||||
|
||||
# Ingress Gateways
|
||||
|
||||
-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer.
|
||||
|
||||
Ingress gateways enable ingress traffic from services outside the Consul
|
||||
service mesh to services inside the Consul service mesh. An ingress gateway is
|
||||
a type of proxy and must be registered as a service in Consul, with the
|
||||
[kind](/api/agent/service#kind) set to "ingress-gateway". They are an
|
||||
entrypoint for outside traffic and allow you to define what services should be
|
||||
exposed and on what port. You configure an ingress gateway by defining a set of
|
||||
[listeners](/docs/agent/config-entries/ingress-gateway#listeners) that each map
|
||||
to a set of backing
|
||||
[services](/docs/agent/config-entries/ingress-gateway#services).
|
||||
|
||||
Depending on the
|
||||
[protocol](/docs/agent/config-entries/ingress-gateway#protocol) defined for a
|
||||
listener, multiple services can be specified for a single listener. In this
|
||||
case, the ingress gateway relies on host/authority headers to decide the
|
||||
service that should receive the traffic.
|
||||
|
||||
To enable easier service discovery, a new Consul [DNS
|
||||
subdomain](/docs/agent/dns#ingress-service-lookups) is provided, on
|
||||
`<service>.ingress.<domain>`.
|
||||
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Ingress gateways also require that your Consul datacenters are configured correctly:
|
||||
|
||||
- You'll need to use Consul version 1.8.0.
|
||||
- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers.
|
||||
- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents.
|
||||
|
||||
Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul.
|
||||
|
||||
## Running and Using an Ingress Gateway
|
||||
|
||||
You must complete the following steps to configure an ingress gateway to proxy traffic to services in the Consul service mesh:
|
||||
|
||||
1. On a host with a Consul client agent, start an Envoy proxy using the [envoy
|
||||
subcommand](/docs/commands/connect/envoy), specifying the `ingress` gateway
|
||||
type:
|
||||
```shell
|
||||
$ consul connect envoy -gateway=ingress -register -service ingress-service \
|
||||
-address '{{ GetInterfaceIP "eth0" }}:8888'
|
||||
```
|
||||
|
||||
2. Create and apply an `ingress-gateway` [configuration entry](/docs/agent/config-entries/ingress-gateway) that defines
|
||||
a set of listeners that expose the desired backing services. The config entry can be applied via the
|
||||
[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).
|
||||
|
||||
3. Ensure that [Consul intentions](/docs/commands/intention) are setup to allow connections from the ingress gateway to the backing services.
|
||||
|
||||
4. **Optionally** use the `<service>.ingress.<domain>` [DNS subdomain](/docs/agent/dns#ingress-service-lookups) to discover the ingress
|
||||
gateways for a service.
|
||||
|
||||
## Ingress Gateway Configuration
|
||||
|
||||
Ingress gateways are configured in service definitions and registered with Consul like other services, with two exceptions.
|
||||
The first is that the [kind](/api/agent/service#kind) must be "ingress-gateway". Second,
|
||||
the ingress gateway service definition may contain a `Proxy.Config` entry just like a
|
||||
Connect proxy service, to define opaque configuration parameters useful for the actual proxy software.
|
||||
For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as
|
||||
[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides).
|
||||
|
||||
-> **Note:** If ACLs are enabled, a token granting `service:write` for the gateway's service name
|
||||
and `service:read` for all services in the datacenter. These permissions authorize the token to route
|
||||
communications for other Connect services.
|
||||
|
||||
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
|
||||
across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different
|
||||
sets of services within their datacenter then the ingress gateways **must** be registered with different names.
|
||||
@ -77,9 +77,16 @@ your network, the proxy's connection to the gateway can happen in one of the fol
|
||||
|
||||
## Mesh Gateway Configuration
|
||||
|
||||
Mesh gateways are defined very similarly to other typical services. The one exception is that a mesh gateway
|
||||
service definition may contain a `Proxy.Config` entry just like a Connect proxy service to define opaque
|
||||
configuration parameters useful for the actual proxy software.
|
||||
Mesh gateways are defined similarly to other services registered with Consul, with two exceptions.
|
||||
The first is that the [service kind](/api/agent/service#kind) must be "mesh-gateway". Second,
|
||||
the mesh gateway service definition may contain a `Proxy.Config` entry just like a
|
||||
Connect proxy service, to define opaque configuration parameters useful for the actual proxy software.
|
||||
For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as
|
||||
[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides).
|
||||
|
||||
-> **Note:** If ACLs are enabled, a token granting `service:write` for the gateways service name
|
||||
and `service:read` for all services in the datacenter. These permissions authorize the token to route
|
||||
communications for other Connect services but does not allow decrypting any of their communications.
|
||||
|
||||
## Connect Proxy Configuration
|
||||
|
||||
|
||||
134
website/pages/docs/connect/terminating_gateway.mdx
Normal file
134
website/pages/docs/connect/terminating_gateway.mdx
Normal file
@ -0,0 +1,134 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Connect - Terminating Gateways
|
||||
sidebar_title: Terminating Gateways
|
||||
description: >-
|
||||
A terminating gateway enables traffic from services in the Consul
|
||||
service mesh to services outside the mesh. This section details
|
||||
how to configure and run a terminating gateway.
|
||||
---
|
||||
|
||||
# Terminating Gateways
|
||||
|
||||
-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer.
|
||||
|
||||
Terminating gateways enable connections from services in the Consul service mesh to
|
||||
services outside the mesh. These gateways effectively act as Connect proxies that can
|
||||
represent more than one service. They terminate Connect mTLS connections, enforce intentions,
|
||||
and forward requests to the appropriate destination.
|
||||
|
||||
|
||||
|
||||
~> **Beta limitations:** Terminating Gateways currently do not support targeting service subsets with
|
||||
[L7 configuration](/docs/connect/l7-traffic-management). They route to all instances of a service with no capabilities
|
||||
for filtering by instance. Terminating Gateways also currently do not support routing to services with a hostname
|
||||
defined as a their address. The service address registered with Consul, that the gateway will route traffic to, **must** be a resolved IP address.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
~> We recommend that terminating gateways are not exposed to the WAN or open internet. This is because terminating gateways
|
||||
hold certificates to decrypt Consul Connect traffic directed at them and may be configured with credentials to connect
|
||||
to linked services. Connections over the WAN or open internet should flow through [mesh gateways](/docs/connect/mesh_gateway)
|
||||
whenever possible since they are not capable of decrypting traffic or connecting directly to services.
|
||||
|
||||
By specifying a path to a [CA file](/docs/agent/config-entries/terminating-gateway#cafile) connections
|
||||
from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a
|
||||
[client certificate](/docs/agent/config-entries/terminating-gateway#certfile)
|
||||
and [private key](/docs/agent/config-entries/terminating-gateway#keyfile) are also specified connections
|
||||
from the terminating gateway will be encrypted using mutual TLS authentication.
|
||||
|
||||
If none of these are provided, Consul will **only** encrypt connections to the gateway and not
|
||||
from the gateway to the destination service.
|
||||
|
||||
-> **Note:** If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS.
|
||||
Client applications can issue plain HTTP requests even when connecting to servers that require HTTPS.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Each terminating gateway needs:
|
||||
|
||||
1. A local Consul client agent to manage its configuration.
|
||||
2. General network connectivity to services within its local Consul datacenter.
|
||||
|
||||
Terminating gateways also require that your Consul datacenters are configured correctly:
|
||||
|
||||
- You'll need to use Consul version 1.8.0.
|
||||
- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers.
|
||||
- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents.
|
||||
|
||||
Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with terminating gateway capabilities in Consul.
|
||||
|
||||
- Terminating gateway proxies receive their configuration through Consul, which
|
||||
automatically generates it based on the gateway's registration. Currently Consul
|
||||
can only translate terminating gateway registration information into Envoy
|
||||
configuration, therefore the proxies acting as terminating gateways must be Envoy.
|
||||
|
||||
Connect proxies that send upstream traffic through a gateway aren't
|
||||
affected when you deploy terminating gateways. If you are using non-Envoy proxies as
|
||||
Connect proxies they will continue to work for traffic directed at services linked to
|
||||
a terminating gateway as long as they discover upstreams with the
|
||||
[/health/connect](/api/health#list-nodes-for-connect-capable-service) endpoint.
|
||||
|
||||
## Running and Using a Terminating Gateway
|
||||
|
||||
You must complete the following steps to configure a terminating gateway to proxy traffic from services in the Consul service mesh:
|
||||
|
||||
1. On a host with a Consul client agent, start an Envoy proxy using the [envoy subcommand](/docs/commands/connect/envoy#terminating-gateways) and
|
||||
specifying the `terminating` gateway type:
|
||||
```shell
|
||||
$ consul connect envoy -gateway=terminating -register -service us-west-gateway \
|
||||
-address '{{ GetInterfaceIP "eth0" }}:8443'
|
||||
```
|
||||
|
||||
2. Create and apply a `terminating-gateway` [configuration entry](/docs/agent/config-entries/terminating-gateway) that defines
|
||||
a set of services that the gateway will proxy traffic to. The config entry can be applied via the
|
||||
[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).
|
||||
|
||||
3. Ensure that [Consul intentions](/docs/commands/intention) are set up to allow connections from the source services in the mesh
|
||||
to the gateway's linked services. The intentions must reference the destination service's name and not the gateway itself.
|
||||
|
||||
4. Ensure necessary [upstreams](/docs/connect/registration/service-registration#upstream-configuration-reference)
|
||||
have been added to service definitions of the source services in the Consul service mesh. Each source service that needs
|
||||
to connect to a service proxied by a terminating gateway will need to add the external service as an upstream destination.
|
||||
|
||||
## Terminating Gateway Configuration
|
||||
|
||||
Terminating gateways are configured in service definitions and registered with Consul like other services, with two exceptions.
|
||||
The first is that the [kind](/api/agent/service#kind) must be "terminating-gateway". Second,
|
||||
the terminating gateway service definition may contain a `Proxy.Config` entry just like a
|
||||
Connect proxy service, to define opaque configuration parameters useful for the actual proxy software.
|
||||
For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as
|
||||
[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides).
|
||||
|
||||
-> **Note:** If ACLs are enabled, the terminating gateways must be registered with a token granting `service:write`
|
||||
for the gateway's service name **and** all linked services. These privileges will authorize the gateway
|
||||
to terminate mTLS connections on behalf of the linked services.
|
||||
|
||||
Linking services to a terminating gateway is done with a `terminating-gateway`
|
||||
[configuration entry](/docs/agent/config-entries/terminating-gateway). This config entry can be applied via the
|
||||
[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).
|
||||
|
||||
Gateways with the same name in Consul's service catalog are configured with a single configuration entry.
|
||||
This means that additional gateway instances registered with the same name will determine their routing based on the existing configuration entry.
|
||||
Adding replicas of a gateway that routes to a particular set of services requires running the
|
||||
[envoy subcommand](/docs/commands/connect/envoy#terminating-gateways) on additional hosts and specifying
|
||||
the same gateway name with the `service` flag.
|
||||
|
||||
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
|
||||
across all federated Consul datacenters. If terminating gateways in different Consul datacenters need to route to different
|
||||
sets of services within their datacenter then the terminating gateways **must** be registered with different names.
|
||||
|
||||
The services that the terminating gateway will proxy for must be registered with Consul, even the services outside the mesh. They must also be registered
|
||||
in the same Consul datacenter as the terminating gateway. Otherwise the terminating gateway will not be able to
|
||||
discover the services' addresses. These services can be registered with a local Consul agent.
|
||||
If there is no agent present, the services can be registered [directly in the catalog](/api/catalog#register-entity)
|
||||
by sending the registration request to a client or server agent on a different host.
|
||||
|
||||
All services registered in the Consul catalog must be associated with a node, even when their node is
|
||||
not managed by a Consul client agent. All agent-less services with the same address can be registered under the same node name and address.
|
||||
However, ensure that the [node name](/api/catalog.html#node) for external services registered directly in the catalog
|
||||
does not match the node name of any Consul client agent node. If the node name overlaps with the node name of a Consul client agent,
|
||||
Consul's [anti-entropy sync](/docs/internals/anti-entropy) will delete the services registered via the `/catalog/register` HTTP API endpoint.
|
||||
|
||||
For a complete example of how to register external services review the
|
||||
[external services guide](https://learn.hashicorp.com/consul/developer-discovery/external).
|
||||
BIN
website/public/img/ingress-gateways.png
Normal file
BIN
website/public/img/ingress-gateways.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 114 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 176 KiB |
BIN
website/public/img/terminating-gateways.png
Normal file
BIN
website/public/img/terminating-gateways.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
Loading…
x
Reference in New Issue
Block a user