Skip to content

Restructure, reformat and rewrite API Compatibility Documentation #1337

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

Merged
merged 12 commits into from
Dec 7, 2023
Merged

Restructure, reformat and rewrite API Compatibility Documentation #1337

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
110df75
Migrate docs to docs.nginx.com (#1226)
JTorreG Nov 29, 2023
a5ae669
fix: fix links in github docs to d-n-c (#1291)
JTorreG Nov 30, 2023
e886318
Fix installation docs for mismatched versions (#1287)
sjberman Nov 30, 2023
ba2b986
Update Control Plane Configuration documentation for Hugo formatting …
ADubhlaoich Nov 30, 2023
fdeec8f
docs: update architecture doc (#1295)
JTorreG Nov 30, 2023
afb7c09
Merge branch 'main' into docs/hugo-docs
sjberman Nov 30, 2023
3693faa
Restructure, reformat and rewrite API Compatibility Documentation
ADubhlaoich Dec 5, 2023
eff2e08
Merge remote-tracking branch 'upstream/main' into docs/api-compatibil…
ADubhlaoich Dec 5, 2023
60b478d
Merge branch 'main' into docs/api-compatibility-review
ADubhlaoich Dec 5, 2023
95bf251
Merge branch 'main' into docs/api-compatibility-review
ADubhlaoich Dec 6, 2023
b656a3c
Update site/content/overview/gateway-api-compatibility.md
ADubhlaoich Dec 6, 2023
b69fe1f
Merge branch 'main' into docs/api-compatibility-review
sjberman Dec 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
249 changes: 138 additions & 111 deletions site/content/overview/gateway-api-compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,52 +11,37 @@ docs: "DOCS-000"
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| [GatewayClass](#gatewayclass) | Supported | Not supported | Not Supported | v1 |
| [Gateway](#gateway) | Supported | Not supported | Not Supported | v1 |
| [HTTPRoute](#httproute) | Supported | Partially supported | Not Supported | v1 |
| [ReferenceGrant](#referencegrant) | Supported | N/A | Not Supported | v1beta1 |
| [Custom policies](#custom-policies) | Not supported | N/A | Not Supported | N/A |
| [TLSRoute](#tlsroute) | Not supported | Not supported | Not Supported | N/A |
| [TCPRoute](#tcproute) | Not supported | Not supported | Not Supported | N/A |
| [UDPRoute](#udproute) | Not supported | Not supported | Not Supported | N/A |
| [Gateway](#gateway) | Supported | Not supported | Not supported | v1 |
| [GatewayClass](#gatewayclass) | Supported | Not supported | Not supported | v1 |
| [HTTPRoute](#httproute) | Supported | Partially supported | Not supported | v1 |
| [ReferenceGrant](#referencegrant) | Supported | N/A | Not supported | v1beta1 |
| [TLSRoute](#tlsroute) | Not supported | Not supported | Not supported | N/A |
| [TCPRoute](#tcproute) | Not supported | Not supported | Not supported | N/A |
| [UDPRoute](#udproute) | Not supported | Not supported | Not supported | N/A |
| [Custom policies](#custom-policies) | Not supported | N/A | Not supported | N/A |
{{< /bootstrap-table >}}

---

## Terminology

Gateway API features has three [support levels](https://gateway-api.sigs.k8s.io/concepts/conformance/#2-support-levels):
Core, Extended and Implementation-specific. We use the following terms to describe the support status for each level and
resource field:
Gateway API features has three [support levels](https://gateway-api.sigs.k8s.io/concepts/conformance/#2-support-levels): Core, Extended and Implementation-specific. We use the following terms to describe the support status for each level and resource field:

- *Supported*. The resource or field is fully supported.
- *Partially supported*. The resource or field is supported partially or with limitations. It will become fully
- _Supported_. The resource or field is fully supported.
- _Partially supported_. The resource or field is supported partially, 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
- _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 Gateway Fabric will never support some resources
> and/or fields of the Gateway API. We will document these decisions on a case by case basis.
>
> NGINX Gateway Fabric doesn't support any features from the experimental release channel.

## Resources

Below we list the resources and the support status of their corresponding fields.
{{< note >}} It's possible that NGINX Gateway Fabric will never support some resources or fields of the Gateway API. They will be documented on a case by case basis. NGINX Gateway Fabric doesn't support any features from the experimental release channel. {{< /note >}}

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

### GatewayClass
---

> Support Levels:
>
> - Core: Supported.
> - Extended: Not supported.
> - Implementation-specific: Not supported.
## Resources

NGINX Gateway Fabric supports only a single GatewayClass resource configured via `--gatewayclass` flag of
the [static-mode](./cli-help.md#static-mode) command.
Each resource below includes the support status of their corresponding fields.

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

- `spec`
- `controllerName` - supported.
Expand All @@ -72,61 +57,59 @@ Fields:
- `SupportedVersion/True/SupportedVersion`
- `SupportedVersion/False/UnsupportedVersion`

---

### Gateway

> Support Levels:
>
> - Core: Supported.
> - Extended: Partially supported.
> - Implementation-specific: Not supported.
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| Gateway | Supported | Not supported | Not supported | v1 |
{{< /bootstrap-table >}}

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

Fields:
See the [static-mode]({{< relref "/reference/cli-help.md#static-mode">}}) command for more information.

**Fields**:

- `spec`
- `gatewayClassName` - supported.
- `gatewayClassName`: Supported.
- `listeners`
- `name` - supported.
- `hostname` - supported.
- `port` - supported.
- `protocol` - partially supported. Allowed values: `HTTP`, `HTTPS`.
- `name`: Supported.
- `hostname`: Supported.
- `port`: Supported.
- `protocol`: Partially supported. Allowed values: `HTTP`, `HTTPS`.
- `tls`
- `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.
- `options` - not supported.
- `allowedRoutes` - supported.
- `addresses` - 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.
- `options`: Not supported.
- `allowedRoutes`: Supported.
- `addresses`: Not supported.
- `status`
- `addresses` - partially supported. LoadBalancer and Pod IP.
- `conditions` - supported (Condition/Status/Reason):
- `addresses`: Partially supported (LoadBalancer and Pod IP).
- `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.
- `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.
NGF 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. NGF only supports a single Gateway.
- `Programmed/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NGF only supports a single Gateway.
- `listeners`
- `name` - supported.
- `supportedKinds` - supported.
- `attachedRoutes` - supported.
- `conditions` - supported (Condition/Status/Reason):
- `name`: Supported.
- `supportedKinds`: 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. NGF only supports a single Gateway.
- `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. NGF only supports a single Gateway.
- `Programmed/True/Programmed`
- `Programmed/False/Invalid`
- `ResolvedRefs/True/ResolvedRefs`
Expand All @@ -135,63 +118,85 @@ Fields:
- `Conflicted/True/ProtocolConflict`
- `Conflicted/False/NoConflicts`

---

### GatewayClass

{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| GatewayClass | Supported | Not supported | Not supported | v1 |
{{< /bootstrap-table >}}

NGINX Gateway Fabric supports a single GatewayClass resource configured with the `--gatewayclass` flag of the [static-mode]({{< relref "/reference/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 status for when GatewayClass references this controller, but a different GatewayClass name is provided to the controller via the command-line argument.

---

### HTTPRoute

> Support Levels:
>
> - Core: Supported.
> - Extended: Partially supported.
> - Implementation-specific: Not supported.
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| HTTPRoute | Supported | Partially supported | Not supported | v1 |
{{< /bootstrap-table >}}

Fields:
**Fields**:

- `spec`
- `parentRefs` - partially supported. Port not supported.
- `hostnames` - 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.
- `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 Gateway Fabric will choose the first one and ignore the
rest.
- `requestHeaderModifier` - supported. If multiple filters with `requestHeaderModifier` are configured,
NGINX Gateway Fabric will choose the first one and ignore the rest.
- `responseHeaderModifier`, `requestMirror`, `urlRewrite`, `extensionRef` - not supported.
- `backendRefs` - partially supported. Backend ref `filters` are not supported.
- `type`: Supported.
- `requestRedirect`: Supported except for the experimental `path` field. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest.
- `requestHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first 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):
- `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.
- `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 can 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.
- `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the HTTPRoute rules has a backendRef with an unsupported value.
- `PartiallyInvalid/True/UnsupportedValue`

---

### ReferenceGrant

> Support Levels:
>
> - Core: Supported.
> - Extended: N/A.
> - Implementation-specific: N/A
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| ReferenceGrant | Supported | N/A | Not supported | v1beta1 |
{{< /bootstrap-table >}}

Fields:

Expand All @@ -205,24 +210,46 @@ Fields:
- `kind` - supports `Gateway` and `HTTPRoute`.
- `namespace`- supported.

---

### TLSRoute

> Status: Not supported.
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| TLSRoute | Not supported | Not supported | Not supported | N/A |
{{< /bootstrap-table >}}

---

### TCPRoute

> Status: Not supported.
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| TCPRoute | Not supported | Not supported | Not supported | N/A |
{{< /bootstrap-table >}}

---

### UDPRoute

> Status: Not supported.
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| UDPRoute | Not supported | Not supported | Not supported | N/A |
{{< /bootstrap-table >}}

---

### Custom Policies

> Status: Not supported.
{{< bootstrap-table "table table-striped table-bordered" >}}
| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version |
|-------------------------------------|--------------------|------------------------|---------------------------------------|-------------|
| Custom policies | Not supported | N/A | Not supported | N/A |
{{< /bootstrap-table >}}

Custom policies will be NGINX Gateway Fabric-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 Gateway Fabric-specific CRDs (Custom Resource Definitions) that will support features such as timeouts, load-balancing methods, authentication, etc. These important data-plane features are not part of the Gateway API specifications.

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 these CRDs are not part of the Gateway API, the mechanism to attach them to Gateway API resources is part of the Gateway API. See the [Policy Attachment documentation](https://gateway-api.sigs.k8s.io/references/policy-attachment/).