mirror of https://github.com/hashicorp/consul
1226 lines
35 KiB
Markdown
1226 lines
35 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: 'Configuration Entry Kind: 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
|
|
|
|
This topic provides reference information for the `ingress-gateway` configuration entry.
|
|
|
|
## Introduction
|
|
|
|
You can define an `ingress-gateway` configuration entry to connect the Consul service mesh to a set of external services. The specification for ingress gateways include a `listeners` configuration, which exposes the service mesh to the external services. Use camel case (`IngressGateway`) to declare an ingress gateway configuration entry on Kubernetes.
|
|
|
|
Refer to the [Kubernetes Ingress Gateway](/docs/k8s/connect/ingress-gateways) documentation for information about configuring ingress gateways on Kubernetes.
|
|
|
|
For other platforms, see [Ingress Gateway](/docs/connect/ingress-gateway).
|
|
|
|
## Requirements
|
|
|
|
- Consul versions 1.8.4+ is required to use the `IngressGateway` custom resource on Kubernetes.
|
|
- Consul versions 1.8.0+ is required to use the `ingress-gateway` custom resource on all other platforms.
|
|
|
|
## Usage
|
|
|
|
1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements).
|
|
1. Create a file containing the configuration entry settings (see [Configuration](#configuration)).
|
|
1. Apply the configuration settings using one of the following methods:
|
|
- Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details.
|
|
- Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details.
|
|
|
|
## Configuration
|
|
|
|
Use the following syntax to configure an ingress gateway.
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "<name for the gateway>"
|
|
|
|
Listeners = [
|
|
{
|
|
Port = <external service port>
|
|
Protocol = "<protocol used by external service>"
|
|
Services = [
|
|
{
|
|
Name = "<name of external service>"
|
|
}
|
|
]
|
|
|
|
}
|
|
]
|
|
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: <name for the gateway>
|
|
spec:
|
|
listeners:
|
|
- port: <external service port>
|
|
protocol: <protocol used by external service>
|
|
services:
|
|
- name: <name of external service>
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "<name for the gateway>",
|
|
"Listeners": [
|
|
{
|
|
"Port": <external service port>,
|
|
"Protocol": "<protocol used by external service>",
|
|
"Services": [
|
|
{
|
|
"Name": "<name of external service>"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
|
|
```
|
|
|
|
</CodeTabs>
|
|
</Tab>
|
|
|
|
<Tab heading="Consul Enterprise">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "<name for the gateway>"
|
|
Namespace = "<namespace containing the gateway>"
|
|
Partition = "<partition containing the gateway namespace>"
|
|
|
|
Listeners = [
|
|
{
|
|
Port = <external service port>
|
|
Protocol = "<protocol used by external service>"
|
|
Services = [
|
|
{
|
|
Name = "<name of external service>"
|
|
}
|
|
]
|
|
|
|
}
|
|
]
|
|
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: <name for the gateway>
|
|
namespace: <namespace containing the gateway>
|
|
partition: <partition containing the gateway namespace>
|
|
|
|
spec:
|
|
listeners:
|
|
- port: <external service port>
|
|
protocol: <protocol used by external service>
|
|
services:
|
|
- name: <name of external service>
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "<name for the gateway>",
|
|
"Namespace": "<namespace containing the gateway>",
|
|
"Partition": "<partition containing the gateway namespace>",
|
|
|
|
"Listeners": [
|
|
{
|
|
"Port": <external service port>,
|
|
"Protocol": "<protocol used by external service>",
|
|
"Services": [
|
|
{
|
|
"Name": "<name of external service>"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Refer to the [Available Fields](#available-fields) section for complete information about all ingress gateway configuration entry options and to the [Example Configurations](#example-configurations) section for example use-cases.
|
|
|
|
### Scope
|
|
|
|
[Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies across the default partition of 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 or partitions. 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/connect/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>.ingress.*`, or if using namespaces,
|
|
`<service-name>.ingress.<namespace>.*`. This matches the [Consul DNS
|
|
ingress subdomain](/docs/discovery/dns#ingress-service-lookups).
|
|
|
|
A wildcard specifier cannot be set on a listener of protocol `tcp`.
|
|
|
|
### ACLs
|
|
|
|
Configuration entries may be protected by [ACLs](/docs/security/acl).
|
|
|
|
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`.
|
|
|
|
### Example Configurations
|
|
|
|
The following examples describe possible use-cases for ingress gateway configuration entries.
|
|
|
|
#### TCP listener
|
|
|
|
The following example sets up a TCP listener on an ingress gateway named `us-east-ingress` to proxy traffic to the `db` service. The Consul Enterprise version also posits the gateway listener inside the `default` [namespace](/docs/enterprise/namespaces) and the `team-frontend` [admin partition](/docs/enterprise/admin-partitions):
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "us-east-ingress"
|
|
|
|
Listeners = [
|
|
{
|
|
Port = 3456
|
|
Protocol = "tcp"
|
|
Services = [
|
|
{
|
|
Name = "db"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: us-east-ingress
|
|
spec:
|
|
listeners:
|
|
- port: 3456
|
|
protocol: tcp
|
|
services:
|
|
- name: db
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "us-east-ingress",
|
|
"Listeners": [
|
|
{
|
|
"Port": 3456,
|
|
"Protocol": "tcp",
|
|
"Services": [
|
|
{
|
|
"Name": "db"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "us-east-ingress"
|
|
Namespace = "default"
|
|
Partition = "team-frontend"
|
|
|
|
Listeners = [
|
|
{
|
|
Port = 3456
|
|
Protocol = "tcp"
|
|
Services = [
|
|
{
|
|
Namespace = "ops"
|
|
Name = "db"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: us-east-ingress
|
|
namespace: default
|
|
spec:
|
|
listeners:
|
|
- port: 3456
|
|
protocol: tcp
|
|
services:
|
|
- name: db
|
|
namespace: ops
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "us-east-ingress",
|
|
"Namespace": "default",
|
|
"Partition": "team-frontend",
|
|
"Listeners": [
|
|
{
|
|
"Port": 3456,
|
|
"Protocol": "tcp",
|
|
"Services": [
|
|
{
|
|
"Namespace": "ops",
|
|
"Name": "db"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
#### Wildcard HTTP Listener
|
|
|
|
In the following example, two listeners are configured on an ingress gateway named `us-east-ingress`:
|
|
|
|
- The first listener is configured to listen on port `8080` and uses a wildcard (`*`) to proxy traffic to all services in the datacenter.
|
|
- The second listener exposes the `api` and `web` services on port `4567` at user-provided hosts.
|
|
- TLS is enabled on every listener.
|
|
|
|
The Consul Enterprise version implements the following additional configurations:
|
|
|
|
- The ingress gateway is set up in the `default` [namespace](/docs/enterprise/namespaces) and proxies traffic to all services in the `frontend` namespace.
|
|
- The `api` and `web` services are proxied to team-specific [admin partitions](/docs/enterprise/admin-partitions):
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "us-east-ingress"
|
|
|
|
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"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: us-east-ingress
|
|
spec:
|
|
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']
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "us-east-ingress",
|
|
"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"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "us-east-ingress"
|
|
Namespace = "default"
|
|
|
|
TLS {
|
|
Enabled = true
|
|
}
|
|
|
|
Listeners = [
|
|
{
|
|
Port = 8080
|
|
Protocol = "http"
|
|
Services = [
|
|
{
|
|
Namespace = "frontend"
|
|
Name = "*"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
Port = 4567
|
|
Protocol = "http"
|
|
Services = [
|
|
{
|
|
Namespace = "frontend"
|
|
Name = "api"
|
|
Hosts = ["foo.example.com"]
|
|
Partition = "api-team"
|
|
},
|
|
{
|
|
Namespace = "frontend"
|
|
Name = "web"
|
|
Hosts = ["website.example.com"]
|
|
Partition = "web-team"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: us-east-ingress
|
|
namespace: default
|
|
spec:
|
|
tls:
|
|
enabled: true
|
|
listeners:
|
|
- port: 8080
|
|
protocol: http
|
|
services:
|
|
- name: '*'
|
|
namespace: frontend
|
|
- port: 4567
|
|
protocol: http
|
|
services:
|
|
- name: api
|
|
namespace: frontend
|
|
hosts: ['foo.example.com']
|
|
partition: api-team
|
|
- name: web
|
|
namespace: frontend
|
|
hosts: ['website.example.com']
|
|
partition: web-team
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "us-east-ingress",
|
|
"Namespace": "default",
|
|
"TLS": {
|
|
"Enabled": true
|
|
},
|
|
"Listeners": [
|
|
{
|
|
"Port": 8080,
|
|
"Protocol": "http",
|
|
"Services": [
|
|
{
|
|
"Namespace": "frontend",
|
|
"Name": "*"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"Port": 4567,
|
|
"Protocol": "http",
|
|
"Services": [
|
|
{
|
|
"Namespace": "frontend",
|
|
"Name": "api",
|
|
"Hosts": ["foo.example.com"],
|
|
"Partition": "api-team"
|
|
},
|
|
{
|
|
"Namespace": "frontend",
|
|
"Name": "web",
|
|
"Hosts": ["website.example.com"],
|
|
"Partition": "web-team"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
#### HTTP listener with Path-based Routing
|
|
|
|
The following example sets up an HTTP listener on an ingress gateway named `us-east-ingress` to proxy
|
|
traffic to a virtual service named `api`. In the Consul Enterprise version, `us-east-ingress` is set up in the `default` namespace and `default` partition.
|
|
|
|
In this use-case, internal-only debug headers should be stripped before responding to external clients.
|
|
Requests to internal services should also be labelled to indicate which gateway they came through.
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "us-east-ingress"
|
|
|
|
Listeners = [
|
|
{
|
|
Port = 80
|
|
Protocol = "http"
|
|
Services = [
|
|
{
|
|
Name = "api"
|
|
RequestHeaders {
|
|
Add {
|
|
"x-gateway" = "us-east-ingress"
|
|
}
|
|
}
|
|
ResponseHeaders {
|
|
Remove = ["x-debug"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: us-east-ingress
|
|
spec:
|
|
listeners:
|
|
- port: 80
|
|
protocol: http
|
|
services:
|
|
- name: api
|
|
# HTTP Header manipulation is not supported in Kubernetes CRD
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "us-east-ingress",
|
|
"Listeners": [
|
|
{
|
|
"Port": 80,
|
|
"Protocol": "http",
|
|
"Services": [
|
|
{
|
|
"Name": "api",
|
|
"RequestHeaders": {
|
|
"Add": {
|
|
"x-gateway": "us-east-ingress"
|
|
}
|
|
},
|
|
"ResponseHeaders": {
|
|
"Remove": ["x-debug"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "us-east-ingress"
|
|
Namespace = "default"
|
|
Partition = "default"
|
|
|
|
Listeners = [
|
|
{
|
|
Port = 80
|
|
Protocol = "http"
|
|
Services = [
|
|
{
|
|
Name = "api"
|
|
Namespace = "frontend"
|
|
RequestHeaders {
|
|
Add {
|
|
"x-gateway" = "us-east-ingress"
|
|
}
|
|
}
|
|
ResponseHeaders {
|
|
Remove = ["x-debug"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: IngressGateway
|
|
metadata:
|
|
name: us-east-ingress
|
|
namespace: default
|
|
spec:
|
|
listeners:
|
|
- port: 80
|
|
protocol: http
|
|
services:
|
|
- name: api
|
|
namespace: frontend
|
|
# HTTP Header manipulation is not supported in Kubernetes CRD
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "ingress-gateway",
|
|
"Name": "us-east-ingress",
|
|
"Namespace": "default",
|
|
"Partition": "default",
|
|
"Listeners": [
|
|
{
|
|
"Port": 80,
|
|
"Protocol": "http",
|
|
"Services": [
|
|
{
|
|
"Name": "api",
|
|
"Namespace": "frontend",
|
|
"RequestHeaders": {
|
|
"Add": {
|
|
"x-gateway": "us-east-ingress"
|
|
}
|
|
},
|
|
"ResponseHeaders": {
|
|
"Remove": ["x-debug"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
For this use-case, the `api` service is not an actual registered service. It exists as a virtual service for L7 configuration only. A `service-router` (`ServiceRouter` on Kubernetes) is defined for the virtual service that uses path-based routing to route requests to different backend services:
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "service-router"
|
|
Name = "api"
|
|
Routes = [
|
|
{
|
|
Match {
|
|
HTTP {
|
|
PathPrefix = "/billing"
|
|
}
|
|
}
|
|
|
|
Destination {
|
|
Service = "billing-api"
|
|
}
|
|
},
|
|
{
|
|
Match {
|
|
HTTP {
|
|
PathPrefix = "/payments"
|
|
}
|
|
}
|
|
|
|
Destination {
|
|
Service = "payments-api"
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: ServiceRouter
|
|
metadata:
|
|
name: api
|
|
spec:
|
|
routes:
|
|
- match:
|
|
http:
|
|
pathPrefix: '/billing'
|
|
destination:
|
|
service: billing-api
|
|
- match:
|
|
http:
|
|
pathPrefix: '/payments'
|
|
destination:
|
|
service: payments-api
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "service-router",
|
|
"Name": "api",
|
|
"Routes": [
|
|
{
|
|
"Match": {
|
|
"HTTP": {
|
|
"PathPrefix": "/billing"
|
|
}
|
|
},
|
|
"Destination": {
|
|
"Service": "billing-api"
|
|
}
|
|
},
|
|
{
|
|
"Match": {
|
|
"HTTP": {
|
|
"PathPrefix": "/payments"
|
|
}
|
|
},
|
|
"Destination": {
|
|
"Service": "payments-api"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "service-router"
|
|
Name = "api"
|
|
Namespace = "default"
|
|
Partition = "default"
|
|
Routes = [
|
|
{
|
|
Match {
|
|
HTTP {
|
|
PathPrefix = "/billing"
|
|
}
|
|
}
|
|
|
|
Destination {
|
|
Service = "billing-api"
|
|
Namespace = "frontend"
|
|
}
|
|
},
|
|
{
|
|
Match {
|
|
HTTP {
|
|
PathPrefix = "/payments"
|
|
}
|
|
}
|
|
|
|
Destination {
|
|
Service = "payments-api"
|
|
Namespace = "frontend"
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: ServiceRouter
|
|
metadata:
|
|
name: api
|
|
namespace: default
|
|
spec:
|
|
routes:
|
|
- match:
|
|
http:
|
|
pathPrefix: '/billing'
|
|
destination:
|
|
service: billing-api
|
|
namespace: frontend
|
|
- match:
|
|
http:
|
|
pathPrefix: '/payments'
|
|
destination:
|
|
service: payments-api
|
|
namespace: frontend
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "service-router",
|
|
"Name": "api",
|
|
"Namespace": "default",
|
|
"Partition": "default",
|
|
"Routes": [
|
|
{
|
|
"Match": {
|
|
"HTTP": {
|
|
"PathPrefix": "/billing"
|
|
}
|
|
},
|
|
"Destination": {
|
|
"Service": "billing-api",
|
|
"Namespace": "frontend"
|
|
}
|
|
},
|
|
{
|
|
"Match": {
|
|
"HTTP": {
|
|
"PathPrefix": "/payments"
|
|
}
|
|
},
|
|
"Destination": {
|
|
"Service": "payments-api",
|
|
"Namespace": "frontend"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Available Fields
|
|
|
|
You can specify the following parameters to configure ingress gateway configuration entries.
|
|
|
|
<ConfigEntryReference
|
|
keys={[
|
|
{
|
|
name: 'apiVersion',
|
|
description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
|
|
hcl: false,
|
|
},
|
|
{
|
|
name: 'Kind',
|
|
description: {
|
|
hcl: 'Must be set to `ingress-gateway`',
|
|
yaml: 'Must be set to `IngressGateway`',
|
|
},
|
|
},
|
|
{
|
|
name: 'Name',
|
|
description: 'Set to the name of the gateway being configured.',
|
|
type: 'string: <required>',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'Namespace',
|
|
type: 'string: `default`',
|
|
enterprise: true,
|
|
description:
|
|
'Specifies the namespace in which the configuration entry will apply. The value must match the namespace in which the gateway is registered.' +
|
|
' If omitted, the namespace will be inherited from the `ns` request parameter (refer to the [`config` API endpoint documentation](/api/config#ns)).' +
|
|
' or will default to the `default` namespace.',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'Meta',
|
|
type: 'map<string|string>: nil',
|
|
description:
|
|
'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'Partition',
|
|
type: `string: "default"`,
|
|
enterprise: true,
|
|
description:
|
|
'Specifies the admin partition in which the configuration will apply. The value must match the partition in which the gateway is registered.' +
|
|
' If omitted, the partition will be inherited from the request (refer to the [`config` API endpoint documentation](/api/config)).' +
|
|
' See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information.',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'metadata',
|
|
children: [
|
|
{
|
|
name: 'name',
|
|
description: 'Set to the name of the service being configured.',
|
|
},
|
|
{
|
|
name: 'namespace',
|
|
enterprise: true,
|
|
description:
|
|
'Refer to the [Kubernetes Namespaces documentation for Consul Enterprise](/docs/k8s/crds#consul-enterprise). The `namespace` parameter is not supported in Consul OSS (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)).',
|
|
},
|
|
],
|
|
hcl: false,
|
|
},
|
|
{
|
|
name: 'TLS',
|
|
type: 'TLSConfig: <optional>',
|
|
description: 'TLS configuration for this gateway.',
|
|
children: [
|
|
{
|
|
name: 'Enabled',
|
|
type: 'bool: false',
|
|
description: {
|
|
hcl:
|
|
"Set this configuration to `true` to enable built-in TLS for every listener on the gateway.<br><br>If TLS is enabled, then each host defined in each service's `Hosts` fields will be added as a DNSSAN to the gateway's x509 certificate.",
|
|
yaml:
|
|
"Set this configuration to `true` to enable built-in TLS for every listener on the gateway.<br><br>If TLS is enabled, then each host defined in each service's `hosts` fields will be added as a DNSSAN to the gateway's x509 certificate.",
|
|
},
|
|
},
|
|
{
|
|
name: 'TLSMinVersion',
|
|
type: 'string: ""',
|
|
description: "Set the default minimum TLS version supported for the gateway's listeners. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy v1.22.0 and newer [will default to TLS 1.2 as a min version](https://github.com/envoyproxy/envoy/pull/19330), while older releases of Envoy default to TLS 1.0.",
|
|
},
|
|
{
|
|
name: 'TLSMaxVersion',
|
|
type: 'string: ""',
|
|
description: {
|
|
hcl:
|
|
"Set the default maximum TLS version supported for the gateway's listeners. Must be greater than or equal to `TLSMinVersion`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
|
|
yaml:
|
|
"Set the default maximum TLS version supported for the gateway's listeners. Must be greater than or equal to `tls_min_version`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
|
|
},
|
|
},
|
|
{
|
|
name: 'CipherSuites',
|
|
type: 'array<string>: <optional>',
|
|
description: `Set the default list of TLS cipher suites for the gateway's
|
|
listeners to support when negotiating connections using
|
|
TLS 1.2 or earlier. If unspecified, Envoy will use a
|
|
[default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites).
|
|
The list of supported cipher suites can seen in
|
|
[\`consul/types/tls.go\`](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169)
|
|
and is dependent on underlying support in Envoy. Future
|
|
releases of Envoy may remove currently-supported but
|
|
insecure cipher suites, and future releases of Consul
|
|
may add new supported cipher suites if any are added to
|
|
Envoy.`
|
|
},
|
|
{
|
|
name: 'SDS',
|
|
yaml: false,
|
|
type: 'SDSConfig: <optional>',
|
|
description:
|
|
'Defines a set of parameters that configures the gateway to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ingress-gateway#sds) for more details on usage.<br><br>SDS properties defined in this field are used as defaults for all listeners on the gateway.',
|
|
children: [
|
|
{
|
|
name: 'ClusterName',
|
|
type: 'string',
|
|
description:
|
|
"Specifies the name of the SDS cluster from which Consul should retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
|
|
},
|
|
{
|
|
name: 'CertResource',
|
|
type: 'string',
|
|
description:
|
|
'Specifies an SDS resource name. Consul will request the SDS resource name when fetching the certificate from the SDS service. Setting this causes all listeners to be served exclusively over TLS with this certificate unless overridden by listener-specific TLS configuration.',
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'Listeners',
|
|
type: 'array<IngressListener>: <optional>)',
|
|
description:
|
|
'A list of listeners that the ingress gateway should setup, uniquely identified by their port number.',
|
|
children: [
|
|
{
|
|
name: 'Port',
|
|
type: 'int: 0',
|
|
description: `The port on which the ingress listener should receive
|
|
traffic. The port will be bound to the IP address that
|
|
was specified in the [\`-address\`](/commands/connect/envoy#address)
|
|
flag when starting the gateway.
|
|
<b>Note:</b> The ingress listener port must not conflict
|
|
with the health check port specified in the \`-address\`
|
|
flag.`,
|
|
},
|
|
{
|
|
name: 'Protocol',
|
|
type: 'string: "tcp"',
|
|
description:
|
|
'The protocol associated with the listener. One of `tcp`, `http`, `http2`, or `grpc`.',
|
|
},
|
|
{
|
|
name: 'Services',
|
|
type: 'array<IngressService>: <optional>',
|
|
description: `A list of services to be exposed via this listener.
|
|
For \`tcp\` listeners, only a single service is allowed.
|
|
Each service must have a unique name. A namespace is also required for
|
|
Consul Enterprise.`,
|
|
children: [
|
|
{
|
|
name: 'Name',
|
|
type: 'string: ""',
|
|
description: `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). If the wildcard specifier,
|
|
\`*\`, is provided, then ALL services will be exposed through the listener.
|
|
This is not supported for listeners with protocol \`tcp\`.`,
|
|
},
|
|
{
|
|
name: 'Namespace',
|
|
type: 'string: ""',
|
|
enterprise: true,
|
|
description:
|
|
'The namespace from which to resolve the service if different than the existing namespace. The current namespace is used if unspecified.',
|
|
},
|
|
{
|
|
name: 'Partition',
|
|
type: 'string: ""',
|
|
enterprise: true,
|
|
description:
|
|
'The admin partition from which to resolve the service if different than the existing partition. The current partition is used if unspecified.',
|
|
},
|
|
{
|
|
name: 'Hosts',
|
|
type: 'array<string>: <optional>',
|
|
description: `A list of hosts that specify what
|
|
requests will match this service. This cannot be used with a \`tcp\`
|
|
listener, and cannot be specified alongside a \`*\` service name. If not
|
|
specified, the default domain \`\<service-name>.ingress.*\` will be used to
|
|
match services. Requests <b>must</b> send the correct host to be routed to
|
|
the defined service.<br><br>
|
|
The wildcard specifier, \`*\`, can be used by itself to match all traffic
|
|
coming to the ingress gateway, if TLS is not enabled. This allows a user
|
|
to route all traffic to a single service without specifying a host,
|
|
allowing simpler tests and demos. Otherwise, the wildcard specifier can
|
|
be used as part of the host to match multiple hosts, but only in the
|
|
leftmost DNS label. This ensures that all defined hosts are valid DNS
|
|
records. For example, \`*.example.com\` is valid, while \`example.*\` and
|
|
\`*-suffix.example.com\` are not.`,
|
|
},
|
|
{
|
|
yaml: false,
|
|
name: 'RequestHeaders',
|
|
type: 'HTTPHeaderModifiers: <optional>',
|
|
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
|
|
that will be applied to requests routed to this service.
|
|
This cannot be used with a \`tcp\` listener.`,
|
|
},
|
|
{
|
|
yaml: false,
|
|
name: 'ResponseHeaders',
|
|
type: 'HTTPHeaderModifiers: <optional>',
|
|
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
|
|
that will be applied to responses from this service.
|
|
This cannot be used with a \`tcp\` listener.`,
|
|
},
|
|
{
|
|
name: 'TLS',
|
|
yaml: false,
|
|
type: 'ServiceTLSConfig: <optional>',
|
|
description: 'TLS configuration for this service.',
|
|
children: [
|
|
{
|
|
name: 'SDS',
|
|
type: 'SDSConfig: <optional>',
|
|
description: `Defines a set of parameters that configures the SDS source for the certificate for this specific service.
|
|
At least one custom host must be specified in \`Hosts\`.
|
|
The certificate retrieved from SDS will be served for all requests identifying one of the
|
|
\`Hosts\` values in the TLS Server Name Indication (SNI) header.`,
|
|
children: [
|
|
{
|
|
name: 'ClusterName',
|
|
type: 'string',
|
|
description:
|
|
"The SDS cluster name to connect to to retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
|
|
},
|
|
{
|
|
name: 'CertResource',
|
|
type: 'string',
|
|
description:
|
|
'The SDS resource name to request when fetching the certificate from the SDS service.',
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'TLS',
|
|
yaml: false,
|
|
type: 'TLSConfig: <optional>',
|
|
description: 'TLS configuration for this listener.',
|
|
children: [
|
|
{
|
|
name: 'Enabled',
|
|
type: 'bool: false',
|
|
description: {
|
|
hcl:
|
|
"Set this configuration to `true` to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in each service's `Hosts` field will be added as a DNSSAN to the gateway's x509 certificate. Note that even hosts from other listeners with TLS disabled will be added. TLS can not be disabled for individual listeners if it is enabled on the gateway.",
|
|
yaml:
|
|
"Set this configuration to `true` to enable built-in TLS for this listener.<br><br>If TLS is enabled, then each host defined in the `hosts` field will be added as a DNSSAN to the gateway's x509 certificate. Note that even hosts from other listeners with TLS disabled will be added. TLS can not be disabled for individual listeners if it is enabled on the gateway.",
|
|
},
|
|
},
|
|
{
|
|
name: 'TLSMinVersion',
|
|
type: 'string: ""',
|
|
description: "Set the minimum TLS version supported for this listener. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy v1.22.0 and newer [will default to TLS 1.2 as a min version](https://github.com/envoyproxy/envoy/pull/19330), while older releases of Envoy default to TLS 1.0.",
|
|
},
|
|
{
|
|
name: 'TLSMaxVersion',
|
|
type: 'string: ""',
|
|
description: {
|
|
hcl:
|
|
"Set the maximum TLS version supported for this listener. Must be greater than or equal to `TLSMinVersion`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
|
|
yaml:
|
|
"Set the maximum TLS version supported for this listener. Must be greater than or equal to `tls_min_version`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`." ,
|
|
},
|
|
},
|
|
{
|
|
name: 'CipherSuites',
|
|
type: 'array<string>: <optional>',
|
|
description: `Set the list of TLS cipher suites to support when negotiating
|
|
connections using TLS 1.2 or earlier. If unspecified,
|
|
Envoy will use a
|
|
[default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites).
|
|
The list of supported cipher suites can seen in
|
|
[\`consul/types/tls.go\`](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169)
|
|
and is dependent on underlying support in Envoy. Future
|
|
releases of Envoy may remove currently-supported but
|
|
insecure cipher suites, and future releases of Consul
|
|
may add new supported cipher suites if any are added to Envoy.`
|
|
},
|
|
{
|
|
name: 'SDS',
|
|
type: 'SDSConfig: <optional>',
|
|
description:
|
|
'Defines a set of parameters that configures the listener to load TLS certificates from an external SDS service. See [SDS](/docs/connect/gateways/ingress-gateway#sds) for more details on usage.<br><br>SDS properties set here will be used as defaults for all services on this listener.',
|
|
children: [
|
|
{
|
|
name: 'ClusterName',
|
|
type: 'string',
|
|
description:
|
|
"The SDS cluster name to connect to to retrieve certificates. This cluster must be [specified in the Gateway's bootstrap configuration](/docs/connect/gateways/ingress-gateway#sds).",
|
|
},
|
|
{
|
|
name: 'CertResource',
|
|
type: 'string',
|
|
description:
|
|
'The SDS resource name to request when fetching the certificate from the SDS service.',
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
]}
|
|
/>
|