Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update gateway listener compatibility doc #829

Merged
merged 3 commits into from
Jul 7, 2023
Merged

Update gateway listener compatibility doc #829

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
94f11ab
Reformat api compatibility doc
pleshakov Jul 7, 2023
7dd2511
Update gateway api compatibility doc for Gateway listener
pleshakov Jul 7, 2023
d05aade
Merge branch 'main' into doc/gateway-listener-compatibility
pleshakov Jul 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 119 additions & 93 deletions docs/gateway-api-compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,139 +4,162 @@ This document describes which Gateway API resources NGINX Kubernetes Gateway sup

## Summary

| Resource | Support Status |
|-|-|
| [GatewayClass](#gatewayclass) | Partially supported |
| [Gateway](#gateway) | Partially supported |
| [HTTPRoute](#httproute) | Partially supported |
| [TLSRoute](#tlsroute) | Not supported |
| [TCPRoute](#tcproute) | Not supported |
| [UDPRoute](#udproute) | Not supported |
| [ReferenceGrant](#referencegrant) | Supported |
| [Custom policies](#custom-policies) | Not supported |
| Resource | Support Status |
|-------------------------------------|---------------------|
| [GatewayClass](#gatewayclass) | Partially supported |
| [Gateway](#gateway) | Partially supported |
| [HTTPRoute](#httproute) | Partially supported |
| [TLSRoute](#tlsroute) | Not supported |
| [TCPRoute](#tcproute) | Not supported |
| [UDPRoute](#udproute) | Not supported |
| [ReferenceGrant](#referencegrant) | Supported |
| [Custom policies](#custom-policies) | Not supported |

## Terminology

We use the following words to describe support status:

- *Supported*. The resource or field is fully supported and conformant to the Gateway API specification.
- *Partially supported*. The resource or field is supported partially or with limitations. It will become fully supported in future releases.
- *Not supported*. The resource or field is not yet supported. It will become partially or fully supported in future releases.
- *Partially supported*. The resource or field is supported partially or with limitations. It will become fully
supported in future releases.
- *Not supported*. The resource or field is not yet supported. It will become partially or fully supported in future
releases.

Note: it might be possible that NGINX Kubernetes Gateway will never support some resources and/or fields of the Gateway API. We will document these decisions on a case by case basis.
Note: it might be possible that NGINX Kubernetes Gateway will never support some resources and/or fields of the Gateway
API. We will document these decisions on a case by case basis.

## Resources

Below we list the resources and the support status of their corresponding fields.
Below we list the resources and the support status of their corresponding fields.

For a description of each field, visit the [Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/).
For a description of each field, visit
the [Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/).

### GatewayClass
### GatewayClass

> Status: Partially supported.
> Status: Partially supported.

NGINX Kubernetes Gateway supports only a single GatewayClass resource configured via `--gatewayclass` flag
of the [static-mode](./cli-help.md#static-mode) command.

Fields:

* `spec`
* `controllerName` - supported.
* `parametersRef` - not supported.
* `description` - supported.
* `status`
* `conditions` - supported (Condition/Status/Reason):
* `Accepted/True/Accepted`
* `Accepted/False/InvalidParameters`
* `Accepted/False/GatewayClassConflict`: Custom reason for when the GatewayClass references this controller, but a different GatewayClass name is provided to the controller via the command-line argument.
* `Accepted/True/Accepted`
* `Accepted/False/InvalidParameters`
* `Accepted/False/GatewayClassConflict`: Custom reason for when the GatewayClass references this controller, but
a different GatewayClass name is provided to the controller via the command-line argument.

### Gateway

> Status: Partially supported.

NGINX Kubernetes Gateway supports only a single Gateway resource. The Gateway resource must reference NGINX Kubernetes Gateway's corresponding GatewayClass.
NGINX Kubernetes Gateway supports only a single Gateway resource. The Gateway resource must reference NGINX Kubernetes
Gateway's corresponding GatewayClass.
See [static-mode](./cli-help.md#static-mode) command for more info.

Fields:

* `spec`
* `gatewayClassName` - supported.
* `listeners`
* `name` - supported.
* `hostname` - supported.
* `port` - supported.
* `port` - supported.
* `protocol` - partially supported. Allowed values: `HTTP`, `HTTPS`.
* `tls`
* `mode` - partially supported. Allowed value: `Terminate`.
* `certificateRefs` - partially supported. The TLS certificate and key must be stored in a Secret resource of type `kubernetes.io/tls` in the same namespace as the Gateway resource. Only a single reference is supported. You must deploy the Secret before the Gateway resource. Secret rotation (watching for updates) is not supported.
* `options` - not supported.
* `mode` - partially supported. Allowed value: `Terminate`.
* `certificateRefs` - The TLS certificate and key must be stored in a Secret resource of
type `kubernetes.io/tls`. Only a single reference is supported. You must deploy the Secret before the
Gateway resource.
* `options` - not supported.
* `allowedRoutes` - supported.
* `addresses` - not supported.
* `status`
* `addresses` - Pod IPAddress supported.
* `conditions` - Supported (Condition/Status/Reason):
* `Accepted/True/Accepted`
* `Accepted/True/ListenersNotValid`
* `Accepted/False/ListenersNotValid`
* `Accepted/False/Invalid`
* `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Gateway is invalid or not supported.
* `Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NKG only supports a single Gateway.
* `Programmed/True/Programmed`
* `Programmed/False/Invalid`
* `Programmed/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NKG only supports a single Gateway.
* `listeners`
* `name` - supported.
* `supportedKinds` - not supported.
* `attachedRoutes` - supported.
* `addresses` - Pod IPAddress supported.
* `conditions` - Supported (Condition/Status/Reason):
* `Accepted/True/Accepted`
* `Accepted/False/UnsupportedProtocol`
* `Accepted/False/InvalidCertificateRef`
* `Accepted/False/ProtocolConflict`
* `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Listener is invalid or not supported.
* `Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NKG only supports a single Gateway.
* `Programmed/True/Programmed`
* `Programmed/False/Invalid`
* `ResolvedRefs/True/ResolvedRefs`
* `ResolvedRefs/False/InvalidCertificateRef`
* `ResolvedRefs/False/InvalidRouteKinds`
* `Conflicted/True/ProtocolConflict`
* `Conflicted/False/NoConflicts`
* `Accepted/True/Accepted`
* `Accepted/True/ListenersNotValid`
* `Accepted/False/ListenersNotValid`
* `Accepted/False/Invalid`
* `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Gateway is invalid or not
supported.
* `Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway.
NKG only supports a single Gateway.
* `Programmed/True/Programmed`
* `Programmed/False/Invalid`
* `Programmed/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting
Gateway. NKG only supports a single Gateway.
* `listeners`
* `name` - supported.
* `supportedKinds` - not supported.
* `attachedRoutes` - supported.
* `conditions` - Supported (Condition/Status/Reason):
* `Accepted/True/Accepted`
* `Accepted/False/UnsupportedProtocol`
* `Accepted/False/InvalidCertificateRef`
* `Accepted/False/ProtocolConflict`
* `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Listener is invalid or
not supported.
* `Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting
Gateway. NKG only supports a single Gateway.
* `Programmed/True/Programmed`
* `Programmed/False/Invalid`
* `ResolvedRefs/True/ResolvedRefs`
* `ResolvedRefs/False/InvalidCertificateRef`
* `ResolvedRefs/False/InvalidRouteKinds`
* `Conflicted/True/ProtocolConflict`
* `Conflicted/False/NoConflicts`

### HTTPRoute

> Status: Partially supported.

Fields:

* `spec`
* `parentRefs` - partially supported. Port not supported.
* `hostnames` - supported.
* `rules`
* `matches`
* `path` - partially supported. Only `PathPrefix` and `Exact` types.
* `headers` - partially supported. Only `Exact` type.
* `queryParams` - partially supported. Only `Exact` type.
* `method` - supported.
* `filters`
* `type` - supported.
* `requestRedirect` - supported except for the experimental `path` field. If multiple filters with `requestRedirect` are configured, NGINX Kubernetes Gateway will choose the first one and ignore the rest.
* `requestHeaderModifier` - supported. If multiple filters with `requestHeaderModifier` are configured, NGINX Kubernetes Gateway will choose the first one and ignore the rest.
* `responseHeaderModifier`, `requestMirror`, `urlRewrite`, `extensionRef` - not supported.
* `backendRefs` - partially supported. Backend ref `filters` are not supported.
* `parentRefs` - partially supported. Port not supported.
* `hostnames` - supported.
* `rules`
* `matches`
* `path` - partially supported. Only `PathPrefix` and `Exact` types.
* `headers` - partially supported. Only `Exact` type.
* `queryParams` - partially supported. Only `Exact` type.
* `method` - supported.
* `filters`
* `type` - supported.
* `requestRedirect` - supported except for the experimental `path` field. If multiple filters
with `requestRedirect` are configured, NGINX Kubernetes Gateway will choose the first one and ignore the
rest.
* `requestHeaderModifier` - supported. If multiple filters with `requestHeaderModifier` are configured,
NGINX Kubernetes Gateway will choose the first one and ignore the rest.
* `responseHeaderModifier`, `requestMirror`, `urlRewrite`, `extensionRef` - not supported.
* `backendRefs` - partially supported. Backend ref `filters` are not supported.
* `status`
* `parents`
* `parentRef` - supported.
* `controllerName` - supported.
* `conditions` - partially supported. Supported (Condition/Status/Reason):
* `Accepted/True/Accepted`
* `Accepted/False/NoMatchingListenerHostname`
* `Accepted/False/NoMatchingParent`
* `Accepted/False/NotAllowedByListeners`
* `Accepted/False/UnsupportedValue`: Custom reason for when the HTTPRoute includes an invalid or unsupported value.
* `Accepted/False/InvalidListener`: Custom reason for when the HTTPRoute references an invalid listener.
* `Accepted/False/GatewayNotProgrammed`: Custom reason for when the Gateway is not Programmed. HTTPRoute may be valid and configured, but will maintain this status as long as the Gateway is not Programmed.
* `ResolvedRefs/True/ResolvedRefs`
* `ResolvedRefs/False/InvalidKind`
* `ResolvedRefs/False/RefNotPermitted`
* `ResolvedRefs/False/BackendNotFound`
* `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the HTTPRoute rules has a backendRef with an unsupported value.
* `parents`
* `parentRef` - supported.
* `controllerName` - supported.
* `conditions` - partially supported. Supported (Condition/Status/Reason):
* `Accepted/True/Accepted`
* `Accepted/False/NoMatchingListenerHostname`
* `Accepted/False/NoMatchingParent`
* `Accepted/False/NotAllowedByListeners`
* `Accepted/False/UnsupportedValue`: Custom reason for when the HTTPRoute includes an invalid or unsupported
value.
* `Accepted/False/InvalidListener`: Custom reason for when the HTTPRoute references an invalid listener.
* `Accepted/False/GatewayNotProgrammed`: Custom reason for when the Gateway is not Programmed. HTTPRoute may
be valid and configured, but will maintain this status as long as the Gateway is not Programmed.
* `ResolvedRefs/True/ResolvedRefs`
* `ResolvedRefs/False/InvalidKind`
* `ResolvedRefs/False/RefNotPermitted`
* `ResolvedRefs/False/BackendNotFound`
* `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the HTTPRoute rules has a backendRef
with an unsupported value.

### TLSRoute

Expand All @@ -156,20 +179,23 @@ Fields:
> Support Level: Core

Fields:

* `spec`
* `to`
* `group` - supported.
* `kind` - supports `Secret` and `Service`.
* `name`- supported.
* `from`
* `group` - supported.
* `kind` - supports `Gateway` and `HTTPRoute`.
* `namespace`- supported.
* `to`
* `group` - supported.
* `kind` - supports `Secret` and `Service`.
* `name`- supported.
* `from`
* `group` - supported.
* `kind` - supports `Gateway` and `HTTPRoute`.
* `namespace`- supported.

### Custom Policies

> Status: Not supported.

Custom policies will be NGINX Kubernetes Gateway-specific CRDs that will allow supporting features like timeouts, load-balancing methods, authentication, etc. - important data-plane features that are not part of the Gateway API spec.
Custom policies will be NGINX Kubernetes Gateway-specific CRDs that will allow supporting features like timeouts,
load-balancing methods, authentication, etc. - important data-plane features that are not part of the Gateway API spec.

While those CRDs are not part of the Gateway API, the mechanism of attaching them to Gateway API resources is part of the Gateway API. See the [Policy Attachment doc](https://gateway-api.sigs.k8s.io/references/policy-attachment/).
While those CRDs are not part of the Gateway API, the mechanism of attaching them to Gateway API resources is part of
the Gateway API. See the [Policy Attachment doc](https://gateway-api.sigs.k8s.io/references/policy-attachment/).