mirror of https://github.com/status-im/consul.git
fixed links and clarified some sections in gateway configuration doc
This commit is contained in:
trujillo-adam
parent
02b9c0d1ad
commit
5dad74df3c
|
|
@ -2,7 +2,7 @@
|
|||
layout: docs
|
||||
page_title: Consul API Gateway Gateway
|
||||
description: >-
|
||||
Consul API Gateway Gateway
|
||||
This topic descrbes how to configure the Consul API Gateway Gateway object
|
||||
---
|
||||
|
||||
# Gateway
|
||||
|
|
@ -22,34 +22,36 @@ Specify the following parameters to declare a Gateway:
|
|||
| `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 |
|
||||
| `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](#configuration-model). Details for each field are described in the [specification](#specification). | Required |
|
||||
|
||||
|
||||
|
||||
## Configuration model
|
||||
|
||||
* [`gatewayClassName`](#gatewayClassName): string | required
|
||||
The following outline shows how to format the configurations in the `Gateway` object. Click on a property name to view details about the configuration.
|
||||
|
||||
* [`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
|
||||
* [`allowedRoutes`](#listeners-allowedroutes): object | required
|
||||
* [`namespaces`](#listeners-allowedroutes-namespaces): object | required
|
||||
* [`from`](#listeners-namespaces-from): string | required
|
||||
* [`selector`](#listeners-allowedroutes-namespaces-selector): object | required if `from` is configured to `selector`
|
||||
* [`matchExpressions`](#listeners-allowedroutes-namespaces-selector-matchexpressions): array of objects | required if `matchLabels` is not configured
|
||||
* [`key`](#listeners-allowedroutes-namespaces-selector-matchexpressions): string | required if `matchExpressions` is declared
|
||||
* [`operator`](#listeners-allowedroutes-namespaces-selector-matchexpressions): string | required if `matchExpressions` is declared
|
||||
* [`values`](#listeners-allowedroutes-namespaces-selector-matchexpressions): array of strings | required if `matchExpressions` is declared
|
||||
* [`matchLabels`](#listeners-allowedroutes-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
|
||||
* [`tls`](#listeners-tls): object | required if `protocol` is set to `HTTPS`
|
||||
* [`certificateRefs`](#listeners-tls): array or objects | required if `tls` is declared
|
||||
* [`name`](#listeners-tls): string | required if `certificateRefs` is declared
|
||||
* [`namespace`](#listeners-tls): string | required if `certificateRefs` is declared
|
||||
* [`mode`](#listeners-tls): string | required if `certificateRefs` is declared
|
||||
* [`options`](#listeners-tls): map of strings | optional
|
||||
|
||||
## Specification
|
||||
|
||||
|
|
@ -74,37 +76,34 @@ Specifies a `namespace` object that defines the types of routes that may be atta
|
|||
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`.
|
||||
Determines which namespaces are allowed to attach a route to the `Gateway`. You can specify one of the following strings:
|
||||
|
||||
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.
|
||||
* `Same` (default): Only routes in the same namespace as the `Gateway` may be attached.
|
||||
* `Selector`: Only routes in namespaces that match the [`selector`](#listeners-allowedroutes-namespaces-selector) may be attached.
|
||||
|
||||
This parameter is required.
|
||||
|
||||
### 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`.
|
||||
Specifies a method for selecting routes that are allowed to attach to the listener. The `Gateway` checks for namespaces in the network that match either a regular expression or a label. Routes from the matching namespace are allowed to attach to the listener.
|
||||
|
||||
The selector configuration contains one of the following objects:
|
||||
* `matchExpressions`
|
||||
* `matchLabels`
|
||||
You can configure one of the following objects:
|
||||
|
||||
* [`matchExpressions`](#listeners-allowedroutes-namespaces-selector-matchexpressions)
|
||||
* [`matchLabels`](#listeners-allowedroutes-namespaces-selector-matchlabels)
|
||||
|
||||
This field is required when [`from`](#listeners-allowedroutes-namespaces-from) is configured to `Selector`.
|
||||
|
||||
### 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 |
|
||||
| Requirement | Description | Type | Required |
|
||||
|--- |--- |--- |--- |
|
||||
|`key` | Specifies the label that the `key` applies to. | string | required when `matchExpressions` is declared |
|
||||
|`operator` | Specifies the key's relation to a set of values. You can use the following keywords: <ul><li>`In`: Only routes in namespaces that contain the strings in the `values` field can attach to the `Gateway`. </li><li>`NotIn`: Routes in namespaces that do not contain the strings in the `values` field can attach to the `Gateway`. </li><li>`Exists`: Routes in namespaces that contain the `key` value are allowed to attach to the `Gateway`.</li><li>`DoesNotExist`: Routes in namespaces that do not contain the `key` value are allowed to attach to the `Gateway`.</li></ul> | string | required when `matchExpressions` is declared |
|
||||
|`values` | Specifies an array of string values. If `operator` is configured to `In` or `NotIn`, then the `values` array must contain values. If `operator` is configured to `Exists` or `DoesNotExist`, then the `values` array must be empty. This array is replaced during a strategic merge patch. | array of strings | required when `matchExpressions` is declared |
|
||||
|
||||
In the following example, routes in namespaces that contain `foo` and `bar` are allowed to attach routes to the `Gateway`.
|
||||
```yaml
|
||||
namespaceSelector:
|
||||
matchExpressions:
|
||||
|
|
@ -118,52 +117,62 @@ namespaceSelector:
|
|||
### 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.
|
||||
|
||||
In the following example, routes in namespaces that have a `bar` label are allowed to attache to the `Gateway`.
|
||||
```yaml
|
||||
namespaceSelector:
|
||||
matchLabels:
|
||||
foo: bar
|
||||
```
|
||||
|
||||
For more on labels, see [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
|
||||
Refer to [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) in the Kubernetes documentation for additional information about labels.
|
||||
|
||||
### listeners.hostname
|
||||
Specifies the `listener`'s hostname
|
||||
Specifies the `listener`'s hostname.
|
||||
* Type: string
|
||||
* Required: required
|
||||
|
||||
### listeners.name
|
||||
Specifies the `listener`'s name
|
||||
Specifies the `listener`'s name.
|
||||
* Type: string
|
||||
* Required: required
|
||||
|
||||
### listeners.port
|
||||
Specifies the port number that the `listener` will attach to
|
||||
Specifies the port number that the `listener` attaches to.
|
||||
* Type: integer
|
||||
* Required: required
|
||||
|
||||
### listeners.protocol
|
||||
Specifies the protocol the `listener` will use
|
||||
Specifies the protocol the `listener` communicates on.
|
||||
* Type: string
|
||||
* Required: required
|
||||
|
||||
Allowed values are `TCP`, `HTTP`, or `HTTPS`
|
||||
|
||||
### listeners.tls
|
||||
* Type: Object
|
||||
* Required: required if `protocol` is set to `HTTPS`
|
||||
Specifies the `tls` configurations for the `Gateway`. The `tls` object is required if `protocol` is set to `HTTPS`. The object contains the following fields:
|
||||
|
||||
### 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
|
||||
| Parameter | Description | Type | Required |
|
||||
| --- | --- | --- | --- |
|
||||
| `certificateRefs` | <div style={{width:480}}>Specifies Kubernetes `name` and `namespace` objects that contains TLS certificates and private keys. <br/>The certificates establish a TLS handshake for requests that match the `hostname` of the associated `listener`. Each reference must be a Kubernetes Secret. If you are using a Secret in a namespace other than the `Gateway`'s, each reference must also have a corresponding [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy).</div> | Object or array | Required if `tls` is set |
|
||||
| `mode` | Specifies the ? | string | Required if `certificateRefs` is set |
|
||||
| `options` | ??? | Map of strings | optional |
|
||||
|
||||
### listeners.tls.mode
|
||||
* Type: String
|
||||
* Required: required if certificateRefs is set
|
||||
In the following example, `tls` settings are configured . . .
|
||||
|
||||
```yaml
|
||||
|
||||
tls:
|
||||
certificateRefs:
|
||||
name: ?
|
||||
namespace: ?
|
||||
mode: ?
|
||||
options:
|
||||
- ?
|
||||
- ?
|
||||
- ?
|
||||
|
||||
```
|
||||
|
||||
### listeners.tls.options
|
||||
* Type: Map of Strings
|
||||
* Required: optional
|
||||
|
||||
## Complete configuration
|
||||
The following example shows a fully configured `Gateway`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue