status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/api-gateway/configuration/gateway.mdx

316 lines
16 KiB
Plaintext
Raw Blame History

---
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`)[#gatewayClassName]: string | required
* (`listeners`)[#listeners]: array of objects | required
* (`allowedRoutes`)[#listeners-allowedRoutes]: object | required
* (`namespaces`}[#listeners-namespaces]: object | required
* (`from`)[#listeners-namespaces-from]: string | required
* (`selector`)[#listeners-namespaces-selector]: object | required if from is configured to selector
* (`matchExpressions`)[#listeners-namespaces-selector-matchExpressions]: array of objects | required if matchLabels is not configured
* (`key`)[#listeners-namespaces-selector-matchExpressions-key]: string | required if matchExpressions is declared
* (`operator`)[#listeners.namespaces-selector-operator]: string | required if matchExpressions is declared
* (`values`)[#listeners.namespaces-selector-values]: array of strings | required if matchExpressions is declared
* (`matchLabels`)[#listeners-namespaces-selector-matchLabels]: map of strings | required if matchExpressions is not configured
* (`hostname`)[#listeners-hostname]: string | required
* (`name`)[#listeners-name]: string | required
* (`port`)[#listeners-port]: integer | required
* (`protocol`)[#listeners-protocol]`: string | required
* (`tls`)[#listeners-tls]: object | required if protocol is set to HTTPS
* (`certificateRefs`)[#listeners-tls-certificateRefs]: array or objects | required if tls is declared
* (`name`)[#listeners-tls-certificateRefs-name]: string | required if certificateRefs is declared
* (`namespace`)[#listeners-tls-certificateRefs-namespace]: string | required if certificateRefs is declared
* (`mode`)[#listeners-tls-mode]: string | required if certificateRefs is declared
* (`options`)[#listeners-tls-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. Unless a custom [GatewayClass](/docs/api-gateway/configuration/gatewayclass) is being used, value should be set to `consul-api-gateway`
* 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",]
```
Reference in New Issue View Git Blame Copy Permalink