Restructure, reformat and rewrite API Compatibility Documentation (#1337

) Restructure, reformat and rewrite API Compatibility Documentation This commit makes a few changes to increase readability: - The table format from the summary is re-used for individual resources - The order of resources is changed to match the API specification - Capilisation and other style concerns have been standardised - Text has been rewritten for conciseness where possible I considered linking to the API specification sections to match the resources, but I noticed that they were versioned, which could possibly create issues for us in managing drift.
nginxinc · Dec 7, 2023 · 041f24f · 041f24f
1 parent 21a2507
commit 041f24f
Showing 1 changed file with 138 additions and 111 deletions.
diff --git a/site/content/overview/gateway-api-compatibility.md b/site/content/overview/gateway-api-compatibility.md
@@ -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.
@@ -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`
@@ -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:
 
@@ -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/).