nginx · ciarams87 · Oct 22, 2025 · Sep 3, 2025 · Sep 15, 2025 · Sep 16, 2025
@@ -36,7 +36,10 @@ Gateway API features has three [support levels](https://gateway-api.sigs.k8s.io/
 - _Not supported_. The resource or field is not yet supported. It will become partially or fully supported in future
   releases.
 
-{{< call-out "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. {{< /call-out >}}
+{{< call-out "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. 
+
+Please note that while we make every effort to reflect the support status of experimental fields in our code and documentation, there may be instances where this is not explicitly 
+indicated. Support for such fields is provided on a best-effort basis.{{< /call-out >}}
 
 
 ## Resources
@@ -101,7 +104,9 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
       - `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.
+  - `addresses`: Valid IPAddresses will be added to the `externalIP` field in the related Services fronting NGINX. Users should ensure that the IP Family of the address matches the IP Family set in the NginxProxy resource (default is dual, meaning both IPv4 and IPv6), otherwise there may be networking issues.
+      - `type`: Partially supported. Allowed value: `IPAddress`.
+      - `value`: Partially supported. Dynamic address allocation when value is unspecified is not supported.
   - `backendTLS`: Not supported.
   - `allowedListeners`: Not supported.
 - `status`
@@ -114,6 +119,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
     - `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Gateway is invalid or not supported.
     - `Programmed/True/Programmed`
     - `Programmed/False/Invalid`
+    - `Accepted/True/UnsupportedField`: Custom reason for when the Gateway is accepted but contains an unsupported field
   - `listeners`
     - `name`: Supported.
     - `supportedKinds`: Supported.
@@ -146,7 +152,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
 **Fields**:
 
 - `spec`
-  - `parentRefs`: Partially supported. Port not supported.
+  - `parentRefs`: Supported.
   - `hostnames`: Supported.
   - `rules`
     - `matches`
@@ -163,6 +169,10 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
       - `requestMirror`: Supported. Multiple mirrors can be specified. Percent and fraction-based mirroring are supported.
       - `extensionRef`: Supported for SnippetsFilters.
     - `backendRefs`: Partially supported. Backend ref `filters` are not supported.
+    - `name`: Not supported.
+    - `timeouts`: Not supported.
+    - `retry`: Not supported.
+    - `sessionPersistence`: Not supported.
 - `status`
   - `parents`
     - `parentRef`: Supported.
@@ -183,6 +193,9 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
       - `ResolvedRefs/False/InvalidIPFamily`: Custom reason for when one of the HTTPRoute rules has a backendRef that has an invalid IPFamily.
       - `ResolvedRefs/False/UnsupportedProtocol`
       - `PartiallyInvalid/True/UnsupportedValue`
+      - `Accepted/True/UnsupportedField`: Custom reason for when the HTTPRouteRule is accepted but contains an unsupported field
+
+      {{< call-out "note" >}} If `name`, `timeouts`, `retry` or `sessionPersistence` are defined for a HTTPRoute rule, they will be ignored and rule still will be created. {{< /call-out >}}
 
 ### GRPCRoute
 
@@ -195,7 +208,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
 **Fields**:
 
 - `spec`
-  - `parentRefs`: Partially supported. Port not supported.
+  - `parentRefs`: Supported.
   - `hostnames`: Supported.
   - `rules`
     - `matches`
@@ -208,6 +221,8 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
       - `requestMirror`: Supported. Multiple mirrors can be specified.
       - `extensionRef`: Supported for SnippetsFilters.
     - `backendRefs`: Partially supported. Backend ref `filters` are not supported.
+    - `name`: Not supported.
+    - `sessionPersistence`: Not supported.
 - `status`
   - `parents`
     - `parentRef`: Supported.
@@ -225,6 +240,9 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
       - `ResolvedRefs/False/BackendNotFound`
       - `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the GRPCRoute rules has a backendRef with an unsupported value.
       - `PartiallyInvalid/True/UnsupportedValue`
+      - `Accepted/True/UnsupportedField`: Custom reason for when the GRPCRouteRule is accepted but contains an unsupported field
+
+{{< call-out "note" >}} If `name` or `sessionPersistence` are defined for a GRPCRoute rule, they will be ignored and rule still will be created. {{< /call-out >}}
 
 ### ReferenceGrant
 
@@ -257,7 +275,7 @@ Fields:
 **Fields**:
 
 - `spec`
-  - `parentRefs`: Partially supported. Port not supported.
+  - `parentRefs`: Supported.
   - `hostnames`: Supported.
   - `rules`
     - `backendRefs`: Partially supported. Only one backend ref allowed.

@@ -27,8 +27,9 @@ Telemetry data is collected once every 24 hours and sent to a service managed by
 - **Version:** the version of the NGINX Gateway Fabric Deployment.
 - **Deployment UID:** the UID of the NGINX Gateway Fabric Deployment.
 - **Image Build Source:** whether the image was built by GitHub or locally (values are `gha`, `local`, or `unknown`). The source repository of the images is **not** collected.
+- **Build OS:** the base operating system the image was built on (values are currently `alpine` or `ubi`). 
 - **Deployment Flags:** a list of NGINX Gateway Fabric Deployment flags that are specified by a user. The actual values of non-boolean flags are **not** collected; we only record that they are either `true` or `false` for boolean flags and `default` or `user-defined` for the rest.
-- **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected.
+- **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `InferencePool`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected.
 - **SnippetsFilters Info** a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected.
 - **Control Plane Pod Count** the count of NGINX Gateway Fabric Pods.
 - **Data Plane Pod Count** the count of NGINX data plane Pods.

@@ -899,6 +899,7 @@ longer necessary.</p>
 <a href="#gateway.nginx.org/v1alpha1.ClientKeepAlive">ClientKeepAlive</a>,
 <a href="#gateway.nginx.org/v1alpha1.ClientKeepAliveTimeout">ClientKeepAliveTimeout</a>,
 <a href="#gateway.nginx.org/v1alpha1.UpstreamKeepAlive">UpstreamKeepAlive</a>,
+<a href="#gateway.nginx.org/v1alpha2.DNSResolver">DNSResolver</a>,
 <a href="#gateway.nginx.org/v1alpha2.TelemetryExporter">TelemetryExporter</a>)
 </p>
 <p>
@@ -1869,6 +1870,21 @@ int32
 Default is 1024.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>dnsResolver</code><br/>
+<em>
+<a href="#gateway.nginx.org/v1alpha2.DNSResolver">
+DNSResolver
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DNSResolver specifies the DNS resolver configuration for external name resolution.
+This enables support for routing to ExternalName Services.</p>
+</td>
+</tr>
 </table>
 </td>
 </tr>
@@ -2245,6 +2261,155 @@ ReadinessProbeSpec
 </tr>
 </tbody>
 </table>
+<h3 id="gateway.nginx.org/v1alpha2.DNSResolver">DNSResolver
+<a class="headerlink" href="#gateway.nginx.org%2fv1alpha2.DNSResolver" title="Permanent link">¶</a>
+</h3>
+<p>
+(<em>Appears on: </em>
+<a href="#gateway.nginx.org/v1alpha2.NginxProxySpec">NginxProxySpec</a>)
+</p>
+<p>
+<p>DNSResolver specifies the DNS resolver configuration for NGINX.
+This enables dynamic DNS resolution for ExternalName Services.
+Corresponds to the NGINX resolver directive: <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver</a></p>
+</p>
+<table class="table table-bordered table-striped">
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>timeout</code><br/>
+<em>
+<a href="#gateway.nginx.org/v1alpha1.Duration">
+Duration
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Timeout specifies the timeout for name resolution.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>cacheTTL</code><br/>
+<em>
+<a href="#gateway.nginx.org/v1alpha1.Duration">
+Duration
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>CacheTTL specifies how long to cache DNS responses.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>disableIPv6</code><br/>
+<em>
+bool
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisableIPv6 disables IPv6 lookups.
+If not specified, or set to false, IPv6 lookups will be enabled.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>addresses</code><br/>
+<em>
+<a href="#gateway.nginx.org/v1alpha2.DNSResolverAddress">
+[]DNSResolverAddress
+</a>
+</em>
+</td>
+<td>
+<p>Addresses specifies the list of DNS server addresses.
+Each address can be an IP address or hostname.
+Example: [{&ldquo;type&rdquo;: &ldquo;IPAddress&rdquo;, &ldquo;value&rdquo;: &ldquo;8.8.8.8&rdquo;}, {&ldquo;type&rdquo;: &ldquo;Hostname&rdquo;, &ldquo;value&rdquo;: &ldquo;dns.google&rdquo;}]</p>
+</td>
+</tr>
+</tbody>
+</table>
+<h3 id="gateway.nginx.org/v1alpha2.DNSResolverAddress">DNSResolverAddress
+<a class="headerlink" href="#gateway.nginx.org%2fv1alpha2.DNSResolverAddress" title="Permanent link">¶</a>
+</h3>
+<p>
+(<em>Appears on: </em>
+<a href="#gateway.nginx.org/v1alpha2.DNSResolver">DNSResolver</a>)
+</p>
+<p>
+<p>DNSResolverAddress specifies the address type and value for a DNS resolver address.</p>
+</p>
+<table class="table table-bordered table-striped">
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>type</code><br/>
+<em>
+<a href="#gateway.nginx.org/v1alpha2.DNSResolverAddressType">
+DNSResolverAddressType
+</a>
+</em>
+</td>
+<td>
+<p>Type specifies the type of address.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>value</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Value specifies the address value.
+When Type is &ldquo;IPAddress&rdquo;, this must be a valid IPv4 or IPv6 address.
+When Type is &ldquo;Hostname&rdquo;, this must be a valid hostname.</p>
+</td>
+</tr>
+</tbody>
+</table>
+<h3 id="gateway.nginx.org/v1alpha2.DNSResolverAddressType">DNSResolverAddressType
+(<code>string</code> alias)</p><a class="headerlink" href="#gateway.nginx.org%2fv1alpha2.DNSResolverAddressType" title="Permanent link">¶</a>
+</h3>
+<p>
+(<em>Appears on: </em>
+<a href="#gateway.nginx.org/v1alpha2.DNSResolverAddress">DNSResolverAddress</a>)
+</p>
+<p>
+<p>DNSResolverAddressType specifies the type of DNS resolver address.</p>
+</p>
+<table class="table table-bordered table-striped">
+<thead>
+<tr>
+<th>Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr><td><p>&#34;Hostname&#34;</p></td>
+<td><p>DNSResolverHostnameType specifies that the address is a hostname.</p>
+</td>
+</tr><tr><td><p>&#34;IPAddress&#34;</p></td>
+<td><p>DNSResolverIPAddressType specifies that the address is an IP address.</p>
+</td>
+</tr></tbody>
+</table>
 <h3 id="gateway.nginx.org/v1alpha2.DaemonSetSpec">DaemonSetSpec
 <a class="headerlink" href="#gateway.nginx.org%2fv1alpha2.DaemonSetSpec" title="Permanent link">¶</a>
 </h3>
@@ -3041,6 +3206,21 @@ int32
 Default is 1024.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>dnsResolver</code><br/>
+<em>
+<a href="#gateway.nginx.org/v1alpha2.DNSResolver">
+DNSResolver
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DNSResolver specifies the DNS resolver configuration for external name resolution.
+This enables support for routing to ExternalName Services.</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="gateway.nginx.org/v1alpha2.NodePort">NodePort

@@ -50,6 +50,7 @@ This command runs the NGINX Gateway Fabric control plane.
 | _usage-report-skip-verify_          | _bool_   | Disable client verification of the NGINX Plus usage reporting server certificate.                                                                                                                                                                                                                                                                                                        |
 | _usage-report-ca-secret_               | _string_ | The name of the Secret containing the NGINX Instance Manager CA certificate. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway)                                                                                                                                                                                                                                                                                              |
 | _usage-report-client-ssl-secret_               | _string_ | The name of the Secret containing the client certificate and key for authenticating with NGINX Instance Manager. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway)                                                                                                                                                                                                                                                                                              |
+| _usage-report-enforce-initial-report_          | _bool_   | Enables or disables the 180-day grace period for sending the initial usage report.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | _snippets-filters_                  | _bool_   | Enable SnippetsFilters feature. SnippetsFilters allow inserting NGINX configuration into the generated NGINX config for HTTPRoute and GRPCRoute resources.                                                                                                                                                                                                                               |
 | _nginx-scc_                  | _string_   | The name of the SecurityContextConstraints to be used with the NGINX data plane Pods. Only applicable in OpenShift.                                                                                                                                                                                                                               |
 | _nginx-one-dataplane-key-secret_ | _string_ | The name of the secret which holds the dataplane key that is required to authenticate with the NGINX One Console. Secret must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). |