Docs/igw docs day refactor (#17259)
* reformatted IGW conf ref * set up nav structure for IGW docs * added main usage IGW usage doc * added usage for serving custom tls certs * updated internal links * Update website/content/docs/connect/config-entries/ingress-gateway.mdx * Apply suggestions from code review Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com> * changed filenames for IGW usage pages * Apply suggestions from code review Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
This commit is contained in:
trujillo-adam
GitHub
parent
e8ccc911af
commit
5937636862
|
|
@ -630,12 +630,12 @@ The `/agent/service/register` endpoint supports camel case and _snake case_ for
|
|||
|
||||
- `Port` `(int: 0)` - Specifies the port of the service.
|
||||
|
||||
- `Kind` `(string: "")` - The kind of service. Defaults to "" which is a
|
||||
typical Consul service. This value may also be "connect-proxy" for
|
||||
[service mesh](/consul/docs/connect) proxies representing another service,
|
||||
"mesh-gateway" for instances of a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration),
|
||||
"terminating-gateway" for instances of a [terminating gateway](/consul/docs/connect/gateways/terminating-gateway),
|
||||
or "ingress-gateway" for instances of a [ingress gateway](/consul/docs/connect/gateways/ingress-gateway).
|
||||
- `Kind` `(string: "")` - The kind of service. Defaults to `""`, which is a
|
||||
typical Consul service. You can specify the following values:
|
||||
- `"connect-proxy"` for [service mesh](/consul/docs/connect) proxies representing another service
|
||||
- `"mesh-gateway"` for instances of a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration)
|
||||
- `"terminating-gateway"` for instances of a [terminating gateway](/consul/docs/connect/gateways/terminating-gateway)
|
||||
- `"ingress-gateway"` for instances of an [ingress gateway](/consul/docs/connect/gateways/ingress-gateway)
|
||||
|
||||
- `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a
|
||||
service mesh proxy instance. This is only valid if `Kind` defines a proxy or gateway.
|
||||
|
|
|
|||
|
|
@ -165,11 +165,9 @@ compatibility with Envoy and prevent potential issues. Default is `false`.
|
|||
If Envoy is configured as a terminating or mesh gateway, traffic from services
|
||||
within the mesh will be received at the specified IP and port.
|
||||
|
||||
If Envoy is configured as an ingress gateway, a `/ready` HTTP endpoint will be
|
||||
instantiated at the specified IP and port. Consul uses `/ready` HTTP endpoints
|
||||
to check gateway health. The specified IP will also be used by the ingress
|
||||
gateway when instantiating user-defined listeners configured in the
|
||||
[ingress gateway](/consul/docs/connect/gateways/ingress-gateway) configuration entry.
|
||||
If Envoy is configured as an ingress gateway, Consul instantiates a `/ready` HTTP endpoint at the specified IP and port. Consul uses `/ready` HTTP endpoints
|
||||
to check gateway health. Ingress gateways also use the specified IP when instantiating user-defined listeners configured in the
|
||||
[ingress gateway configuration entry](/consul/docs/connect/config-entries/ingress-gateway).
|
||||
|
||||
~> **Note**: Ensure that user-defined ingress gateway listeners use a
|
||||
different port than the port specified in `-address` so that they do not
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,281 +0,0 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Ingress Gateway | Service Mesh
|
||||
description: >-
|
||||
Ingress gateways listen for requests from external network locations and route authorized traffic to destinations in the service mesh. Use custom TLS certificates with ingress gateways through Envoy's gRPC Secret Discovery Service (SDS).
|
||||
---
|
||||
|
||||
# Ingress Gateways
|
||||
|
||||
-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer.
|
||||
|
||||
Ingress gateways enable connectivity within your organizational network from services outside the Consul
|
||||
service mesh to services in the mesh. An ingress gateway is
|
||||
a type of proxy and must be registered as a service in Consul, with the
|
||||
[kind](/consul/api-docs/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](/consul/docs/connect/config-entries/ingress-gateway#listeners) that each map
|
||||
to a set of backing
|
||||
[services](/consul/docs/connect/config-entries/ingress-gateway#services).
|
||||
|
||||
To enable easier service discovery, a new Consul [DNS
|
||||
subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups) is provided, on
|
||||
`<service>.ingress.<domain>`.
|
||||
|
||||
For listeners with a
|
||||
[protocol](/consul/docs/connect/config-entries/ingress-gateway#protocol) other than
|
||||
`tcp`, 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. The host used to match traffic
|
||||
defaults to the [Consul DNS ingress
|
||||
subdomain](/consul/docs/services/discovery/dns-static-lookups#ingress-service-lookups), but can be changed using
|
||||
the [hosts](/consul/docs/connect/config-entries/ingress-gateway#hosts) field.
|
||||
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Ingress gateways also require that your Consul datacenters are configured correctly:
|
||||
|
||||
- You'll need to use Consul version 1.8.0 or newer.
|
||||
- Consul [service mesh](/consul/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers.
|
||||
- [gRPC](/consul/docs/agent/config/config-files#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
|
||||
|
||||
For a complete example of how to allow external traffic inside your Consul service mesh,
|
||||
review the [ingress gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-ingress-gateways).
|
||||
|
||||
## 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](/consul/api-docs/agent/service#kind) must be "ingress-gateway". Second,
|
||||
the ingress gateway service definition may contain a `Proxy.Config` entry just like a
|
||||
service mesh proxy service, to define opaque configuration parameters useful for the actual proxy software.
|
||||
For Envoy there are some supported [gateway options](/consul/docs/connect/proxies/envoy#gateway-options) as well as
|
||||
[escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides).
|
||||
|
||||
-> **Note:** If ACLs are enabled, ingress gateways must be registered with a token granting `service:write` for the ingress gateway's service name,
|
||||
`service:read` for all services in the ingress gateway's configuration entry, and `node:read` for all nodes of the services
|
||||
in the ingress gateway's configuration entry. These privileges authorize the token to route communications to other mesh services.
|
||||
If the Consul client agent on the gateway's node is not configured to use the default gRPC port, 8502, then the gateway's token
|
||||
must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies.
|
||||
|
||||
~> [Configuration entries](/consul/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.
|
||||
|
||||
<!-- Add a "permalink" anchor here since this title is long and may be edited
|
||||
but we need to deep-link to it elsewhere -->
|
||||
<a name="sds"></a>
|
||||
|
||||
## Custom TLS Certificates via Secret Discovery Service (SDS)
|
||||
|
||||
~> **Advanced Topic:** This topic describes a low-level feature designed for
|
||||
developers building integrations with custom TLS management solutions.
|
||||
|
||||
Consul 1.11 added support for ingress gateways to serve TLS certificates to
|
||||
inbound traffic that are sourced from an external service. The external service
|
||||
must implement Envoy's [gRPC Secret Discovery
|
||||
Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret)
|
||||
(or SDS) API.
|
||||
|
||||
The following procedure describes how to configure an ingress gateway with TLS certificates from an SDS source. The instructions assume that you are familiar with Envoy configuration and the SDS protocol.
|
||||
|
||||
### Configure Static SDS Cluster(s)
|
||||
|
||||
Each Envoy proxy that makes up this Ingress Gateway must define one or more additional [static
|
||||
clusters](/consul/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) when registering. These additional clusters define how Envoy should connect to the required SDS service(s). Defining extra clusters in Envoy's bootstrap configuration requires a manual registration of the Ingress Gateway with Consul proxy.
|
||||
It's not possible to use the `-register` flag with `consul connect envoy -gateway=ingress` to automatically register the proxy in this case.
|
||||
|
||||
The cluster(s) must provide connection information and any necessary
|
||||
authentication information such as mTLS credentials.
|
||||
|
||||
The following example will demonstrate how to use:
|
||||
- A DNS name to discover the SDS service addresses
|
||||
- Local certificate files for TLS client authentication with the SDS server.
|
||||
The certificates are assumed to be created and managed by some other
|
||||
process.
|
||||
|
||||
1. **Register the proxy service.**
|
||||
|
||||
The following Proxy Service Definition defines the additional cluster
|
||||
configuration that will be provided to Envoy when it starts. With this TLS
|
||||
configuration, Envoy will detect changes to the certificate and key files on
|
||||
disk so an external process may maintain and rotate them without needing an
|
||||
Envoy restart.
|
||||
|
||||
```hcl
|
||||
// public-ingress.hcl
|
||||
Services {
|
||||
Name = "public-ingress"
|
||||
Kind = "ingress-gateway"
|
||||
|
||||
Proxy {
|
||||
Config {
|
||||
envoy_extra_static_clusters_json = <<EOF
|
||||
{
|
||||
"name": "sds-cluster",
|
||||
"connect_timeout": "5s",
|
||||
"http2_protocol_options": {},
|
||||
"type": "LOGICAL_DNS",
|
||||
"transport_socket": {
|
||||
"name":"tls",
|
||||
"typed_config": {
|
||||
"@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
|
||||
"common_tls_context":{
|
||||
"tls_certificate_sds_secret_configs": [
|
||||
{
|
||||
"name":"tls_sds",
|
||||
"sds_config":{
|
||||
"path":"/certs/sds-auth-cert.json"
|
||||
}
|
||||
}
|
||||
],
|
||||
"validation_context_sds_secret_config": {
|
||||
"name":"validation_context_sds",
|
||||
"sds_config":{
|
||||
"path":"/certs/sds-validation.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"load_assignment": {
|
||||
"cluster_name": "sds-cluster",
|
||||
"endpoints": [
|
||||
{
|
||||
"lb_endpoints": [
|
||||
{
|
||||
"endpoint": {
|
||||
"address": {
|
||||
"socket_address": {
|
||||
"address": "sds-server.svc.cluster.local",
|
||||
"port_value": 8080,
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
EOF
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. **Issue the following command to create the registration.**
|
||||
|
||||
```
|
||||
consul services register public-ingress.hcl
|
||||
```
|
||||
|
||||
The command must be executed against the Consul agent on the Envoy proxy's node.
|
||||
|
||||
#### Setup TLS Client Authentication for SDS
|
||||
|
||||
Configuration files similar to the following examples must be available on the
|
||||
disk where the Envoy proxy will run. The actual certificates and keys referenced
|
||||
in the configuration files must also be present.
|
||||
|
||||
1. **Configure TLS client authentication for SDS.**
|
||||
|
||||
The certificates and keys must be saved to the same disk where the Envoy
|
||||
proxy will run. The following example files reference the PEM-encoded
|
||||
certificate and key files to be used for TLS Client Authentication with the
|
||||
SDS service (`sds-client-auth.{crt,key}`) and the certificate authority
|
||||
certificate used to validate the SDS server's TLS credentials
|
||||
(`sds-ca.crt`).
|
||||
|
||||
Refer to [Envoy's documentation]
|
||||
(https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap) for
|
||||
more details on this configuration and other possible authentication
|
||||
options.
|
||||
|
||||
```json
|
||||
// /certs/sds-auth-cert.json
|
||||
{
|
||||
"resources": [
|
||||
{
|
||||
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
|
||||
"name": "tls_sds",
|
||||
"tls_certificate": {
|
||||
"certificate_chain": {
|
||||
"filename": "/certs/sds-client-auth.crt"
|
||||
},
|
||||
"private_key": {
|
||||
"filename": "/certs/sds-client-auth.key"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
```json
|
||||
// /certs/sds-validation.json
|
||||
{
|
||||
"resources": [
|
||||
{
|
||||
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
|
||||
"name": "validation_context_sds",
|
||||
"validation_context": {
|
||||
"trusted_ca": {
|
||||
"filename": "/certs/sds-ca.crt"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
1. **Issue the following command to start Envoy.**
|
||||
|
||||
```bash
|
||||
$ consul connect envoy -gateway=ingress -service public-ingress
|
||||
```
|
||||
|
||||
### Configure the Ingress Gateway to Use Certificates from SDS
|
||||
|
||||
SDS certificates may now be configured in the `ingress-gateway` Config Entry.
|
||||
|
||||
The following example shows a single default certificate and key being used for
|
||||
all listeners.
|
||||
|
||||
```hcl
|
||||
// public-ingress-cfg.hcl
|
||||
Kind = "ingress-gateway"
|
||||
Name = "public-ingress"
|
||||
|
||||
TLS {
|
||||
SDS {
|
||||
# This must match the name of the static cluster from step #1
|
||||
ClusterName = "sds-cluster"
|
||||
# This is the name of the certificate resource to load.
|
||||
CertResource = "example.com-public-cert"
|
||||
}
|
||||
}
|
||||
|
||||
Listeners = [
|
||||
{
|
||||
Port = 8443
|
||||
Protocol = "http"
|
||||
Services = ["*"]
|
||||
}
|
||||
]
|
||||
|
||||
```
|
||||
|
||||
1. **Run `consul config write public-ingress-cfg.hcl` to write this configuration.**
|
||||
|
||||
The Envoy instance will now start a listener on port 8443 and attempt to fetch
|
||||
the TLS certificate named from the SDS server.
|
||||
|
||||
Separate certificates may be loaded per listener or per-service with hostname
|
||||
(SNI) switching. See the [Config Entry
|
||||
reference](/consul/docs/connect/config-entries/ingress-gateway) for more details.
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Ingress gateway overview
|
||||
description: >-
|
||||
Ingress gateways enable you to connect external services to services in your mesh. Ingress gateways are a type of proxy that listens for requests from external network locations and route authorized traffic to destinations in the service mesh.
|
||||
---
|
||||
|
||||
# Ingress gateways overview
|
||||
|
||||
An ingress gateway is a type of proxy that enables network connectivity from external services to services inside the mesh. The following diagram describes the ingress gateway workflow:
|
||||
|
||||
|
||||
|
||||
## Workflow
|
||||
|
||||
The following stages describe how to add an ingress gateway to your service mesh:
|
||||
|
||||
1. Configure ingress gateway listeners: Create an ingress gateway configuration entry and specify which services to expose to external requests. The configuration entry allows you to define what services should be exposed, on what port, and by what hostname. You can expose services registered with Consul or expose virtual services defined in other configuration entries. Refer to [Ingress gateway configuration entry reference](/consul/docs/connect/config-entries/ingress-gateway) for details on the configuration parameters you can specify.
|
||||
|
||||
1. Define an ingress gateway proxy service: Ingress gateways are a special-purpose proxy service that you can define and register in a similar manner to other services. When you register the ingress gateway service, Consul applies the configurations defined in the ingress gateway configuration reference. Refer to [Implement an ingress gateway](/consul/docs/connect/gateways/ingress-gateway/usage) for additional information.
|
||||
|
||||
1. Start the network proxy: The ingress gateway proxy service accepts configurations from the configuration entry and directs requests to the exposed services. When the external traffic passes through the ingress gateway, your sidecar proxy handles the inbound and outbound connections between the exposed services and the gateway. Refer to [Service mesh proxy overview](/consul/docs/connect/proxies) to learn more about the proxies Consul supports.
|
||||
|
||||
## Integrations with custom TLS management solutions
|
||||
|
||||
You can configure the ingress gateway to retrieve and serve custom TLS certificates from external systems. This functionality is designed to help you integrate with custom TLS management software. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for additional information.
|
||||
|
|
@ -0,0 +1,246 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Serve custom TLS certificates from an external service
|
||||
description: Learn how to configure ingress gateways to serve TLS certificates from an external service to using secret discovery service. The SDS feature is designed for developers building integrations with custom TLS management solutions.
|
||||
---
|
||||
|
||||
# Serve custom TLS certificates from an external service
|
||||
|
||||
This is an advanced topic that describes how to configure ingress gateways to serve TLS certificates sourced from an external service to inbound traffic using secret discovery service (SDS). SDS is a low-level feature designed for developers building integrations with custom TLS management solutions. For instructions on more common ingress gateway implementations, refer to [Implement an ingress gateway](/consul/docs/connect/gateways/ingress-gateway/usage).
|
||||
|
||||
## Overview
|
||||
|
||||
The following process describes the general procedure for configuring ingress gateways to serve TLS certificates sourced from external services:
|
||||
|
||||
1. Configure static SDS clusters in the ingress gateway service definition.
|
||||
1. Register the service definition.
|
||||
1. Configure TLS client authentication
|
||||
1. Start Envoy.
|
||||
1. Configure SDS settings in an ingress gateway configuration entry.
|
||||
1. Register the ingress gateway configuration entry with Consul.
|
||||
|
||||
## Requirements
|
||||
|
||||
- The external service must implement Envoy's [gRPC secret discovery service (SDS) API](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret).
|
||||
- You should have some familiarity with Envoy configuration and the SDS protocol.
|
||||
- The [`connect.enabled` parameter](/consul/docs/agent/config/config-files#connect) must be set to `true` for all server agents in the Consul datacenter.
|
||||
- The [`ports.grpc` parameter](/consul/docs/agent/config/config-files#connect) must be configured for all server agents in the Consul datacenter.
|
||||
|
||||
### ACL requirements
|
||||
|
||||
If ACLs are enabled, you must present a token when registering ingress gateways that grant the following permissions:
|
||||
|
||||
- `service:write` for the ingress gateway's service name
|
||||
- `service:read` for all services in the ingress gateway's configuration entry
|
||||
- `node:read` for all nodes of the services in the ingress gateway's configuration entry.
|
||||
|
||||
These privileges authorize the token to route communications to other services in the mesh. If the Consul client agent on the gateway's node is not configured to use the default gRPC port, `8502`, then the gateway's token must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies.
|
||||
|
||||
## Configure static SDS clusters
|
||||
|
||||
You must define one or more additional static clusters in the ingress gateway service definition for each Envoy proxy associated with the gateway. The additional clusters define how Envoy should connect to the required SDS services.
|
||||
|
||||
Configure the static clusters in the [`Proxy.Config.envoy_envoy_extra_static_clusters_json`](/consul/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) parameter in the service definition.
|
||||
|
||||
The clusters must provide connection information and any necessary authentication information, such as mTLS credentials.
|
||||
|
||||
You must manually register the ingress gateway with Consul proxy to define extra clusters in Envoy's bootstrap configuration. You can not use the `-register` flag with `consul connect envoy -gateway=ingress` to automatically register the proxy to define static clusters.
|
||||
|
||||
In the following example, the `public-ingress` gateway includes a static cluster named `sds-cluster` that specifies paths to the SDS certificate and SDS certification validation files:
|
||||
|
||||
|
||||
<CodeBlockConfig heading="public-ingress-service.hcl">
|
||||
|
||||
```hcl
|
||||
Services {
|
||||
Name = "public-ingress"
|
||||
Kind = "ingress-gateway"
|
||||
|
||||
Proxy {
|
||||
Config {
|
||||
envoy_extra_static_clusters_json = <<EOF
|
||||
{
|
||||
"name": "sds-cluster",
|
||||
"connect_timeout": "5s",
|
||||
"http2_protocol_options": {},
|
||||
"type": "LOGICAL_DNS",
|
||||
"transport_socket": {
|
||||
"name":"tls",
|
||||
"typed_config": {
|
||||
"@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
|
||||
"common_tls_context":{
|
||||
"tls_certificate_sds_secret_configs": [
|
||||
{
|
||||
"name":"tls_sds",
|
||||
"sds_config":{
|
||||
"path":"/certs/sds-auth-cert.json"
|
||||
}
|
||||
}
|
||||
],
|
||||
"validation_context_sds_secret_config": {
|
||||
"name":"validation_context_sds",
|
||||
"sds_config":{
|
||||
"path":"/certs/sds-validation.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"load_assignment": {
|
||||
"cluster_name": "sds-cluster",
|
||||
"endpoints": [
|
||||
{
|
||||
"lb_endpoints": [
|
||||
{
|
||||
"endpoint": {
|
||||
"address": {
|
||||
"socket_address": {
|
||||
"address": "sds-server.svc.cluster.local",
|
||||
"port_value": 8080,
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
EOF
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-clusters) for details about configuration parameters for SDS clusters.
|
||||
|
||||
## Register the ingress gateway service definition
|
||||
|
||||
Issue the `consul services register` command on the Consul agent on the Envoy proxy's node to register the service. The following example command registers an ingress gateway proxy from a `public-ingress.hcl` file:
|
||||
|
||||
```shell-session
|
||||
$ consul services register public-ingress.hcl
|
||||
```
|
||||
|
||||
Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for additional information about registering services in Consul.
|
||||
|
||||
## Configure TLS client authentication
|
||||
|
||||
Store TLS client authentication files, certificate files, and keys on disk where the Envoy proxy runs and ensure that they are available to Consul. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/bootstrap/bootstrap) for details on configuring authentication files.
|
||||
|
||||
The following example specifies certificate chain:
|
||||
|
||||
|
||||
<CodeBlockConfig heading="certs/sds-auth-cert.json">
|
||||
|
||||
```json
|
||||
{
|
||||
"resources": [
|
||||
{
|
||||
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
|
||||
"name": "tls_sds",
|
||||
"tls_certificate": {
|
||||
"certificate_chain": {
|
||||
"filename": "/certs/sds-client-auth.crt"
|
||||
},
|
||||
"private_key": {
|
||||
"filename": "/certs/sds-client-auth.key"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
The following example specifies the validation context:
|
||||
|
||||
<CodeBlockConfig heading="/certs/sds-validation.json">
|
||||
|
||||
```json
|
||||
{
|
||||
"resources": [
|
||||
{
|
||||
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
|
||||
"name": "validation_context_sds",
|
||||
"validation_context": {
|
||||
"trusted_ca": {
|
||||
"filename": "/certs/sds-ca.crt"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
## Start Envoy
|
||||
|
||||
Issue the `consul connect envoy` command to bootstrap Envoy. The following example starts Envoy and registers it as a service called `public-ingress`:
|
||||
|
||||
```shell-session
|
||||
$ consul connect envoy -gateway=ingress -service public-ingress
|
||||
```
|
||||
|
||||
Refer to [Consul Connect Envoy](/consul/commands/connect/envoy) for additional information about using the `consul connect envoy` command.
|
||||
|
||||
## Define an ingress gateway configuration entry
|
||||
|
||||
Create an ingress gateway configuration entry that enables the gateway to use certificates from SDS. The configuration entry also maps downstream ingress listeners to upstream services. Configure the following fields:
|
||||
|
||||
- [`Kind`](/consul/docs/connect/config-entries/ingress-gateway#kind): Set the value to `ingress-gateway`.
|
||||
- [`Name`](/consul/docs/connect/config-entries/ingress-gateway#name): Consul applies the configuration entry settings to ingress gateway proxies with names that match the `Name` field.
|
||||
- [`TLS`](/consul/docs/connect/config-entries/ingress-gateway#tls): The main `TLS` parameter for the configuration entry holds the SDS configuration. You can also specify TLS configurations per listener and per service.
|
||||
- [`TLS.SDS`](/consul/docs/connect/config-entries/ingress-gateway#tls-sds): The `SDS` map includes the following configuration settings:
|
||||
- [`ClusterName`](/consul/docs/connect/config-entries/ingress-gateway#tls-sds-clustername): Specifies the name of the cluster you specified when [configuring the SDS cluster](#configure-static-SDS-clusters).
|
||||
- [`CertResource`](/consul/docs/connect/config-entries/ingress-gateway#tls-sds-certresource): Specifies the name of the certificate resource to load.
|
||||
- [`Listeners`](/consul/docs/connect/config-entries/ingress-gateway#listeners): Specify one or more listeners.
|
||||
- [`Listeners.Port`](/consul/docs/connect/config-entries/ingress-gateway#listeners-port): Specify a port for the listener. Each listener is uniquely identified by its port number.
|
||||
- [`Listeners.Protocol`](/consul/docs/connect/config-entries/ingress-gateway#listeners-protocol): The default protocol is `tcp`, but you must specify the protocol used by the services you want to allow traffic from.
|
||||
- [`Listeners.Services`](/consul/docs/connect/config-entries/ingress-gateway#listeners-services): The `Services` field contains the services that you want to expose to upstream services. The field contains several options and sub-configurations that enable granular control over ingress traffic, such as health check and TLS configurations.
|
||||
|
||||
For Consul Enterprise service meshes, you may also need to configure the [`Partition`](/consul/docs/connect/config-entries/ingress-gateway#partition) and [`Namespace`](/consul/docs/connect/config-entries/ingress-gateway#namespace) fields for the gateway and for each exposed service.
|
||||
|
||||
Refer to [Ingress gateway configuration entry reference](/consul/docs/connect/config-entries/ingress-gateway) for details about the supported parameters.
|
||||
|
||||
The following example directs Consul to retrieve `example.com-public-cert` certificates from an SDS cluster named `sds-cluster` and serve them to all listeners:
|
||||
|
||||
<CodeBlockConfig heading="public-ingress-cfg.hcl">
|
||||
|
||||
```hcl
|
||||
Kind = "ingress-gateway"
|
||||
Name = "public-ingress"
|
||||
|
||||
TLS {
|
||||
SDS {
|
||||
ClusterName = "sds-cluster"
|
||||
CertResource = "example.com-public-cert"
|
||||
}
|
||||
}
|
||||
|
||||
Listeners = [
|
||||
{
|
||||
Port = 8443
|
||||
Protocol = "http"
|
||||
Services = ["*"]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
## Register the ingress gateway configuration entry
|
||||
|
||||
You can register the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). Refer to [How to Use Configuration Entries](/consul/docs/agent/config-entries) for details about applying configuration entries.
|
||||
|
||||
The following example registers an ingress gateway configuration entry named `public-ingress-cfg.hcl` that is stored on the local system:
|
||||
|
||||
```shell-session
|
||||
$ consul config write public-ingress-cfg.hcl
|
||||
```
|
||||
|
||||
The Envoy instance starts a listener on the port specified in the configuration entry and fetches the TLS certificate named from the SDS server.
|
||||
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Implement an ingress gateway
|
||||
description: Learn how to implement ingress gateways, which are Consul service mesh constructs that listen for requests from external network locations and route authorized traffic to destinations in the service mesh.
|
||||
---
|
||||
|
||||
# Implement an ingress gateway
|
||||
|
||||
This topic describes how to add ingress gateways to your Consul service mesh. Ingress gateways enable connectivity within your organizational network by allowing services outside of the service mesh to send traffic to services in the mesh. Refer to [Ingress gateways overview](/consul/docs/connect/gateways/ingress-gateway/) for additional information about ingress gateways.
|
||||
|
||||
This topic describes ingress gateway usage for virtual machine (VM) environments. Refer to [Configure ingress gateways for Consul on Kubernetes](/consul/docs/k8s/connect/ingress-gateways) for instructions on how to implement ingress gateways in Kubernetes environments.
|
||||
|
||||
## Overview
|
||||
|
||||
Ingress gateways are a type of proxy service included with Consul. Complete the following steps to set up an ingress gateway:
|
||||
|
||||
1. Define listeners and the services they expose. Specify these details in an ingress gateway configuration entry.
|
||||
1. Register an ingress gateway service. Define the services in a service definition file.
|
||||
1. Start the ingress gateway. This step deploys the Envoy proxy that functions as the ingress gateway.
|
||||
|
||||
After specifying listeners and services in the ingress gateway configuration entry, you can register the gateway service and start Envoy with a single CLI command instead of completing these steps separately. Refer [Register an ingress service on Envoy startup](#register-an-ingress-service-on-envoy-startup).
|
||||
|
||||
## Requirements
|
||||
|
||||
- Service mesh must be enabled for all agents. Set the [`connect.enabled` parameter](/consul/docs/agent/config/config-files#connect) to `true` to enable service mesh.
|
||||
- The gRPC port must be configured for all server agents in the datacenter. Specify the gRPC port in the [`ports.grpc` parameter](/consul/docs/agent/config/config-files#grpc_port). We recommend setting the port to `8502` to simplify configuration when ACLs are enabled. Refer to [ACL requirements](#acl-requirements) for additional information.
|
||||
- You must use Envoy for sidecar proxies in your service mesh. Refer to [Envoy Proxy Configuration for Service Mesh](/consul/docs/connect/proxies/envoy) for supported versions.
|
||||
|
||||
### ACL requirements
|
||||
|
||||
If ACLs are enabled, you must present a token when registering ingress gateways that grant the following permissions:
|
||||
|
||||
`service:write` for the ingress gateway's service name
|
||||
`service:read` for all services in the ingress gateway's configuration entry
|
||||
`node:read` for all nodes of the services in the ingress gateway's configuration entry.
|
||||
|
||||
These privileges authorize the token to route communications to other services in the mesh. If the Consul client agent on the gateway's node is not configured to use the default `8502` gRPC port, then the gateway's token must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies.
|
||||
|
||||
## Expose services
|
||||
|
||||
Define and apply an ingress gateway configuration entry to specify which services in the mesh to expose to external services.
|
||||
|
||||
### Define an ingress gateway configuration entry
|
||||
|
||||
Ingress gateway configuration entries map downstream ingress listeners to upstream services. When you register an ingress gateway proxy that matches the configuration entry name, Consul applies the settings specified in the configuration entry. Configure the following fields:
|
||||
|
||||
- [`Kind`](/consul/docs/connect/config-entries/ingress-gateway#kind): Set the value to `ingress-gateway`.
|
||||
- [`Name`](/consul/docs/connect/config-entries/ingress-gateway#name): Consul applies the configuration entry settings to ingress gateway proxies with names that match the `Name` field.
|
||||
- [`Listeners`](/consul/docs/connect/config-entries/ingress-gateway#listeners): Specify one or more listeners.
|
||||
- [`Listeners.Port`](/consul/docs/connect/config-entries/ingress-gateway#listeners-port): Specify a port for the listener. Each listener is uniquely identified by its port number.
|
||||
- [`Listeners.Protocol`](/consul/docs/connect/config-entries/ingress-gateway#listeners-protocol): The default protocol is `tcp`, but you must specify the protocol used by the services you want to allow traffic from.
|
||||
- [`Listeners.Services`](/consul/docs/connect/config-entries/ingress-gateway#listeners-services): The `Services` field contains the services that you want to expose to upstream services. The field contains several options and sub-configurations that enable granular control over ingress traffic, such as health check and TLS configurations.
|
||||
|
||||
For Consul Enterprise service meshes, you may also need to configure the [`Partition`](/consul/docs/connect/config-entries/ingress-gateway#partition) and [`Namespace`](/consul/docs/connect/config-entries/ingress-gateway#namespace) fields for the gateway and for each exposed service.
|
||||
|
||||
Refer to [Ingress gateway configuration entry reference](/consul/docs/connect/config-entries/ingress-gateway) for details about the supported parameters.
|
||||
|
||||
### Register an ingress gateway configuration entry
|
||||
|
||||
You can register the configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). Refer to [How to Use Configuration Entries](/consul/docs/agent/config-entries) for details about applying configuration entries.
|
||||
|
||||
The following example registers an ingress gateway configuration entry named `public-ingress.hcl` that is stored on the local system:
|
||||
|
||||
```shell-session
|
||||
$ consul config write public-ingress.hcl
|
||||
```
|
||||
|
||||
## Deploy an ingress gateway service
|
||||
|
||||
To deploy an ingress gateway service, create a service definition and register it with Consul.
|
||||
|
||||
You can also define an ingress gateway service and register it with Consul while starting an Envoy proxy from the command line. Refer to [Register an ingress service on Envoy startup](#register-an-ingress-service-on-envoy-startup) for details.
|
||||
|
||||
### Create a service definition for the ingress gateway
|
||||
|
||||
Consul applies the settings defined in the ingress gateway configuration entry to ingress gateway services that match the configuration entry name. Refer to [Define services](/consul/docs/services/usage/define-services) for additional information about defining services in Consul.
|
||||
|
||||
The following fields are required for the ingress gateway service definition:
|
||||
|
||||
- [`Kind`](/consul/docs/services/configuration/services-configuration-reference#kind): The field must be set to `ingress-gateway`.
|
||||
- [`Name`](/consul/docs/services/configuration/services-configuration-reference#name): The name should match the value specified for the `Name` field in the configuration entry.
|
||||
|
||||
All other service definition fields are optional, but we recommend defining health checks to verify the health of the gateway. Refer to [Services configuration reference](/consul/docs/services/configuration/services-configuration-reference) for information about defining services.
|
||||
|
||||
### Register the ingress gateway proxy service
|
||||
|
||||
You can register the ingress gateway using API or CLI. Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions on registering services in Consul.
|
||||
|
||||
The following example registers an ingress gateway defined in `ingress-gateway.hcl` from the Consul CLI:
|
||||
|
||||
```shell-session
|
||||
$ consul services register ingress-service.hcl
|
||||
```
|
||||
|
||||
## Start an Envoy proxy
|
||||
|
||||
Run the `consul connect envoy` command to start Envoy. Specify the name of the ingress gateway service and include the `-gateway=ingress` flag. Refer to [Consul Connect Envoy](/consul/commands/connect/envoy) for details about using the command.
|
||||
|
||||
The following example starts Envoy for the `ingress-service` gateway service:
|
||||
|
||||
```shell-session
|
||||
$ consul connect envoy -gateway=ingress ingress-service
|
||||
```
|
||||
|
||||
### Register an ingress service on Envoy startup
|
||||
|
||||
You can also automatically register the ingress gateway service when starting the Envoy proxy. Specify the following flags with the `consul connect envoy` command:
|
||||
|
||||
- `-gateway=ingress`
|
||||
- `-register`
|
||||
- `-service=<name of the service>`
|
||||
|
||||
The following example starts Envoy and registers an ingress gateway service named `ingress-service` bound to the agent address at port `8888`:
|
||||
|
||||
```shell-session
|
||||
$ consul connect envoy -gateway=ingress -register \
|
||||
-service ingress-service \
|
||||
-address '{{ GetInterfaceIP "eth0" }}:8888'
|
||||
```
|
||||
You cannot register the ingress gateway service and start the proxy at the same time if you configure the gateway to retrieve and serve TLS certificates from their external downstreams. Refer to [Serve custom TLS certificates from an external service](/consul/docs/connect/gateways/ingress-gateway/tls-external-service) for more information.
|
||||
|
||||
## Additional Envoy configurations
|
||||
|
||||
Ingress gateways support additional Envoy gateway options and escape-hatch overrides. Specify gateway options in the ingress gateway service definition to use them. To use escape-hatch overrides, you must add them to your global proxy defaults configuration entry. Refer to the following documentation for additional information:
|
||||
|
||||
- [Gateway options](/consul/docs/connect/proxies/envoy#gateway-options)
|
||||
- [Escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides)
|
||||
|
|
@ -674,7 +674,24 @@
|
|||
},
|
||||
{
|
||||
"title": "Ingress Gateways",
|
||||
"path": "connect/gateways/ingress-gateway"
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "connect/gateways/ingress-gateway"
|
||||
},
|
||||
{
|
||||
"title": "Implement an ingress gateway",
|
||||
"path": "connect/gateways/ingress-gateway/usage"
|
||||
},
|
||||
{
|
||||
"title": "Serve TLS certificates from an external service",
|
||||
"path": "connect/gateways/ingress-gateway/tls-external-service"
|
||||
},
|
||||
{
|
||||
"title": "Configuration",
|
||||
"href": "/consul/docs/connect/config-entries/ingress-gateway"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Terminating Gateways",
|
||||
|
|
|
|||
Loading…
Reference in New Issue