Merge branch 'main' into tests/nfr-tests-edge

Author: ciarams87

.github/workflows/build.yml

@@ -193,7 +193,7 @@ jobs:
           fail-build: false
 
       - name: Upload scan result to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
+        uses: github/codeql-action/upload-sarif@0499de31b99561a6d14a36a5f662c2a54f91beee # v4.31.2
         if: ${{ !inputs.dry_run }}
         continue-on-error: true
         with:

.github/workflows/ci.yml

@@ -374,7 +374,7 @@ jobs:
 
       - name: Generate Assertion Document
         id: assertiondoc
-        uses: nginxinc/compliance-rules/.github/actions/assertion@83e452166aaf0ad8f07caf91a4f1f903b3dea1e6
+        uses: nginxinc/compliance-rules/.github/actions/assertion@b0bda4baf00b030fd4e365821878b4857078e494
         with:
           artifact-name: ${{ github.event.repository.name }}_${{ github.sha }}_${{ github.run_number }}_${{ matrix.gateway.os }}_${{ matrix.gateway.arch }}
           artifact-digest: ${{ matrix.gateway.digest }}
@@ -393,7 +393,7 @@ jobs:
 
       - name: Sign and Store Assertion Document
         id: sign
-        uses: nginxinc/compliance-rules/.github/actions/sign@83e452166aaf0ad8f07caf91a4f1f903b3dea1e6
+        uses: nginxinc/compliance-rules/.github/actions/sign@b0bda4baf00b030fd4e365821878b4857078e494
         with:
           assertion-doc: ${{ steps.assertiondoc.outputs.assertion-document-path }}
 

.github/workflows/lint.yml

@@ -50,7 +50,7 @@ jobs:
         uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9 # v8.0.0
         with:
           working-directory: ${{ matrix.directory }}
-          version: v2.5.0 # renovate: datasource=github-tags depName=golangci/golangci-lint
+          version: v2.6.0 # renovate: datasource=github-tags depName=golangci/golangci-lint
 
   njs-lint:
     name: NJS Lint

.github/workflows/scorecards.yml

@@ -60,6 +60,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
+        uses: github/codeql-action/upload-sarif@0499de31b99561a6d14a36a5f662c2a54f91beee # v4.31.2
         with:
           sarif_file: results.sarif

.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
           - javascript
 
   - repo: https://github.com/golangci/golangci-lint
-    rev: v2.5.0
+    rev: v2.6.0
     hooks:
       - id: golangci-lint-full
         name: golangci-lint-root

Makefile

@@ -24,7 +24,7 @@ GO_LINKER_FLAGS = $(GO_LINKER_FLAGS_OPTIMIZATIONS) $(GO_LINKER_FlAGS_VARS)
 
 # tools versions
 # renovate: datasource=github-tags depName=golangci/golangci-lint
-GOLANGCI_LINT_VERSION = v2.5.0
+GOLANGCI_LINT_VERSION = v2.6.0
 # renovate: datasource=docker depName=kindest/node
 KIND_K8S_VERSION = v1.34.0
 # renovate: datasource=github-tags depName=norwoodj/helm-docs

docs/proposals/authentication-filter.md

@@ -0,0 +1,24 @@
+# Enhancement Proposal-4052: Authentiation Filter
+
+- Issue: https://github.com/nginx/nginx-gateway-fabric/issues/4052
+- Status: Provisional
+
+## Summary
+
+Design and implement a means for users of NGINX Gateway Fabric to enable authentication on requests to their backend applications.
+This new filter should eventually expose all forms of authentication available through NGINX, both Open Source and Plus.
+
+## Goals
+
+- Design a means of configuring authentication for NGF
+- Design Authentication CRD with Basic Auth and JWT Auth in mind
+- Determine initial resource specification
+- Evaluate filter early in request processing, occurring before URLRewrite, header modifiers and backend selection
+- Authentication failures returns 401 Unauthorized by default
+- Ensure response codes are configurable
+
+## Non-Goals
+
+- Design for OIDC Auth
+- An Auth filter for TCP and UDP routes
+- Design for integration with [ExternalAuth in the Gateway API](https://gateway-api.sigs.k8s.io/geps/gep-1494/)

docs/proposals/session-persistence.md

@@ -0,0 +1,25 @@
+# Enhancement Proposal-4051: Session Persistence for NGINX Plus and OSS
+
+- Issue: https://github.com/nginx/nginx-gateway-fabric/issues/4051
+- Status: Provisional
+
+## Summary
+
+Enable NGINX Gateway Fabric to support session persistence for both NGINX Plus and NGINX OSS, allowing application developers to configure basic session persistence using the `ip_hash` load balancing method in OSS and cookie-based session persistence in NGINX Plus.
+
+## Goals
+
+- Extend the Upstream Settings Policy API to allow specifying `ip_hash` load balancing method to support basic session persistence.
+- Design the translation of the Gateway API `sessionPersistence` specification, which can be configured on both HTTPRoute and GRPCRoute, into NGINX Plus cookie-based session persistence directives with `secure` and `httpOnly` mode enforced by default.
+
+## Non-Goals
+
+- Describe or implement low-level configuration details for enabling session persistence.
+- Extend session persistence support to TLSRoutes or other Layer 4 route types.
+- Supporting the `sameSite` cookie directive for NGINX Plus session persistence, which may be considered in the future as the Gateway API `sessionPersistence` specification evolves.
+
+## Useful Links
+
+- Session Persistence [specification](https://gateway-api.sigs.k8s.io/reference/spec/#sessionpersistence).
+- Extended Session Persistence [GEP](https://gateway-api.sigs.k8s.io/geps/gep-1619).
+- RFC standard for [Set-Cookie](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1) header.

examples/externalname-service/README.md

@@ -7,16 +7,24 @@ This example demonstrates how to use NGINX Gateway Fabric to route traffic to ex
 In this example, we will:
 
 1. Deploy NGINX Gateway Fabric with DNS resolver configuration
-2. Create an ExternalName service pointing to an external API
-3. Configure HTTP and TLS routes to route traffic to this external service
-4. Test both HTTP and TLS routing functionality
+2. Create an ExternalName service pointing to an external API (httpbin.org)
+3. Deploy an internal service (coffee) to demonstrate mixed routing
+4. Configure an HTTPRoute that routes to both external and internal services
+5. (Optional) Configure BackendTLSPolicy for HTTPS connections to external services
+6. Test HTTP routing with both external and internal services
+7. (Optional) Test HTTPS backend connections and TLS passthrough
 
 ## Running the Example
 
 ## 1. Deploy NGINX Gateway Fabric
 
 1. Follow the [installation instructions](https://docs.nginx.com/nginx-gateway-fabric/install/) to deploy NGINX Gateway Fabric.
 
+    **Note**: To use BackendTLSPolicy or TLSRoute for HTTPS connections to external services, you must:
+
+    - Install NGINX Gateway Fabric with `enableExperimental=true`
+    - Install the experimental Gateway APIs on the cluster
+
 ## 2. Deploy the Gateway with DNS Resolver
 
 Create the Gateway and NginxProxy configuration that enables DNS resolution for ExternalName services:
@@ -30,30 +38,64 @@ This creates:
 - A Gateway with HTTP and TLS listeners
 - An NginxProxy resource with DNS resolver configuration
 
-## 3. Deploy ExternalName Services
+## 3. Deploy Services
 
-Create the ExternalName service that points to external APIs:
+Create the ExternalName service and internal service:
 
 ```shell
-kubectl apply -f external-service.yaml
+kubectl apply -f cafe.yaml
 ```
 
-This creates an ExternalName service which points to `httpbin.org` with both HTTP and HTTPS ports
+This creates:
+
+- An ExternalName service which points to `httpbin.org` with both HTTP and HTTPS ports
+- A coffee deployment and service for internal routing
 
 ## 4. Configure Routing
 
-Create the HTTPRoute and TLSRoute that route traffic to the external service:
+Create the HTTPRoute and TLSRoute that route traffic to the services:
 
 ```shell
 kubectl apply -f route.yaml
 ```
 
 This creates:
 
-- An HTTPRoute that routes HTTP traffic to the httpbin service
-- A TLSRoute that routes TLS traffic to the httpbin service
+- An HTTPRoute with two paths:
+  - `/external/*` - Routes to the ExternalName service (httpbin.org) with a URLRewrite filter that strips the `/external` prefix
+  - `/coffee` - Routes to the internal coffee service
+- A TLSRoute for TLS passthrough to the external httpbin service (commented out by default)
+
+## 5. (Optional) Configure HTTPS Backend
+
+If your external service requires HTTPS connections (like `https://httpbin.org`), you need to:
+
+1. Update the HTTPRoute to use port 443 for the httpbin service in `route.yaml`:
+
+   ```yaml
+   backendRefs:
+   - name: httpbin
+     port: 443  # Change from 80 to 443
+   ```
 
-## 5. Test the Configuration
+2. Create a BackendTLSPolicy:
+
+   ```shell
+   kubectl apply -f backendtlspolicy.yaml
+   ```
+
+This configures NGINX Gateway Fabric to:
+
+- Establish TLS connections to the backend service
+- Verify the backend's TLS certificate using system CA certificates
+- Match the certificate's hostname against the external service hostname
+
+**Note**: BackendTLSPolicy is different from TLSRoute:
+
+- **BackendTLSPolicy**: NGF terminates client TLS/HTTP and establishes HTTPS to the backend. Allows HTTP-level routing (paths, headers, etc.)
+- **TLSRoute**: TLS passthrough where the client establishes TLS directly with the backend. No HTTP-level routing possible.
+
+## 6. Test the Configuration
 
 Wait for the Gateway to be ready:
 
@@ -66,43 +108,106 @@ Save the public IP address and ports of the NGINX Service into shell variables:
 ```text
 GW_IP=XXX.YYY.ZZZ.III
 GW_PORT_HTTP=<port number>
-GW_PORT_HTTPS=<port number>
 ```
 
-Test the httpbin service via HTTP:
+Test the ExternalName service (httpbin.org) via HTTP:
 
 ```shell
-curl --resolve httpbin.example.com:$GW_PORT_HTTP:$GW_IP http://httpbin.example.com:$GW_PORT_HTTP/get
+curl --resolve cafe.example.com:$GW_PORT_HTTP:$GW_IP http://cafe.example.com:$GW_PORT_HTTP/external/get
 ```
 
-Test the httpbin service via TLS passthrough:
-
-```shell
-curl -k --resolve httpbin.example.com:$GW_PORT_HTTPS:$GW_IP https://httpbin.example.com:$GW_PORT_HTTPS/get
-```
-
-You should see a JSON response from httpbin.org showing request details e.g.
+You should see a JSON response from httpbin.org. Notice the `Host` header is correctly set to `httpbin.org`:
 
 ```json
 {
   "args": {},
   "headers": {
     "Accept": "*/*",
-    "Host": "httpbin.example.com",
+    "Host": "httpbin.org",
     "User-Agent": "curl/8.7.1",
-    "X-Amzn-Trace-Id": "Root=1-68a49086-1e1dabb51155e05c1ebc1f63"
+    "X-Amzn-Trace-Id": "Root=1-6901e342-2ce43cf518ee439d4e4d4867",
+    "X-Forwarded-Host": "cafe.example.com"
   },
   "origin": "xxx.xxx.xxx.xx",
-  "url": "https://httpbin.example.com/get"
+  "url": "http://cafe.example.com/get"
 }
 ```
 
+Test the internal coffee service:
+
+```shell
+curl --resolve cafe.example.com:$GW_PORT_HTTP:$GW_IP http://cafe.example.com:$GW_PORT_HTTP/coffee
+```
+
+You should see a response from the coffee service:
+
+```text
+Server address: 10.244.0.7:8080
+Server name: coffee-<pod-id>
+Date: ...
+URI: /coffee
+Request ID: ...
+```
+
+You can also test other httpbin.org endpoints:
+
+```shell
+# Test /anything endpoint
+curl --resolve cafe.example.com:$GW_PORT_HTTP:$GW_IP http://cafe.example.com:$GW_PORT_HTTP/external/anything
+
+# Test /headers endpoint
+curl --resolve cafe.example.com:$GW_PORT_HTTP:$GW_IP http://cafe.example.com:$GW_PORT_HTTP/external/headers
+```
+
+### Testing HTTPS Backend (Optional)
+
+If you configured BackendTLSPolicy in step 5, NGF will establish HTTPS connections to the external service. The client connection remains HTTP, but the backend connection uses HTTPS:
+
+```shell
+curl --resolve cafe.example.com:$GW_PORT_HTTP:$GW_IP http://cafe.example.com:$GW_PORT_HTTP/external/get
+```
+
+The response will show the request was successfully proxied to `https://httpbin.org` with proper TLS verification.
+
+### Testing TLS Passthrough (Optional)
+
+To test TLS passthrough, first uncomment the TLSRoute section in `route.yaml` and reapply:
+
+```shell
+kubectl apply -f route.yaml
+```
+
+Then save the HTTPS port:
+
+```text
+GW_PORT_HTTPS=<port number>
+```
+
+Test the httpbin service via TLS passthrough:
+
+```shell
+curl -k --resolve httpbin.example.com:$GW_PORT_HTTPS:$GW_IP https://httpbin.example.com:$GW_PORT_HTTPS/get
+```
+
+You should see a JSON response from httpbin.org via HTTPS.
+
+## How It Works
+
+This example demonstrates key features for routing to external services:
+
+1. **DNS Resolution**: The NginxProxy resource configures DNS resolvers (8.8.8.8, 1.1.1.1) so NGINX can resolve external hostnames
+2. **Host Header Handling**: NGF automatically detects ExternalName services and sets the `Host` header to the external hostname (`httpbin.org`) instead of the Gateway hostname (`cafe.example.com`), ensuring external services receive the correct Host header
+3. **URL Rewriting**: The URLRewrite filter strips the `/external` prefix before proxying to httpbin.org, so `/external/get` becomes `/get` on the external service
+4. **Mixed Routing**: The same HTTPRoute can route to both ExternalName services and internal Kubernetes services seamlessly
+5. **HTTPS Backends**: BackendTLSPolicy enables secure HTTPS connections to external services while allowing HTTP-level routing based on paths, headers, etc.
+6. **TLS Passthrough**: The TLSRoute allows direct TLS connections to external services without termination at the Gateway (no HTTP-level routing)
+
 ## Cleanup
 
 Remove all resources created in this example:
 
 ```shell
 kubectl delete -f route.yaml
-kubectl delete -f external-service.yaml
+kubectl delete -f cafe.yaml
 kubectl delete -f gateway.yaml
 ```

examples/externalname-service/backendtlspolicy.yaml

@@ -0,0 +1,12 @@
+apiVersion: gateway.networking.k8s.io/v1alpha3
+kind: BackendTLSPolicy
+metadata:
+  name: httpbin-tls
+spec:
+  targetRefs:
+  - group: ""
+    kind: Service
+    name: httpbin
+  validation:
+    hostname: httpbin.org
+    wellKnownCACertificates: System