diff --git a/content/ngf/get-started.md b/content/ngf/get-started.md index beb65dcb7f..2d0094c073 100644 --- a/content/ngf/get-started.md +++ b/content/ngf/get-started.md @@ -215,7 +215,7 @@ service/tea created Verify that the new pods are in the `default` namespace: ```shell -kubectl -n default get pods +kubectl get pods ``` ```text @@ -252,7 +252,7 @@ gateway.gateway.networking.k8s.io/gateway created Verify that the NGINX deployment has been provisioned: ```shell -kubectl -n default get pods +kubectl get pods ``` ```text @@ -317,7 +317,7 @@ httproute.gateway.networking.k8s.io/tea created You can check that all of the expected services are available using `kubectl get`: ```shell -kubectl -n default get services +kubectl get services ``` ```text @@ -331,7 +331,7 @@ tea ClusterIP 10.96.43.183 80/TCP 2m2s You can also use `kubectl describe` on the new resources to check their status: ```shell -kubectl -n default describe httproutes +kubectl describe httproutes ``` ```text @@ -446,7 +446,7 @@ Events: ``` ```shell -kubectl -n default describe gateways +kubectl describe gateways ``` ```text diff --git a/content/ngf/how-to/gateway-api-inference-extension.md b/content/ngf/how-to/gateway-api-inference-extension.md index fa3db52725..5836b98c1c 100644 --- a/content/ngf/how-to/gateway-api-inference-extension.md +++ b/content/ngf/how-to/gateway-api-inference-extension.md @@ -103,10 +103,30 @@ EOF Confirm that the Gateway was assigned an IP address and reports a `Programmed=True` status: ```shell -kubectl describe gateway inference-gateway +kubectl describe gateways.gateway.networking.k8s.io inference-gateway ``` -Save the public IP address and port of the NGINX Service into shell variables: +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/monitoring/tracing.md b/content/ngf/monitoring/tracing.md index 6ad4d62ffc..5a3d7e3830 100644 --- a/content/ngf/monitoring/tracing.md +++ b/content/ngf/monitoring/tracing.md @@ -244,9 +244,35 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io cafe +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/overview/custom-policies.md b/content/ngf/overview/custom-policies.md index 7d904fdaf3..6f1c7cb2a3 100644 --- a/content/ngf/overview/custom-policies.md +++ b/content/ngf/overview/custom-policies.md @@ -137,7 +137,7 @@ NGINX Gateway Fabric sets the [PolicyStatus](https://gateway-api.sigs.k8s.io/ref To check the status of a policy, use `kubectl describe`. This example checks the status of the `foo` ObservabilityPolicy, which is accepted: ```shell -kubectl describe observabilitypolicies.gateway.nginx.org foo -n default +kubectl describe observabilitypolicies.gateway.nginx.org foo ``` ```text diff --git a/content/ngf/overview/gateway-api-compatibility.md b/content/ngf/overview/gateway-api-compatibility.md index 33e2dd2604..9fa0741091 100644 --- a/content/ngf/overview/gateway-api-compatibility.md +++ b/content/ngf/overview/gateway-api-compatibility.md @@ -20,8 +20,8 @@ Learn which Gateway API resources NGINX Gateway Fabric supports and to which lev | [GRPCRoute](#grpcroute) | Supported | Partially supported | Not supported | v1 | Standard | | [ReferenceGrant](#referencegrant) | Supported | N/A | Not supported | v1beta1 | Standard | | [TLSRoute](#tlsroute) | Supported | Not supported | Not supported | v1alpha2 | Experimental | -| [TCPRoute](#tcproute) | Not supported | Not supported | Not supported | v1alpha2 | Experimental | -| [UDPRoute](#udproute) | Not supported | Not supported | Not supported | v1alpha2 | Experimental | +| [TCPRoute](#tcproute) | Supported | Supported | Not supported | v1alpha2 | Experimental | +| [UDPRoute](#udproute) | Supported | Supported | Not supported | v1alpha2 | Experimental | | [BackendTLSPolicy](#backendtlspolicy) | Partially Supported | Supported | Partially supported | v1 | Standard | | [Custom policies](#custom-policies) | N/A | N/A | Supported | N/A | N/A | {{< /table >}} @@ -310,7 +310,7 @@ Fields: {{< table >}} | Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | |----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| TCPRoute | Not supported | Not supported | Not supported | v1alpha2 | Experimental | +| TCPRoute | Supported | Supported | Not supported | v1alpha2 | Experimental | {{< /table >}} ### UDPRoute @@ -318,7 +318,7 @@ Fields: {{< table >}} | Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | |----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| UDPRoute | Not supported | Not supported | Not supported | v1alpha2 | Experimental | +| UDPRoute | Supported | Supported | Not supported | v1alpha2 | Experimental | {{< /table >}} ### BackendTLSPolicy diff --git a/content/ngf/traffic-management/advanced-routing.md b/content/ngf/traffic-management/advanced-routing.md index cca1e83da5..b8c6300c16 100644 --- a/content/ngf/traffic-management/advanced-routing.md +++ b/content/ngf/traffic-management/advanced-routing.md @@ -89,9 +89,35 @@ EOF ``` This gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames. -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io cafe +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III @@ -386,7 +412,7 @@ This will result in a `404 Not Found` response since `/coffee/123` does not matc If you have any issues while sending traffic, try the following to debug your configuration and setup: -- Make sure you set the shell variables $GW_IP and $GW_PORT to the public IP and port of the NGINX service. Refer to the [Installation]({{< ref "/ngf/install/" >}}) guides for more information. +- Make sure you set the shell variables ${GW_IP} and ${GW_PORT} to the public IP and port of the NGINX service. Refer to the [Installation]({{< ref "/ngf/install/" >}}) guides for more information. - Check the status of the Gateway: diff --git a/content/ngf/traffic-management/basic-routing.md b/content/ngf/traffic-management/basic-routing.md index 58be430bd4..c416048d68 100644 --- a/content/ngf/traffic-management/basic-routing.md +++ b/content/ngf/traffic-management/basic-routing.md @@ -223,14 +223,40 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io cafe +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` {{< call-out "note" >}} @@ -438,7 +464,7 @@ If you have any issues while testing the configuration, try the following to deb - Check the generated nginx config: ```shell - kubectl exec -it -n -- nginx -T + kubectl exec -it deployments/cafe-nginx -- nginx -T ``` The config should contain a server block with the server name "cafe.example.com" that listens on port 80. This server block should have a single location `/` that proxy passes to the coffee upstream: diff --git a/content/ngf/traffic-management/client-settings.md b/content/ngf/traffic-management/client-settings.md index 20bdf9d0e3..f01767d604 100644 --- a/content/ngf/traffic-management/client-settings.md +++ b/content/ngf/traffic-management/client-settings.md @@ -56,7 +56,32 @@ Create HTTPRoutes for the coffee and tea applications: kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/httproutes.yaml ``` -Save the public IP address and port of the NGINX Service into shell variables: +Verify the gateway is created: + +```shell +kubectl describe gateways.gateway.networking.k8s.io gateway +``` + +Verify the status is `Accepted`: + +```text +Status: + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/traffic-management/https-termination.md b/content/ngf/traffic-management/https-termination.md index e8d8b08429..d735762c7b 100644 --- a/content/ngf/traffic-management/https-termination.md +++ b/content/ngf/traffic-management/https-termination.md @@ -154,15 +154,41 @@ This gateway configures: - `http` listener for HTTP traffic - `https` listener for HTTPS traffic. It terminates TLS connections using the `cafe-secret` we created. -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and ports of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io cafe +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +- Save the public IP address and port(s) of the Gateway into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_HTTP_PORT= - GW_HTTPS_PORT= - ``` + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_HTTP_PORT= + GW_HTTPS_PORT= + ``` {{< call-out "note" >}} diff --git a/content/ngf/traffic-management/mirror.md b/content/ngf/traffic-management/mirror.md index c9bde4cf89..ae40a45462 100644 --- a/content/ngf/traffic-management/mirror.md +++ b/content/ngf/traffic-management/mirror.md @@ -133,9 +133,35 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io cafe +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/traffic-management/redirects-and-rewrites.md b/content/ngf/traffic-management/redirects-and-rewrites.md index 58c9e15f95..ea5c8ec18e 100644 --- a/content/ngf/traffic-management/redirects-and-rewrites.md +++ b/content/ngf/traffic-management/redirects-and-rewrites.md @@ -44,9 +44,35 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io gateway +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/traffic-management/request-response-headers.md b/content/ngf/traffic-management/request-response-headers.md index 225cfc8e2d..c5a209bca6 100644 --- a/content/ngf/traffic-management/request-response-headers.md +++ b/content/ngf/traffic-management/request-response-headers.md @@ -42,9 +42,35 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io gateway +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/traffic-management/session-persistence.md b/content/ngf/traffic-management/session-persistence.md index 19c681d6ee..f228dbd59e 100644 --- a/content/ngf/traffic-management/session-persistence.md +++ b/content/ngf/traffic-management/session-persistence.md @@ -145,7 +145,7 @@ EOF This creates three Service resources and multiple Pods in the default namespace. The multiple replicas are needed to demonstrate stickiness to backend Pods. ```shell -kubectl get all -o wide -n default +kubectl get all -o wide ``` ```text @@ -184,27 +184,38 @@ EOF After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: ```shell -kubectl get gateways.gateway.networking.k8s.io gateway +kubectl describe gateways.gateway.networking.k8s.io gateway ``` +Verify the status is `Accepted`: + ```text -NAME CLASS ADDRESS PROGRAMMED AGE -gateway nginx 10.96.15.149 True 23h +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed ``` -Save the public IP address and port of the NGINX Service into shell variables: +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III GW_PORT= ``` -Lookup the name of the NGINX pod and save into shell variable: - -```text -NGINX_POD_NAME= -``` - {{< call-out "note" >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /call-out >}} ## Session Persistence Methods @@ -310,7 +321,7 @@ Status: Next, verify that the policy has been applied to the `coffee` upstream by inspecting the NGINX configuration: ```shell -kubectl exec -it -n $NGINX_POD_NAME -- nginx -T +kubectl exec -it deployments/gateway-nginx -- nginx -T ``` You should see the `ip_hash` directive on the `coffee` upstream: @@ -416,7 +427,7 @@ Status: Next, verify that the tea upstream has a sticky cookie directive configured, which is responsible for issuing the session cookie and its attributes. The `sticky cookie` directive’s attributes are derived from the `sessionPersistence` configuration, such as the expiry (24h) and the route path (`/tea`). Inspect the NGINX configuration with: ```shell -kubectl exec -it -n $NGINX_POD_NAME -- nginx -T +kubectl exec -it deployments/gateway-nginx -- nginx -T ``` ```text @@ -514,7 +525,7 @@ EOF Verify the NGINX configuration: ```shell -kubectl exec -it -n $NGINX_POD_NAME -- nginx -T +kubectl exec -it deployments/gateway -- nginx -T ``` ```text diff --git a/content/ngf/traffic-management/snippets.md b/content/ngf/traffic-management/snippets.md index c84b9294e8..f504eee461 100644 --- a/content/ngf/traffic-management/snippets.md +++ b/content/ngf/traffic-management/snippets.md @@ -68,12 +68,38 @@ We have outlined a few best practices to keep in mind when using `SnippetsFilter kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/snippets-filter/gateway.yaml ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -- Save the public IP address and port of the NGINX Service into shell variables: + ```shell + kubectl describe gateways.gateway.networking.k8s.io gateway + ``` + + Verify the status is `Accepted`: + + ```text + Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed + ``` + + Save the public IP address and port(s) of the Gateway into shell variables: ```text - GW_IP= + GW_IP=XXX.YYY.ZZZ.III GW_PORT= ``` diff --git a/content/ngf/traffic-management/tcp-routing.md b/content/ngf/traffic-management/tcp-routing.md new file mode 100644 index 0000000000..2bdcca287e --- /dev/null +++ b/content/ngf/traffic-management/tcp-routing.md @@ -0,0 +1,299 @@ +--- +title: TCPRoute +weight: 1100 +toc: true +nd-content-type: how-to +nd-product: FABRIC +nd-docs: DOCS-0000 +--- + +Learn how to configure a TCPRoute to establish a TCP connection between NGINX Gateway Fabric and the backend applications. + +## Overview + +TCPRoute is a Gateway API resource that is used to configure routing for TCP connections. When attached to a Gateway listener, it forwards connections arriving on the listener’s port to one or more backend Services. In this guide, you will configure two TCPRoutes for **coffee** and **tea** applications, and see how listeners are attached to backends to route TCP traffic. + +## Note on Gateway API Experimental Features + +{{< call-out "important" >}} TCPRoute is a Gateway API resource from the experimental release channel. {{< /call-out >}} + +{{< include "/ngf/installation/install-gateway-api-experimental-features.md" >}} + +## Before you begin + +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric with experimental features enabled. + +## Setup + +Create two simple applications `coffee` and `tea` by copying and pasting the following block into your terminal: + +```yaml +kubectl apply -f - < 81/TCP 3m1s +service/tea ClusterIP 10.96.16.136 82/TCP 3m1s +``` + +Create a Gateway with two TCP listeners: + +```yaml +kubectl apply -f - < +GW_PORT_2= +``` + +{{< call-out "note" >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /call-out >}} + +Create TCPRoutes for routing to `coffee` and `tea` applications: + +```yaml +kubectl apply -f - <}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /call-out >}} + +Send requests to Gateway on different ports and observe which server the response comes from: + +```shell +curl -i http://${GW_IP}:${GW_PORT_1} +``` + +```text +Server address: 10.244.0.81:8080 +Server name: coffee-5b9c74f9d9-brlsx +``` + +```shell +curl -i http://${GW_IP}:${GW_PORT_2} +``` + +```text +Server address: 10.244.0.82:8080 +Server name: tea-859766c68c-scndk +``` + +Requests sent to port `${GW_PORT_1}` (listener `coffee`) are served by the coffee Service, and requests sent to port `${GW_PORT_2}` (listener `tea`) are served by the tea Service. + +## Further Readings + +- [TCPRoute](https://gateway-api.sigs.k8s.io/reference/spec/#tcproute) diff --git a/content/ngf/traffic-management/tls-passthrough.md b/content/ngf/traffic-management/tls-passthrough.md index 663c1ed214..1ed9cd1f3f 100644 --- a/content/ngf/traffic-management/tls-passthrough.md +++ b/content/ngf/traffic-management/tls-passthrough.md @@ -155,9 +155,35 @@ This Gateway will configure NGINX Gateway Fabric to accept TLS connections on po {{< call-out "note" >}}It is possible to add an HTTPS listener on the same port that terminates TLS connections so long as the hostname does not overlap with the TLS listener hostname.{{< /call-out >}} -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io gateway +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/traffic-management/udp-routing.md b/content/ngf/traffic-management/udp-routing.md new file mode 100644 index 0000000000..649e1f2b47 --- /dev/null +++ b/content/ngf/traffic-management/udp-routing.md @@ -0,0 +1,297 @@ +--- +title: UDPRoute +weight: 1200 +toc: true +nd-content-type: how-to +nd-product: FABRIC +nd-docs: DOCS-0000 +--- + +Learn how to configure a UDPRoute to handle a UDP connection between NGINX Gateway Fabric and the backend applications. + +## Overview + +UDPRoute enables you to expose and route UDP traffic through a Gateway. In this guide, you’ll configure a Gateway with a UDP listener and attach a UDPRoute to it. The listener defines the external UDP port, and the UDPRoute specifies the backend services; packets arriving on the listener’s port are forwarded to the backend applications. + +## Note on Gateway API Experimental Features + +{{< call-out "important" >}} UDPRoute is a Gateway API resource from the experimental release channel. {{< /call-out >}} + +{{< include "/ngf/installation/install-gateway-api-experimental-features.md" >}} + +## Before you begin + +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric with experimental features enabled. + +## Setup + +Create a simple application `coredns` by copying and pasting the following block into your terminal: + +```yaml +kubectl apply -f - < 53/UDP 13m +``` + +Create a Gateway with UDP listener: + +```yaml +kubectl apply -f - < +``` + +{{< call-out "note" >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /call-out >}} + +Create UDPRoute for routing to `coredns` application: + +```yaml +kubectl apply -f - <> DiG 9.10.6 <<>> ${GW_IP} 53 cafe.example.com +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 13260 +;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1 + +;; OPT PSEUDOSECTION: +; EDNS: version: 0, flags:; udp: 4096 +;; QUESTION SECTION: +;localhost. IN A + +;; ANSWER SECTION: +localhost. 600 IN A 127.0.0.1 + +;; Query time: 136 msec +;; SERVER: 192.168.72.180#53(192.168.72.180) +;; WHEN: Thu Jan 08 21:44:46 MST 2026 +;; MSG SIZE rcvd: 54 + +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: SERVFAIL, id: 32036 +;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 1 + +;; OPT PSEUDOSECTION: +; EDNS: version: 0, flags:; udp: 4096 +;; QUESTION SECTION: +;53. IN A + +;; Query time: 141 msec +;; SERVER: 192.168.72.180#53(192.168.72.180) +;; WHEN: Thu Jan 08 21:44:47 MST 2026 +;; MSG SIZE rcvd: 31 + +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 16210 +;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1 + +;; OPT PSEUDOSECTION: +; EDNS: version: 0, flags:; udp: 4096 +;; QUESTION SECTION: +;cafe.example.com. IN A + +;; AUTHORITY SECTION: +example.com. 900 IN SOA elliott.ns.cloudflare.com. dns.cloudflare.com. 2393120882 10000 2400 604800 1800 + +;; Query time: 159 msec +;; SERVER: 192.168.72.180#53(192.168.72.180) +;; WHEN: Thu Jan 08 21:44:47 MST 2026 +;; MSG SIZE rcvd: 107 +``` + +## Further Readings + +- [UDPRoute](https://gateway-api.sigs.k8s.io/reference/spec/#udproute) \ No newline at end of file diff --git a/content/ngf/traffic-management/upstream-settings.md b/content/ngf/traffic-management/upstream-settings.md index 6e7078fe53..77103787a0 100644 --- a/content/ngf/traffic-management/upstream-settings.md +++ b/content/ngf/traffic-management/upstream-settings.md @@ -120,7 +120,7 @@ EOF This will create two services and pods in the default namespace: ```shell -kubectl get svc,pod -n default +kubectl get svc,pod ``` ```text @@ -151,19 +151,39 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io gateway +``` + +Verify the status is `Accepted`: ```text -GW_IP=XXX.YYY.ZZZ.III -GW_PORT= +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed ``` -Lookup the name of the NGINX pod and save into shell variable: +Save the public IP address and port(s) of the Gateway into shell variables: ```text -NGINX_POD_NAME= +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= ``` {{< call-out "note" >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /call-out >}} @@ -314,7 +334,7 @@ The `lb-method-hash` policy should show the same `Accepted` condition. Next, verify that the policies have been applied to the `coffee` and `tea` upstreams by inspecting the NGINX configuration: ```shell -kubectl exec -it -n $NGINX_POD_NAME -- nginx -T +kubectl exec -it deployments/gateway-nginx -- nginx -T ``` You should see the `random two least_time=header` directive on the `coffee` upstreams and `hash $upstream_addr consistent` in the `tea` upstream: @@ -394,7 +414,7 @@ Events: Next, verify that the policy has been applied to the `coffee` and `tea` upstreams by inspecting the NGINX configuration: ```shell -kubectl exec -it -n $NGINX_POD_NAME -- nginx -T +kubectl exec -it deployments/gateway-nginx -- nginx -T ``` You should see the `zone` directive in the `coffee` and `tea` upstreams both specify the size `1m`: @@ -471,7 +491,7 @@ Events: Next, verify that the policy has been applied to the `coffee` upstreams, by inspecting the NGINX configuration: ```shell -kubectl exec -it -n $NGINX_POD_NAME -- nginx -T +kubectl exec -it deployments/gateway-nginx -- nginx -T ``` You should see that the `coffee` upstream has the `keepalive` directive set to 32: @@ -533,7 +553,8 @@ Status: Next, verify that the policy has been applied to the `tea` upstream, by inspecting the NGINX configuration: ```shell -kubectl exec -it -n $NGINX_POD_NAME -- nginx -T +kubectl exec -it deployments/gateway-nginx -- nginx -T +``` ```text upstream default_tea_80 { diff --git a/content/ngf/traffic-security/secure-backend.md b/content/ngf/traffic-security/secure-backend.md index a885e2e3e5..a7769c60c2 100644 --- a/content/ngf/traffic-security/secure-backend.md +++ b/content/ngf/traffic-security/secure-backend.md @@ -258,9 +258,35 @@ spec: EOF ``` -After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created: -Save the public IP address and port of the NGINX Service into shell variables: +```shell +kubectl describe gateways.gateway.networking.k8s.io gateway +``` + +Verify the status is `Accepted`: + +```text +Status: + Addresses: + Type: IPAddress + Value: 10.96.36.219 + Conditions: + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is accepted + Observed Generation: 1 + Reason: Accepted + Status: True + Type: Accepted + Last Transition Time: 2026-01-09T05:40:37Z + Message: The Gateway is programmed + Observed Generation: 1 + Reason: Programmed + Status: True + Type: Programmed +``` + +Save the public IP address and port(s) of the Gateway into shell variables: ```text GW_IP=XXX.YYY.ZZZ.III diff --git a/content/ngf/troubleshooting.md b/content/ngf/troubleshooting.md index 3c5fe29140..147c1142e7 100644 --- a/content/ngf/troubleshooting.md +++ b/content/ngf/troubleshooting.md @@ -72,7 +72,7 @@ LAST SEEN TYPE REASON OBJECT Getting shell access to containers allows developers and operators to view the environment of a running container, see its logs or diagnose any problems. To get shell access to the NGINX container, use `kubectl exec`: ```shell -kubectl exec -it -n -- /bin/sh +kubectl exec -it -n -- /bin/sh ``` #### Logs