diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index ea01afa62..61b36b65e 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -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: | 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` |
Specifies Kubernetes `name` and `namespace` objects that contains TLS certificates and private keys.
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).
| 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`.