diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway.mdx index 79c5ba32d4..5cddea611c 100644 --- a/website/content/docs/api-gateway.mdx +++ b/website/content/docs/api-gateway.mdx @@ -253,16 +253,18 @@ Refer to the Kubernetes Gateway API documentation for details about configuring Listeners are the logical endpoints bound to the gateway's addresses. Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener: -- `hostname`: Hostname specifies the virtual hostname to match for protocol types. -- `port`: Specifies the network port. -- `protocol`: Specifies the network protocol expected by the listener. -- `tls` [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig) - - `mode` [`TLSModeType`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType): Defaults to `Terminate` if unspecified, `Passthrough` is not yet supported. - - `certificateRefs` [`[]*SecretObjectReference`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference): Used for Envoy SDS (Secret Discovery Service) to support terminating TLS. - - `options`: Key/value pairs to enable implementation-specific extended TLS configuration. Consul API Gateway supports the following options: - - `"api-gateway.consul.hashicorp.com/tls_min_version"`: Set the minimum TLS version supported for this listener. Allowed values are `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. If unspecified, Consul API Gateway will default to TLS 1.2. - - `"api-gateway.consul.hashicorp.com/tls_max_version"`: Set the maximum TLS version supported for this listener. Must be greater than or equal to `TLSMinVersion`. Allowed values are `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Consul API Gateway will use Envoy's current default of TLS 1.3. - - `"api-gateway.consul.hashicorp.com/tls_cipher_suites"`: Set the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier. If unspecified, Consul API Gateway will set a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [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 full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) 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 API Gateway may add new supported cipher suites if any are added to Envoy. +| Parameter | Description | Type | Default | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | +| `hostname` | Specifies the virtual hostname to match for protocol types. | String | none | +| `port` | Specifies the network port number. | Integer | none | +| `protocol` | Specifies the network protocol expected by the listener. | String | `http` | +| `tls` | Collection of parameters that specify TLS options for the listener. Refer to the [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig) documentation for additional information about configuring TLS. | Object | N/A | +| `tls.mode` | Specifies a mode for operating Consul API Gateway listeners over TLS.
You can only specify the `Terminate` mode, which configures the TLS session between the downstream client and the gateway to terminate at the gateway.
Refer to the [`TLSModeType` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType) for additional information. | String | `Terminate` | +| `tls.certificateRefs` | Specifies the name of secret object used for Envoy SDS (Secret Discovery Service) to support terminating TLS. Refer to the [`[]*SecretObjectReference` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference) for additional information. | String | N/A | +| `tls.options` | Specifies key/value pairs to enable extended TLS configuration specific to an implementation. | Object | N/A | +| `tls.options.tls_min_version` | Specifies the minimum TLS version supported for the listener. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.2` | +| `tls.options.tls_max_version"` | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.3` | +| `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier.
If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [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) will be used.
The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String | See description | Refer to the Kubernetes Gateway API documentation for details about configuring listeners: