From c1db9e4a1189e0ec456ff3dbf071288b30f9f017 Mon Sep 17 00:00:00 2001 From: Benjamin Jee Date: Mon, 28 Apr 2025 10:43:38 -0700 Subject: [PATCH 1/2] Update documentation on accessing nginx container --- content/ngf/how-to/monitoring/dashboard.md | 4 +- content/ngf/how-to/monitoring/tracing.md | 16 ++- .../ngf/how-to/monitoring/troubleshooting.md | 122 ++++++++++++------ .../traffic-management/advanced-routing.md | 24 ++-- .../traffic-management/client-settings.md | 21 +-- .../traffic-management/https-termination.md | 29 ++--- .../redirects-and-rewrites.md | 24 ++-- .../request-response-headers.md | 20 +-- .../routing-traffic-to-your-app.md | 43 +++--- .../ngf/how-to/traffic-management/snippets.md | 25 ++-- .../traffic-management/tls-passthrough.md | 25 ++-- .../traffic-management/upstream-settings.md | 39 +++--- .../integrating-cert-manager.md | 2 +- .../securing-backend-traffic.md | 21 +-- .../installation/installing-ngf/manifests.md | 2 +- content/ngf/overview/nginx-plus.md | 2 +- 16 files changed, 249 insertions(+), 170 deletions(-) diff --git a/content/ngf/how-to/monitoring/dashboard.md b/content/ngf/how-to/monitoring/dashboard.md index fd16d9911..8019aa8a8 100644 --- a/content/ngf/how-to/monitoring/dashboard.md +++ b/content/ngf/how-to/monitoring/dashboard.md @@ -17,10 +17,10 @@ The NGINX Plus dashboard offers a real-time live activity monitoring interface t To access the dashboard: -1. Use port-forwarding to forward connections to port 8765 on your local machine to port 8765 on the NGINX Gateway Fabric pod (replace `` with the actual name of the pod). +1. Use port-forwarding to forward connections to port 8765 on your local machine to port 8765 on the NGINX Plus pod (replace `` with the actual name of the pod). ```shell - kubectl port-forward 8765:8765 -n nginx-gateway + kubectl port-forward 8765:8765 -n ``` 1. Open your browser to [http://127.0.0.1:8765/dashboard.html](http://127.0.0.1:8765/dashboard.html) to access the dashboard. diff --git a/content/ngf/how-to/monitoring/tracing.md b/content/ngf/how-to/monitoring/tracing.md index 34a0dfc60..db711b128 100644 --- a/content/ngf/how-to/monitoring/tracing.md +++ b/content/ngf/how-to/monitoring/tracing.md @@ -170,13 +170,6 @@ If you already have NGINX Gateway Fabric installed, then you can create the `Ngi kubectl edit gatewayclasses.gateway.networking.k8s.io nginx ``` -Save the public IP address and port of NGINX Gateway Fabric into shell variables: - -```text -GW_IP=XXX.YYY.ZZZ.III -GW_PORT= -``` - You can now create the application, route, and tracing policy. --- @@ -257,6 +250,15 @@ spec: EOF ``` +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service into shell variables: + +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` + Check that traffic can flow to the application. {{< note >}} If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve. {{< /note >}} diff --git a/content/ngf/how-to/monitoring/troubleshooting.md b/content/ngf/how-to/monitoring/troubleshooting.md index 4f8cf1e4f..009e64abc 100644 --- a/content/ngf/how-to/monitoring/troubleshooting.md +++ b/content/ngf/how-to/monitoring/troubleshooting.md @@ -80,7 +80,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 nginx-gateway -c nginx -- /bin/sh +kubectl exec -it -n -- /bin/sh ``` --- @@ -104,7 +104,7 @@ You can see logs for a crashed or killed container by adding the `-p` flag to th To see logs for the data plane container: ```shell - kubectl -n nginx-gateway logs -c nginx + kubectl -n logs -c nginx ``` 1. Error Logs @@ -118,13 +118,13 @@ You can see logs for a crashed or killed container by adding the `-p` flag to th For the _nginx_ container you can `grep` for various [error](https://nginx.org/en/docs/ngx_core_module.html#error_log) logs. For example, to search for all logs logged at the `emerg` level: ```shell - kubectl -n nginx-gateway logs -c nginx | grep emerg + kubectl -n logs -c nginx | grep emerg ``` For example, if a variable is too long, NGINX may display such an error message: ```text - kubectl logs -n nginx-gateway ngf-nginx-gateway-fabric-bb8598998-jwk2m -c nginx | grep emerg + kubectl logs -n dev-env gateway-nginx-bb8598998-jwk2m -c nginx | grep emerg 2024/06/13 20:04:17 [emerg] 27#27: too long parameter, probably missing terminating """ character in /etc/nginx/conf.d/http.conf:78 ``` @@ -158,7 +158,7 @@ server { } ``` -Once a HTTPRoute with path matches and rules are defined, nginx.conf is updated accordingly to determine which location block will manage incoming requests. To demonstrate how `nginx.conf` is changed, create some resources: +Once an HTTPRoute with path matches and rules are defined, nginx.conf is updated accordingly to determine which location block will manage incoming requests. To demonstrate how `nginx.conf` is changed, create some resources: 1. A Gateway with single listener with the hostname `*.example.com` on port 80. 2. A simple `coffee` application. @@ -290,10 +290,6 @@ The configuration may change in future releases. This configuration is valid for Metrics can be useful to identify performance bottlenecks and pinpoint areas of high resource consumption within NGINX Gateway Fabric. To set up metrics collection, refer to the [Prometheus Metrics guide]({{< ref "prometheus.md" >}}). The metrics dashboard will help you understand problems with the way NGINX Gateway Fabric is set up or potential issues that could show up with time. -For example, metrics `nginx_reloads_total` and `nginx_reload_errors_total` offer valuable insights into the system's stability and reliability. A high `nginx_reloads_total` value indicates frequent updates or configuration changes, while a high `nginx_reload_errors_total` value suggests issues with the configuration or other problems preventing successful reloads. Monitoring these metrics helps identify and resolve configuration errors, ensuring consistent service reliability. - -In such situations, it's advisable to review the logs of both NGINX and NGINX Gateway containers for any potential error messages. Additionally, verify the configured resources to ensure they are in a valid state. - --- #### Access the NGINX Plus Dashboard @@ -336,46 +332,100 @@ To understand why the NGINX Gateway Fabric Pod has not started running or is not kubectl describe pod -n nginx-gateway ``` -The Pod description includes details about the image name, tags, current status, and environment variables. Verify that these details match your setup and cross-check with the events to ensure everything is functioning as expected. For example, the Pod below has two containers that are running and the events reflect the same. +The Pod description includes details about the image name, tags, current status, and environment variables. Verify that these details match your setup and cross-check with the events to ensure everything is functioning as expected. For example, the Pod below has the nginx-gateway container that is running and the events reflect the same. ```text Containers: nginx-gateway: - Container ID: containerd://06c97a9de938b35049b7c63e251418395aef65dd1ff996119362212708b79cab - Image: nginx-gateway-fabric - Image ID: docker.io/library/import-2024-06-13@sha256:1460d63bd8a352a6e455884d7ebf51ce9c92c512cb43b13e44a1c3e3e6a08918 - Ports: 9113/TCP, 8081/TCP - Host Ports: 0/TCP, 0/TCP + Container ID: containerd://492f380d5919ae2cdca0e009e7a7d5bf4092f8e1910f52d8951d58b73f125646 + Image: nginx-gateway-fabric:latest + Image ID: sha256:c034f1e5bde0490b1f2441e0e9b0bcfce5f2e259bb6210c55d4d67f808a74ecb + Ports: 8443/TCP, 9113/TCP, 8081/TCP + Host Ports: 0/TCP, 0/TCP, 0/TCP + SeccompProfile: RuntimeDefault + Args: + controller + --gateway-ctlr-name=gateway.nginx.org/nginx-gateway-controller + --gatewayclass=nginx + --config=my-release-config + --service=my-release-nginx-gateway-fabric + --agent-tls-secret=agent-tls + --metrics-port=9113 + --health-port=8081 + --leader-election-lock-name=my-release-nginx-gateway-fabric-leader-election State: Running - Started: Thu, 13 Jun 2024 11:47:46 -0600 + Started: Thu, 24 Apr 2025 10:57:16 -0700 Ready: True Restart Count: 0 Readiness: http-get http://:health/readyz delay=3s timeout=1s period=1s #success=1 #failure=3 Environment: - POD_IP: (v1:status.podIP) POD_NAMESPACE: nginx-gateway (v1:metadata.namespace) - POD_NAME: ngf-nginx-gateway-fabric-66dd665756-zh7d7 (v1:metadata.name) - nginx: - Container ID: containerd://c2f3684fd8922e4fac7d5707ab4eb5f49b1f76a48893852c9a812cd6dbaa2f55 - Image: nginx-gateway-fabric/nginx - Image ID: docker.io/library/import-2024-06-13@sha256:c9a02cb5665c6218373f8f65fc2c730f018d0ca652ae827cc913a7c6e9db6f45 - Ports: 80/TCP, 443/TCP - Host Ports: 0/TCP, 0/TCP - State: Running - Started: Thu, 13 Jun 2024 11:47:46 -0600 - Ready: True - Restart Count: 0 - Environment: + POD_NAME: my-release-nginx-gateway-fabric-b99bd5cdd-qzp5q (v1:metadata.name) + POD_UID: (v1:metadata.uid) + INSTANCE_NAME: (v1:metadata.labels['app.kubernetes.io/instance']) + IMAGE_NAME: nginx-gateway-fabric:latest + Mounts: + /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-5dg45 (ro) + /var/run/secrets/ngf from nginx-agent-tls (rw) Events: Type Reason Age From Message ---- ------ ---- ---- ------- - Normal Scheduled 40s default-scheduler Successfully assigned nginx-gateway/ngf-nginx-gateway-fabric-66dd665756-zh7d7 to kind-control-plane - Normal Pulled 40s kubelet Container image "nginx-gateway-fabric" already present on machine - Normal Created 40s kubelet Created container nginx-gateway - Normal Started 39s kubelet Started container nginx-gateway - Normal Pulled 39s kubelet Container image "nginx-gateway-fabric/nginx" already present on machine - Normal Created 39s kubelet Created container nginx - Normal Started 39s kubelet Started container nginx + Normal Scheduled 22s default-scheduler Successfully assigned nginx-gateway/my-release-nginx-gateway-fabric-b99bd5cdd-qzp5q to kind-control-plane + Normal Pulled 20s kubelet Container image "nginx-gateway-fabric:latest" already present on machine + Normal Created 20s kubelet Created container: nginx-gateway + Normal Started 20s kubelet Started container nginx-gateway +``` + +--- + +##### NGINX Pod is not running or ready + +To understand why the NGINX Pod has not started running or is not ready, check the state of the Pod to get detailed information about the current status and events happening in the Pod. To do this, use `kubectl describe`: + +```shell +kubectl describe pod -n +``` + +The Pod description includes details about the image name, tags, current status, and environment variables. Verify that these details match your setup and cross-check with the events to ensure everything is functioning as expected. For example, the Pod below has the nginx container that is running and the events reflect the same. + +```text +Containers: + nginx: + Container ID: containerd://0dd33fd358ba3b369de315be15b197e369342aba7aa8d3ea12e4455823fa90ce + Image: nginx-gateway-fabric/nginx:latest + Image ID: sha256:e5cb19bab49cbde6222df607a0946e1e00c1af767263b79ae36e4c69f8547f20 + Ports: 80/TCP, 9113/TCP + Host Ports: 0/TCP, 0/TCP + SeccompProfile: RuntimeDefault + State: Running + Started: Thu, 24 Apr 2025 10:57:36 -0700 + Ready: True + Restart Count: 0 + Environment: + Mounts: + /etc/nginx-agent from nginx-agent (rw) + /etc/nginx/conf.d from nginx-conf (rw) + /etc/nginx/includes from nginx-includes (rw) + /etc/nginx/main-includes from nginx-main-includes (rw) + /etc/nginx/secrets from nginx-secrets (rw) + /etc/nginx/stream-conf.d from nginx-stream-conf (rw) + /var/cache/nginx from nginx-cache (rw) + /var/lib/nginx-agent from nginx-agent-lib (rw) + /var/log/nginx-agent from nginx-agent-log (rw) + /var/run/nginx from nginx-run (rw) + /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-f9kph (ro) + /var/run/secrets/ngf from nginx-agent-tls (rw) + /var/run/secrets/ngf/serviceaccount from token (rw) +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Scheduled 2m57s default-scheduler Successfully assigned default/gateway-nginx-85f7f6d7d-fx7q2 to kind-control-plane + Normal Pulled 2m54s kubelet Container image "nginx-gateway-fabric:latest" already present on machine + Normal Created 2m54s kubelet Created container: init + Normal Started 2m54s kubelet Started container init + Normal Pulled 2m53s kubelet Container image "nginx-gateway-fabric/nginx:latest" already present on machine + Normal Created 2m53s kubelet Created container: nginx + Normal Started 2m53s kubelet Started container nginx ``` --- diff --git a/content/ngf/how-to/traffic-management/advanced-routing.md b/content/ngf/how-to/traffic-management/advanced-routing.md index 1ca8e61ce..2709961e0 100644 --- a/content/ngf/how-to/traffic-management/advanced-routing.md +++ b/content/ngf/how-to/traffic-management/advanced-routing.md @@ -26,14 +26,6 @@ The goal is to create a set of rules that will result in client requests being s ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< 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. {{< /note >}} --- @@ -69,6 +61,16 @@ 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. + +Save the public IP address and port of the NGINX Service into shell variables: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` + +{{< 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.{{< /note >}} The [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) is typically deployed by the [application developer](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the `coffee` HTTPRoute: @@ -154,7 +156,7 @@ This HTTPRoute has a few important properties: ### Send traffic to Coffee -Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our coffee applications. +Using the external IP address and port for the NGINX Service, we can send traffic to our coffee applications. {{< note >}} If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve. {{< /note >}} @@ -269,7 +271,7 @@ The properties of this HTTPRoute include: ### Send traffic to Tea -Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our tea applications. +Using the external IP address and port for the NGINX Service, we can send traffic to our tea applications. {{< note >}} If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve. {{< /note >}} @@ -303,7 +305,7 @@ This request should receive a response from the `tea-post` pod. Any other type o 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 Gateway Fabric service. Refer to the [Installation]({{< ref "/ngf/installation/" >}}) 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/installation/" >}}) guides for more information. - Check the status of the Gateway: diff --git a/content/ngf/how-to/traffic-management/client-settings.md b/content/ngf/how-to/traffic-management/client-settings.md index 5ccc454cd..518f01bcc 100644 --- a/content/ngf/how-to/traffic-management/client-settings.md +++ b/content/ngf/how-to/traffic-management/client-settings.md @@ -39,14 +39,6 @@ For all the possible configuration options for `ClientSettingsPolicy`, see the [ ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - - {{< 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.{{< /note >}} - Create the coffee and tea example applications: @@ -59,6 +51,7 @@ For all the possible configuration options for `ClientSettingsPolicy`, see the [ ```yaml kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/gateway.yaml ``` +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. - Create HTTPRoutes for the coffee and tea applications: @@ -66,9 +59,19 @@ For all the possible configuration options for `ClientSettingsPolicy`, see the [ 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: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` + + {{< 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.{{< /note >}} + + - Test the configuration: - You can send traffic to the coffee and tea applications using the external IP address and port for NGINX Gateway Fabric. + You can send traffic to the coffee and tea applications using the external IP address and port for the NGINX Service. Send a request to coffee: diff --git a/content/ngf/how-to/traffic-management/https-termination.md b/content/ngf/how-to/traffic-management/https-termination.md index bc4253098..7d6e4da62 100644 --- a/content/ngf/how-to/traffic-management/https-termination.md +++ b/content/ngf/how-to/traffic-management/https-termination.md @@ -20,21 +20,6 @@ In this guide, we will show how to configure HTTPS termination for your applicat ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - - Save the ports of NGINX Gateway Fabric: - - ```text - GW_HTTP_PORT= - GW_HTTPS_PORT= - ``` - -{{< 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.{{< /note >}} --- @@ -175,6 +160,18 @@ 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. + +Save the public IP address and ports of the NGINX Service into shell variables: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_HTTP_PORT= + GW_HTTPS_PORT= + ``` + +{{< 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.{{< /note >}} + To create the httproute resources, copy and paste the following into your terminal: ```yaml @@ -223,7 +220,7 @@ The first route issues a `requestRedirect` from the `http` listener on port 80 t ## Send traffic -Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our coffee application. +Using the external IP address and ports for the NGINX Service, we can send traffic to our coffee application. {{< note >}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} diff --git a/content/ngf/how-to/traffic-management/redirects-and-rewrites.md b/content/ngf/how-to/traffic-management/redirects-and-rewrites.md index 9552d88f3..60df195f8 100644 --- a/content/ngf/how-to/traffic-management/redirects-and-rewrites.md +++ b/content/ngf/how-to/traffic-management/redirects-and-rewrites.md @@ -24,14 +24,6 @@ To see an example of a redirect using scheme and port, see the [HTTPS Terminatio ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< 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.{{< /note >}} --- @@ -60,6 +52,18 @@ spec: EOF ``` +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service into shell variables: + +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` + +{{< 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.{{< /note >}} + + --- ## URLRewrite example @@ -184,7 +188,7 @@ EOF ### Send traffic -Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our coffee application. +Using the external IP address and port for the NGINX Service, we can send traffic to our coffee application. {{< note >}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} @@ -431,7 +435,7 @@ EOF ### Send traffic -Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our tea and soda applications to verify the redirect is successful. We will use curl's `--include` option to print the response headers (we are interested in the `Location` header). +Using the external IP address and port for the NGINX Service, we can send traffic to our tea and soda applications to verify the redirect is successful. We will use curl's `--include` option to print the response headers (we are interested in the `Location` header). {{< note >}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} diff --git a/content/ngf/how-to/traffic-management/request-response-headers.md b/content/ngf/how-to/traffic-management/request-response-headers.md index c4820a46c..6d41a07d2 100644 --- a/content/ngf/how-to/traffic-management/request-response-headers.md +++ b/content/ngf/how-to/traffic-management/request-response-headers.md @@ -20,14 +20,6 @@ This guide describes how to configure the headers application to modify the head ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< 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 .{{< /note >}} --- @@ -56,6 +48,18 @@ spec: EOF ``` +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service into shell variables: + +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` + +{{< 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 .{{< /note >}} + + --- ## RequestHeaderModifier example diff --git a/content/ngf/how-to/traffic-management/routing-traffic-to-your-app.md b/content/ngf/how-to/traffic-management/routing-traffic-to-your-app.md index 8d405485d..904b21650 100644 --- a/content/ngf/how-to/traffic-management/routing-traffic-to-your-app.md +++ b/content/ngf/how-to/traffic-management/routing-traffic-to-your-app.md @@ -20,12 +20,6 @@ You can route traffic to your Kubernetes applications using the Gateway API and ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` --- @@ -106,19 +100,19 @@ service/coffee ClusterIP 198.51.100.1 80/TCP 77s ## Application architecture with NGINX Gateway Fabric -To route traffic to the **coffee** application, we will create a gateway and HTTPRoute. The following diagram shows the configuration we are creating in the next step: +To route traffic to the **coffee** application, we will create a Gateway and HTTPRoute. The following diagram shows the configuration we are creating in the next step: {{}} -We need a gateway to create an entry point for HTTP traffic coming into the cluster. The **cafe** gateway we are going to create will open an entry point to the cluster on port 80 for HTTP traffic. +We need a Gateway to create an entry point for HTTP traffic coming into the cluster. The **cafe** Gateway we are going to create will open an entry point to the cluster on port 80 for HTTP traffic. -To route HTTP traffic from the gateway to the **coffee** service, we need to create an HTTPRoute named **coffee** and attach it to the gateway. This HTTPRoute will have a single routing rule that routes all traffic to the hostname "cafe.example.com" from the gateway to the **coffee** service. +To route HTTP traffic from the Gateway to the **coffee** service, we need to create an HTTPRoute named **coffee** and attach it to the Gateway. This HTTPRoute will have a single routing rule that routes all traffic to the hostname "cafe.example.com" from the Gateway to the **coffee** service. -Once NGINX Gateway Fabric processes the **cafe** gateway and **coffee** HTTPRoute, it will configure its data plane (NGINX) to route all HTTP requests sent to "cafe.example.com" to the pods that the **coffee** service targets: +Once NGINX Gateway Fabric processes the **cafe** Gateway and **coffee** HTTPRoute, it will configure a data plane (NGINX) to route all HTTP requests sent to "cafe.example.com" to the pods that the **coffee** service targets: {{Traffic Flow}} -The **coffee** service is omitted from the diagram above because the NGINX Gateway Fabric routes directly to the pods that the **coffee** service targets. +The **coffee** service is omitted from the diagram above because the NGINX Pod routes directly to the pods that the **coffee** service targets. {{< note >}}In the diagrams above, all resources that are the responsibility of the cluster operator are shown in blue. The orange resources are the responsibility of the application developers. @@ -145,11 +139,22 @@ spec: EOF ``` -This gateway is associated with the NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a GatewayClass with the name **nginx**. NGINX Gateway Fabric will only configure gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass` [command-line flag]({{< ref "/ngf/reference/cli-help.md#static-mode" >}}). +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service into shell variables: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` + +{{< 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.{{< /note >}} + +This Gateway is associated with NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a GatewayClass with the name **nginx**. NGINX Gateway Fabric will only configure Gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass` [command-line flag]({{< ref "/ngf/reference/cli-help.md#static-mode" >}}). -We specify a [listener](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Listener) on the gateway to open an entry point on the cluster. In this case, since the coffee application accepts HTTP requests, we create an HTTP listener, named **http**, that listens on port 80. +We specify a [listener](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Listener) on the Gateway to open an entry point on the cluster. In this case, since the coffee application accepts HTTP requests, we create an HTTP listener, named **http**, that listens on port 80. -By default, gateways only allow routes (such as HTTPRoutes) to attach if they are in the same namespace as the gateway. If you want to change this behavior, you can set +By default, Gateways only allow routes (such as HTTPRoutes) to attach if they are in the same namespace as the Gateway. If you want to change this behavior, you can set the [**allowedRoutes**](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.AllowedRoutes) field. Next you will create the HTTPRoute by copying and pasting the following into your terminal: @@ -176,7 +181,7 @@ spec: EOF ``` -To attach the **coffee** HTTPRoute to the **cafe** gateway, we specify the gateway name in the [**parentRefs**](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.CommonRouteSpec) field. The attachment will succeed if the hostnames and protocol in the HTTPRoute are allowed by at least one of the gateway's listeners. +To attach the **coffee** HTTPRoute to the **cafe** Gateway, we specify the Gateway name in the [**parentRefs**](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.CommonRouteSpec) field. The attachment will succeed if the hostnames and protocol in the HTTPRoute are allowed by at least one of the Gateway's listeners. The [**hostnames**](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.HTTPRouteSpec) field allows you to list the hostnames that the HTTPRoute matches. In this case, incoming requests handled by the **http** listener with the HTTP host header "cafe.example.com" will match this HTTPRoute and will be routed according to the rules in the spec. @@ -186,9 +191,9 @@ The [**rules**](https://gateway-api.sigs.k8s.io/references/spec/#gateway.network ## Test the configuration -To test the configuration, we will send a request to the public IP and port of NGINX Gateway Fabric that you saved in the [Before you begin](#before-you-begin) section and verify that the response comes from one of the **coffee** pods. +To test the configuration, we will send a request to the public IP and port of the NGINX Service that you saved earlier after creating the Gateway resource and verify that the response comes from one of the **coffee** pods. -{{< note >}}Your clients should be able to resolve the domain name "cafe.example.com" to the public IP of the NGINX Gateway Fabric. In this guide we will simulate that using curl's `--resolve` option. {{< /note >}} +{{< note >}}Your clients should be able to resolve the domain name "cafe.example.com" to the public IP of the NGINX Service. In this guide we will simulate that using curl's `--resolve` option. {{< /note >}} First, let's send a request to the path "/": @@ -248,7 +253,7 @@ You should receive a 404 Not Found error: If you have any issues while testing the configuration, 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 Gateway Fabric Service. Refer to the [Installation]({{< ref "/ngf/installation/" >}}) 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/installation/" >}}) guides for more information. - Check the status of the gateway: @@ -345,7 +350,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-gateway -c nginx -- nginx -T + kubectl exec -it -n -- 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/how-to/traffic-management/snippets.md b/content/ngf/how-to/traffic-management/snippets.md index 543c2b917..2c91deb93 100644 --- a/content/ngf/how-to/traffic-management/snippets.md +++ b/content/ngf/how-to/traffic-management/snippets.md @@ -64,15 +64,6 @@ We have outlined a few best practices to keep in mind when using `SnippetsFilter - Using Kubernetes manifests: set the `--snippets-filters` flag in the nginx-gateway container argument, add `snippetsfilters` to the RBAC rules with verbs `list` and `watch`, and add `snippetsfilters/status` to the RBAC rules with verb `update`. See this [example manifest](https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/snippets-filters/deploy.yaml) for clarification. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP= - GW_PORT= - ``` - - {{< 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. {{< /note >}} - - Create the coffee and tea example applications: ```yaml @@ -85,6 +76,18 @@ 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. + +- Save the public IP address and port of the NGINX Service into shell variables: + + ```text + GW_IP= + GW_PORT= + ``` + + {{< 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. {{< /note >}} + + - Create HTTPRoutes for the coffee and tea applications: ```yaml @@ -93,7 +96,7 @@ We have outlined a few best practices to keep in mind when using `SnippetsFilter - Test the configuration: - You can send traffic to the coffee and tea applications using the external IP address and port for NGINX Gateway Fabric. + You can send traffic to the coffee and tea applications using the external IP address and port for the NGINX Service. Send a request to coffee: @@ -427,7 +430,7 @@ An example of an error from the NGINX Gateway Fabric `nginx-gateway` container l {"level":"error","ts":"2024-10-29T22:19:41Z","logger":"eventLoop.eventHandler","msg":"Failed to update NGINX configuration","batchID":156,"error":"failed to reload NGINX: reload unsuccessful: no new NGINX worker processes started for config version 141. Please check the NGINX container logs for possible configuration issues: context deadline exceeded","stacktrace":"github.com/nginx/nginx-gateway-fabric/internal/mode/static.(*eventHandlerImpl).HandleEventBatch\n\tgithub.com/nginx/nginx-gateway-fabric/internal/mode/static/handler.go:219\ngithub.com/nginx/nginx-gateway-fabric/internal/framework/events.(*EventLoop).Start.func1.1\n\tgithub.com/nginx/nginx-gateway-fabric/internal/framework/events/loop.go:74"} ``` -An example of an error from the NGINX Gateway Fabric `nginx` container logs: +An example of an error from the NGINX Pod's `nginx` container logs: ```text 2024/10/29 22:18:41 [emerg] 40#40: invalid number of arguments in "limit_req_zone" directive in /etc/nginx/includes/SnippetsFilter_http_default_rate-limiting-sf.conf:1 diff --git a/content/ngf/how-to/traffic-management/tls-passthrough.md b/content/ngf/how-to/traffic-management/tls-passthrough.md index 92f1c5385..52cf11f58 100644 --- a/content/ngf/how-to/traffic-management/tls-passthrough.md +++ b/content/ngf/how-to/traffic-management/tls-passthrough.md @@ -7,7 +7,7 @@ product: NGF docs: DOCS-000 --- -Learn how to use TLSRoutes to configure TLS Passthrough load-balancing with NGINX Gateway Fabric. +Learn how to use TLSRoutes to configure TLS passthrough load-balancing with NGINX Gateway Fabric. --- @@ -27,15 +27,7 @@ In this guide, we will show how to configure TLS passthrough for your applicatio ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric with experimental features enabled. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_TLS_PORT= - ``` - -{{< 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. {{< /note >}} +- [Install]({{< relref "/ngf/installation/" >}}) NGINX Gateway Fabric with experimental features enabled. --- @@ -171,6 +163,17 @@ This Gateway will configure NGINX Gateway Fabric to accept TLS connections on po {{< 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.{{< /note >}} +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service into shell variables: + +```text +GW_IP=XXX.YYY.ZZZ.III +GW_TLS_PORT= +``` + +{{< 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. {{< /note >}} + Create a TLSRoute that attaches to the Gateway and routes requests to `app.example.com` to the `secure-app` Service: ```yaml @@ -199,7 +202,7 @@ EOF ## Send traffic -Using the external IP address and port for NGINX Gateway Fabric, send traffic to the `secure-app` application. +Using the external IP address and port for the NGINX Service, send traffic to the `secure-app` application. {{< note >}}If you have a DNS record allocated for `app.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} diff --git a/content/ngf/how-to/traffic-management/upstream-settings.md b/content/ngf/how-to/traffic-management/upstream-settings.md index 6fd92b620..8f99f3d2d 100644 --- a/content/ngf/how-to/traffic-management/upstream-settings.md +++ b/content/ngf/how-to/traffic-management/upstream-settings.md @@ -34,21 +34,7 @@ For all the possible configuration options for `UpstreamSettingsPolicy`, see the ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -- Lookup the name of the NGINX Gateway Fabric pod and save into shell variable: - - ```text - NGF_POD_NAME= - ``` - - {{< 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.{{< /note >}} +- [Install]({{< relref "/ngf/installation/" >}}) NGINX Gateway Fabric. --- @@ -160,6 +146,23 @@ spec: EOF ``` +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service 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= +``` + +{{< 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.{{< /note >}} + Create HTTPRoutes for the `coffee` and `tea` applications: ```yaml @@ -206,7 +209,7 @@ EOF Test the configuration: -You can send traffic to the `coffee` and `tea` applications using the external IP address and port for NGINX Gateway Fabric. +You can send traffic to the `coffee` and `tea` applications using the external IP address and port for the NGINX Service. Send a request to `coffee`: @@ -290,7 +293,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-gateway $NGF_POD_NAME -c nginx -- nginx -T +kubectl exec -it -n $NGINX_POD_NAME -- nginx -T ``` You should see the `zone` directive in the `coffee` and `tea` upstreams both specify the size `1m`: @@ -363,7 +366,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-gateway $NGF_POD_NAME -c nginx -- nginx -T +kubectl exec -it -n $NGINX_POD_NAME -- nginx -T ``` You should see that the `coffee` upstream has the `keepalive` directive set to 32: diff --git a/content/ngf/how-to/traffic-security/integrating-cert-manager.md b/content/ngf/how-to/traffic-security/integrating-cert-manager.md index 751e06329..ec46560e9 100644 --- a/content/ngf/how-to/traffic-security/integrating-cert-manager.md +++ b/content/ngf/how-to/traffic-security/integrating-cert-manager.md @@ -288,7 +288,7 @@ Request ID: e64c54a2ac253375ac085d48980f000a - The temporary HTTPRoute created by cert-manager routes the traffic between cert-manager and the Let's Encrypt server through NGINX Gateway Fabric. If the challenge is not successful, it may be useful to inspect the NGINX logs to see the ACME challenge requests. You should see something like the following: ```shell - kubectl logs -n nginx-gateway -c nginx + kubectl logs -n <...> 52.208.162.19 - - [15/Aug/2023:13:18:12 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "cert-manager-challenges/v1.12.0 (linux/amd64) cert-manager/bd192c4f76dd883f9ee908035b894ffb49002384" 52.208.162.19 - - [15/Aug/2023:13:18:14 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "cert-manager-challenges/v1.12.0 (linux/amd64) cert-manager/bd192c4f76dd883f9ee908035b894ffb49002384" diff --git a/content/ngf/how-to/traffic-security/securing-backend-traffic.md b/content/ngf/how-to/traffic-security/securing-backend-traffic.md index 212861e65..e8ce86ec8 100644 --- a/content/ngf/how-to/traffic-security/securing-backend-traffic.md +++ b/content/ngf/how-to/traffic-security/securing-backend-traffic.md @@ -28,14 +28,6 @@ In this guide, we will show how to specify the TLS configuration of the connecti ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric with experimental features enabled. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< 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.{{< /note >}} --- @@ -187,11 +179,22 @@ spec: EOF ``` +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service into shell variables: + +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` + +{{< 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.{{< /note >}} + --- ## Send Traffic without backend TLS configuration -Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our secure-app application. To show what happens if we send plain HTTP traffic from NGF to our `secure-app`, let's try sending a request before we create the backend TLS configuration. +Using the external IP address and port for the NGINX Service, we can send traffic to our secure-app application. To show what happens if we send plain HTTP traffic from NGINX to our `secure-app`, let's try sending a request before we create the backend TLS configuration. {{< note >}}If you have a DNS record allocated for `secure-app.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} diff --git a/content/ngf/installation/installing-ngf/manifests.md b/content/ngf/installation/installing-ngf/manifests.md index 50384c205..a42ea9bd0 100644 --- a/content/ngf/installation/installing-ngf/manifests.md +++ b/content/ngf/installation/installing-ngf/manifests.md @@ -182,7 +182,7 @@ The output should look similar to this (note that the pod name will include a un ```text NAME READY STATUS RESTARTS AGE -nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s +nginx-gateway-5d4f4c7db7-xk2kq 1/1 Running 0 112s ``` --- diff --git a/content/ngf/overview/nginx-plus.md b/content/ngf/overview/nginx-plus.md index ae4de3643..47aa8d8cc 100644 --- a/content/ngf/overview/nginx-plus.md +++ b/content/ngf/overview/nginx-plus.md @@ -10,7 +10,7 @@ NGINX Gateway Fabric can use NGINX Open Source or NGINX Plus as its data plane. ## Benefits of NGINX Plus -- **Robust metrics**: A plethora of [additional Prometheus metrics](https://github.com/nginx/nginx-prometheus-exporter#metrics-for-nginx-plus) are available. +- **Robust metrics**: A plethora of [additional Prometheus metrics]({{< ref "/ngf/how-to/monitoring/prometheus.md#nginxnginx-plus-metrics" >}}) are available. - **Live activity monitoring**: The [NGINX Plus dashboard]({{< ref "/ngf/how-to/monitoring/dashboard.md" >}}) shows real-time metrics and information about your server infrastructure. - **Dynamic upstream configuration**: NGINX Plus can dynamically reconfigure upstream servers when applications in Kubernetes scale up and down, preventing the need for an NGINX reload. - **Support**: With an NGINX Plus license, you can take advantage of full [support](https://my.f5.com/manage/s/article/K000140156/) from NGINX, Inc. From 9070dbf43ce268f6e375ca815b7441d5b068eee8 Mon Sep 17 00:00:00 2001 From: Benjamin Jee Date: Mon, 28 Apr 2025 11:21:06 -0700 Subject: [PATCH 2/2] Update request mirror document --- .../ngf/how-to/traffic-management/mirror.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/content/ngf/how-to/traffic-management/mirror.md b/content/ngf/how-to/traffic-management/mirror.md index 8ca7a5c2e..e6a5c0bd0 100644 --- a/content/ngf/how-to/traffic-management/mirror.md +++ b/content/ngf/how-to/traffic-management/mirror.md @@ -23,14 +23,6 @@ sent to the **coffee** application will also be sent to the **tea** application ## Before you begin - [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< 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.{{< /note >}} --- @@ -147,6 +139,17 @@ spec: EOF ``` +After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. + +Save the public IP address and port of the NGINX Service into shell variables: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_PORT= + ``` + +{{< 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.{{< /note >}} + Now create an HTTPRoute that defines a RequestMirror filter that copies all requests sent to `/coffee` to be sent to the **coffee** backend and mirrored to the **tea** backend. Use the following command: ```yaml