This topic provides reference information for the `ingress-gateway` configuration entry.
This topic provides reference information for the `ingress-gateway` configuration entry.
## Introduction
@ -20,20 +20,20 @@ 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.
- 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. Specify the `ingress-gateway` (`IngressGateway`) configuration in the agent configuration file (see [config_entries](/docs/agent/options#config_entries)) as described in [Configuration](#configuration).
1. Apply the configuration 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.
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
## Configuration
Use the following syntax to configure an ingress gateway.
Use the following syntax to configure an ingress gateway.
<Tabs>
<Tab heading="Consul OSS">
@ -153,11 +153,12 @@ spec:
]
}
```
</CodeTabs>
</Tab>
</Tabs>
</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.
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
@ -202,7 +203,6 @@ The following examples describe possible use-cases for ingress gateway configura
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):
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 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):
- 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">
@ -557,7 +557,7 @@ spec:
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.
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>
@ -693,7 +693,7 @@ spec:
{
"Name": "api",
"Namespace": "frontend",
"RequestHeaders": {
"RequestHeaders": {
"Add": {
"x-gateway": "us-east-ingress"
}
@ -899,7 +899,7 @@ spec:
## Available Fields
You can specify the following parameters to configure ingress gateway configuration entries.
You can specify the following parameters to configure ingress gateway configuration entries.
<ConfigEntryReference
keys={[
@ -942,11 +942,11 @@ You can specify the following parameters to configure ingress gateway configurat
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.' +
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,
yaml: false,
},
{
name: 'metadata',
@ -961,12 +961,6 @@ You can specify the following parameters to configure ingress gateway configurat
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)).',
},
{
name: 'partition',
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. Refer to the [Admin Partitions documentation](/docs/enterprise/admin-partitions) for additional information. The `partitions` parameter is not supported in Consul OSS.',
},
],
hcl: false,
},
@ -989,17 +983,20 @@ You can specify the following parameters to configure ingress gateway configurat
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.",
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).",
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.",
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.',
},
],
},
@ -1094,34 +1091,36 @@ You can specify the following parameters to configure ingress gateway configurat
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.
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.",
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',
@ -1142,17 +1141,20 @@ You can specify the following parameters to configure ingress gateway configurat
{
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.",
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).",
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.",
description:
'The SDS resource name to request when fetching the certificate from the SDS service.',
},
],
},
@ -1162,4 +1164,3 @@ You can specify the following parameters to configure ingress gateway configurat
trujillo-adam
3 years ago