github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/connect/config-entries/ingress-gateway.mdx

998 lines
25 KiB
Markdown
Raw Blame History

---
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
-> **v1.8.4+:** On Kubernetes, the `IngressGateway` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.8.0+:** On other platforms, this config entry is supported in Consul versions 1.8.0+.
The `ingress-gateway` config entry kind (`IngressGateway` on Kubernetes) allows you to configure ingress gateways
with listeners that expose a set of services outside the Consul service mesh.
For Kubernetes, see [Kubernetes Ingress Gateway](/docs/k8s/connect/ingress-gateways) for more information.
For other platforms, see [Ingress Gateway](/docs/connect/ingress-gateway).
~> **Note:** [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.<br />
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`.
## Sample Config Entries
### TCP listener
<Tabs>
<Tab heading="Consul OSS">
Set up a TCP listener on an ingress gateway named "us-east-ingress" to proxy traffic to the "db" service:
<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">
Set up a TCP listener on an ingress gateway named "us-east-ingress" in the default namespace
to proxy traffic to the "db" service in the ops namespace:
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
```hcl
Kind = "ingress-gateway"
Name = "us-east-ingress"
Namespace = "default"
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",
"Listeners": [
{
"Port": 3456,
"Protocol": "tcp",
"Services": [
{
"Namespace": "ops",
"Name": "db"
}
]
}
]
}
```
</CodeTabs>
</Tab>
</Tabs>
### Wildcard HTTP listener
<Tabs>
<Tab heading="Consul OSS">
Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the datacenter.
Also make two services available over a custom port with user-provided hosts, and enable TLS on every listener:
<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">
Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the frontend namespace.
Also make two services in the frontend namespace available over a custom port with user-provided hosts, and enable TLS on every listener:
<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"]
},
{
Namespace = "frontend"
Name = "web"
Hosts = ["website.example.com"]
}
]
}
]
```
```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']
- name: web
namespace: frontend
hosts: ['website.example.com']
```
```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"]
},
{
"Namespace": "frontend",
"Name": "web",
"Hosts": ["website.example.com"]
}
]
}
]
}
```
</CodeTabs>
</Tab>
</Tabs>
### HTTP listener with path-based routing
<Tabs>
<Tab heading="Consul OSS">
Set up an HTTP listener on an ingress gateway named "us-east-ingress" to proxy
traffic to a virtual service named "api".
Additionally, ensure internal-only debug headers are stripped before responding
to external clients, and that requests to internal services are labelled to
indicate which gateway they came through.
<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 yet 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">
Set up an HTTP listener on an ingress gateway named "us-east-ingress" in the
default namespace to proxy traffic to a virtual service named "api".
Additionally, ensure internal-only debug headers are stripped before responding
to external clients, and that requests to internal services are labelled to
indicate which gateway they came through.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
```hcl
Kind = "ingress-gateway"
Name = "us-east-ingress"
Namespace = "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 yet supported in Kubernetes CRD
```
```json
{
"Kind": "ingress-gateway",
"Name": "us-east-ingress",
"Namespace": "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>
The `api` service is not an actual registered service. It exist as a "virtual"
service for L7 configuration only. A `service-router` (`ServiceRouter` on Kubernetes) is defined for this
virtual service which 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"
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",
"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
<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 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.',
yaml: false,
},
{
name: 'Meta',
type: 'map<string|string>: nil',
description:
'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
yaml: false,
},
{
name: 'metadata',
children: [
{
name: 'name',
description: 'Set to the name of the service being configured.',
},
{
name: 'namespace',
description:
'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
},
],
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: '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-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\`.`,
},
{
name: 'Namespace',
type: 'string: ""',
enterprise: true,
description:
'The namespace to resolve the service from instead of the current namespace. If empty the current namespace is assumed.',
},
{
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.",
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.",
},
},
{
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.",
},
],
},
],
},
],
},
]}
/>
## 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`.
Reference in New Issue View Git Blame Copy Permalink