317 lines
16 KiB
Plaintext
317 lines
16 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Consul API Gateway Gateway
|
|
description: >-
|
|
Consul API Gateway Gateway
|
|
---
|
|
|
|
# Gateway
|
|
|
|
This topic provides full details about the `Gateway` resource.
|
|
|
|
## Introduction
|
|
|
|
A `Gateway` is an instance of network infrastructure that determines how service traffic should be handled. A `Gateway` contains one or more `listeners` that bind to a set of IP addresses. An `HTTPRoute` or `TCPRoute` can then attach to a gateway listener to direct traffic from the gateway to a service.
|
|
|
|
Gateway instances derive their configurations from the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource, which acts as a template for individual `Gateway` deployments. Refer to [GatewayClass](/docs/api-gateway/configuration/gatewayclass) for additional information.
|
|
|
|
Specify the following parameters to declare a Gateway:
|
|
|
|
| Parameter | Description | Required |
|
|
| -----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:|
|
|
| `kind` | Specifies the type of configuration object. The value should always be `Gateway`. | Required |
|
|
| `description` | Human-readable string that describes the purpose of the `Gateway`. | Optional |
|
|
| `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required |
|
|
| `scope` | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required |
|
|
| `fields` | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required |
|
|
|
|
|
|
|
|
## Configuration model
|
|
|
|
* `gatewayClassName`: string | required
|
|
* `listeners`: array of objects | required
|
|
* `allowedRoutes`: object | required
|
|
* `namespaces`: object | required
|
|
* `from`: string | required
|
|
* `selector`: object | required if from is configured to selector
|
|
* `matchExpressions`: array of objects | required if matchLabels is not configured
|
|
* `key`: string | required if matchExpressions is declared
|
|
* `operator`: string | required if matchExpressions is declared
|
|
* `values`: array of strings | required if matchExpressions is declared
|
|
* `matchLabels`: map of strings | required if matchExpressions is not configured
|
|
* `hostname`: string | required
|
|
* `name`: string | required
|
|
* `port`: integer | required
|
|
* `protocol`: string | required
|
|
* `tls`: object | required if protocol is set to HTTPS
|
|
* `certificateRefs`: array or objects | required if tls is declared
|
|
* `name`: string | required if certificateRefs is declared
|
|
* `namespace`: string | required if certificateRefs is declared
|
|
* `mode`: string | required if certificateRefs is declared
|
|
* `options`: map of strings | optional
|
|
|
|
## Specification
|
|
|
|
This topic provides details about the configuration parameters.
|
|
|
|
### gatewayClassName
|
|
Specifies the name of the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance.
|
|
* Type: string
|
|
* Required: required
|
|
|
|
### listeners
|
|
Specifies the `listeners` associated with the `Gateway`. At least one `listener` must be specified. Each `listener` within a `Gateway` must have a unique combination of `hostname`, `port`, and `protocol`.
|
|
|
|
* Type: array of objects
|
|
* Required: required
|
|
|
|
### listeners.allowedRoutes
|
|
Specifies a `namespace` object that defines the types of routes that may be attached to a listener.
|
|
* Type: object
|
|
* Required: required
|
|
|
|
### listeners.allowedRoutes.namespaces
|
|
Determines which routes are allowed to attach to the `listener`. Only routes in the same namespace as the `Gateway` may be attached by default.
|
|
|
|
### listeners.allowedRoutes.namespaces.from
|
|
Specifies the policy for which namespaces a route may attach to a `Gateway` from. Defaults to `Same`.
|
|
|
|
This parameter has the following properties:
|
|
* Type: string
|
|
* Required: required
|
|
|
|
You can specify one of the following strings:
|
|
* `All`: Routes in all namespaces may be attached to the `Gateway`.
|
|
* `Same`: Only routes in the same namespace as the `Gateway` may be attached.
|
|
* `Selector`: Only routes in namespaces that match the `selector` may be attached.
|
|
|
|
### listeners.allowedRoutes.namespaces.selector
|
|
Specifies a method of matching namespaces from which routes are allowed to attach to the listener.
|
|
* Type: Object
|
|
* Required: Required when `from` is configured to `Selector`.
|
|
|
|
The selector configuration contains one of the following objects:
|
|
* `matchExpressions`
|
|
* `matchLabels`
|
|
|
|
### listeners.allowedRoutes.namespaces.selector.matchExpressions
|
|
Specifies an array of requirements for matching namespaces. If a match is found, then routes from the matching namespace(s) are allowed to attach to the `Gateway`. The following table describes members of the `matchExpressions` array:
|
|
|
|
| Requirement | Description | Type |
|
|
|:-----------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:|
|
|
|`key` | Specifies that label that the key applies to. | string |
|
|
|`operator` | Specifies the key's relation to a set of values. The following values are valid:In: description of what this means NotIn: description of what this means Exists: description of what this means DoesNotExist: description of what this means | string |
|
|
|`values` | Specifies an array of string values. If the operator is configured to In or NotIn,the values array must be non-empty. If theoperator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. | array of strings |
|
|
|`scope` | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required |
|
|
|`fields` | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required |
|
|
|
|
```yaml
|
|
namespaceSelector:
|
|
matchExpressions:
|
|
- key: kubernetes.io/metadata.name
|
|
operator: In
|
|
values:
|
|
- foo
|
|
- bar
|
|
```
|
|
|
|
### listeners.allowedRoutes.namespaces.selector.matchLabels
|
|
Specifies an array of labels and label values. If a match is found, then routes with the matching label(s) are allowed to attach to the `Gateway`. This selector can contain any arbitrary key/value pair.
|
|
|
|
```yaml
|
|
namespaceSelector:
|
|
matchLabels:
|
|
foo: bar
|
|
```
|
|
|
|
For more on labels, see [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
|
|
|
|
### listeners.hostname
|
|
Specifies the `listener`'s hostname
|
|
* Type: string
|
|
* Required: required
|
|
|
|
### listeners.name
|
|
Specifies the `listener`'s name
|
|
* Type: string
|
|
* Required: required
|
|
|
|
### listeners.port
|
|
Specifies the port number that the `listener` will attach to
|
|
* Type: integer
|
|
* Required: required
|
|
|
|
### listeners.protocol
|
|
Specifies the protocol the `listener` will use
|
|
* Type: string
|
|
* Required: required
|
|
|
|
Allowed values are `TCP`, `HTTP`, or `HTTPS`
|
|
|
|
### listeners.tls
|
|
* Type: Object
|
|
* Required: required if `protocol` is set to `HTTPS`
|
|
|
|
### listeners.tls.certificateRefs
|
|
`CertificateRefs` contains a series of references to Kubernetes objects that contains TLS certificates and private keys. These certificates are used to establish a TLS handshake for requests that match the hostname of the associated `listener`. Each reference must be a Kubernetes Secret, and, if using a Secret in a namespace other than the`Gateway`'s, must have a corresponding `ReferencePolicy` created.
|
|
* Type: Object or Array
|
|
* Required: required if `tls` is set
|
|
|
|
### listeners.tls.mode
|
|
* Type: String
|
|
* Required: required if certificateRefs is set
|
|
|
|
### listeners.tls.options
|
|
* Type: Map of Strings
|
|
* Required: optional
|
|
|
|
## Complete configuration
|
|
The following example shows a fully configured `Gateway`.
|
|
|
|
```yaml
|
|
kind: Gateway
|
|
Description: This gateway enables traffic from A to B.
|
|
version: gateway.networking.k8s.io/v1alpha2
|
|
scope: Namespaced
|
|
fields:
|
|
- name: addresses
|
|
supported: false
|
|
- name: gatewayClassName
|
|
type: string
|
|
description: Name of a GatewayClass resource used for this Gateway.
|
|
- name: listeners
|
|
type: array<object>
|
|
description: |
|
|
Description of the listeners associated with this Gateway.
|
|
items:
|
|
fields:
|
|
- name: allowedRoutes
|
|
type: object
|
|
description: |
|
|
AllowedRoutes defines the types of routes that
|
|
MAY be attached to a Listener and the trusted namespaces where
|
|
those Route resources MAY be present.
|
|
fields:
|
|
- name: kinds
|
|
supported: false
|
|
- name: namespaces
|
|
type: object
|
|
description: |
|
|
Description of namespaces from which routes may be attached to this Listener. This is restricted
|
|
to the namespace of this Gateway by default.
|
|
fields:
|
|
- name: from
|
|
type: string
|
|
default: Same
|
|
description: |
|
|
From indicates where Routes will be selected
|
|
for this Gateway."
|
|
enum: ["All", "Selector", "Same"]
|
|
- name: selector
|
|
type: object
|
|
description: "Selector must be specified when From is
|
|
set to \"Selector\". In that case, only Routes in
|
|
Namespaces matching this Selector will be selected
|
|
by this Gateway."
|
|
fields:
|
|
- name: matchExpressions
|
|
type: array<object>
|
|
description: |
|
|
matchExpressions is a list of label
|
|
selector requirements. The requirements are ANDed.
|
|
items:
|
|
fields:
|
|
- name: key
|
|
type: string
|
|
description: |
|
|
key is the label key that the
|
|
selector applies to.
|
|
- name: operator
|
|
type: string
|
|
description: |
|
|
operator represents a key's relationship
|
|
to a set of values. Valid operators are
|
|
In, NotIn, Exists and DoesNotExist.
|
|
- name: values
|
|
type: array<string>
|
|
description: |
|
|
values is an array of string
|
|
values. If the operator is In or NotIn,
|
|
the values array must be non-empty. If the
|
|
operator is Exists or DoesNotExist, the
|
|
values array must be empty. This array is
|
|
replaced during a strategic merge patch.
|
|
- name: matchLabels
|
|
type: map<string, string>
|
|
description: |
|
|
matchLabels is a map of {key,value}
|
|
pairs. A single {key,value} in the matchLabels
|
|
map is equivalent to an element of matchExpressions,
|
|
whose key field is "key", the operator is "In",
|
|
and the values array contains only "value". The
|
|
requirements are ANDed.
|
|
- name: hostname
|
|
type: string
|
|
description: |
|
|
Hostname specifies the virtual hostname to match for HTTP or HTTPS-based listeners. When unspecified,
|
|
all hostnames are matched. This is implemented by checking the HTTP Host header sent on a client request.
|
|
- name: name
|
|
type: string
|
|
description: "Name is the name of the Listener. This name MUST be unique within a Gateway."
|
|
- name: port
|
|
type: integer
|
|
description: "Port is the network port of a listener."
|
|
- name: protocol
|
|
type: string
|
|
description: "Protocol specifies the network protocol this listener expects to receive."
|
|
enum: ["HTTP", "HTTPS", "TCP"]
|
|
- name: tls
|
|
type: object
|
|
description: |
|
|
TLS is the TLS configuration for the Listener.
|
|
This field is required if the Protocol field is "HTTPS".
|
|
It is invalid to set this field if the Protocol
|
|
field is "HTTP" or "TCP".
|
|
fields:
|
|
- name: certificateRefs
|
|
type: array<object>
|
|
description: |
|
|
CertificateRefs contains a series of references
|
|
to Kubernetes objects that contains TLS certificates and
|
|
private keys. These certificates are used to establish
|
|
a TLS handshake for requests that match the hostname of
|
|
the associated listener. Each reference must be a Kubernetes
|
|
Secret, and, if using a Secret in a namespace other than the
|
|
Gateway's, must have a corresponding ReferencePolicy created.
|
|
items:
|
|
fields:
|
|
- name: group
|
|
supported: false
|
|
- name: kind
|
|
supported: false
|
|
- name: name
|
|
type: string
|
|
description: Name is the name of the Kubernetes Secret.
|
|
- name: namespace
|
|
type: string
|
|
description: |
|
|
Namespace is the namespace of the Secret. When unspecified, the local namespace is inferred.
|
|
|
|
Note that when a namespace is specified, a ReferencePolicy
|
|
object is required in the specified namespace to
|
|
allow that namespace's owner to accept the reference.
|
|
- name: mode
|
|
type: string
|
|
default: Terminate
|
|
description: "Mode defines the TLS behavior for the TLS session initiated by the client. The only supported mode at this time is `Terminate`"
|
|
enum: ["Terminate"]
|
|
- name: options
|
|
type: map<string, string>
|
|
description: |
|
|
Options are a list of key/value pairs to enable
|
|
extended TLS configuration for each implementation.
|
|
enum: ["api-gateway.consul.hashicorp.com/tls_min_version","api-gateway.consul.hashicorp.com/tls_max_version","api-gateway.consul.hashicorp.com/tls_cipher_suites",]
|
|
```
|
|
|