NGINX Gateway Fabric with the HUMAN Enforcer

NGINX Gateway Fabric + HUMAN Enforcer is a production-ready distribution of NGINX Gateway Fabric engineered specifically for high-security environments. This custom Docker image comes with the HUMAN Enforcer module pre-compiled and pre-installed, bridging the gap between modern Kubernetes networking and enterprise-grade bot protection.

What is NGINX Gateway Fabric?

NGINX Gateway Fabric (NGF) is the successor to the traditional NGINX Ingress Controller. It’s an implementation of the Kubernetes Gateway API designed to configure NGINX as a data plane using modern, role-oriented primitives. Unlike the legacy Ingress resource, NGF provides a standardized, expressive, and extensible way to manage external access to services in a Kubernetes cluster.

The Integration Logic: SnippetsFilter

One of the primary challenges of adopting the strict Gateway API standard is the loss of flexibility for custom NGINX modules. The Gateway API does not inherently know how to configure third-party modules like HUMAN Security. We solve this using SnippetsFilter.

SnippetsFilter is a powerful extension within NGINX Gateway Fabric that allows us to inject raw NGINX configuration directives directly into specific contexts (like main, http, or location) of the generated nginx.conf. Instead of mounting complex sidecar configurations or external files, you configure the HUMAN Enforcer using native Kubernetes manifests. You simply apply a SnippetsFilter resource that contains your HUMAN directives (e.g. px_appId, px_auth_token, px_cookie_secret, etc.). The NGINX Gateway Fabric dynamically injects these into the data plane configuration, ensuring your bot protection rules are applied at the edge, aligned perfectly with your HTTPRoutes.

NGINX Gateway Fabric & HUMAN Enforcer Docker image integration

The px-nginx-gateway-fabric image is based on the official NGINX Gateway Fabric image, with the HUMAN Enforcer module pre-compiled and integrated.

• Docker image repository: us-docker.pkg.dev/hmn-registry/docker-public/px-nginx-gateway-fabric
• Versioning schema: px-nginx-ingress-controller:vX.X.X-Y.Y.Y, where:
  • vX.X.X: NGINX Gateway Fabric version. See releases
  • Y.Y.Y: NGINX Enforcer version. See changelog

Prerequisites

• A functioning NGINX Gateway Fabric setup
• Your unique HUMAN information:
  • Your Application ID. You can find this under Platform Settings > Applications > Overview in the HUMAN console. If you have multiple environments, you’ll also have multiple Application IDs, so be sure to choose the correct ID for the environment you want to install on.
  • Your Server Token. You can find this under Platform Settings > Applications > Status & Settings > Server Token.
  • Your Risk Cookie Key. You can find this under Bot Defender > Policies > Policy Settings > Policy Information.

Integration

1. Install NGINX Gateway Fabric and the HUMAN Enforcer as well as enable SnippetsFilter. Set the parameters as follows:
   • nginx.image.repository: Set to us-docker.pkg.dev/hmn-registry/docker-public/px-nginx-gateway-fabric
   • nginx.image.tag: Use v2.3.0-latest

$
helm uninstall ngf -n nginx-gateway
>
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
>
  --create-namespace \
>
  -n nginx-gateway \
>
  --set nginxGateway.snippetsFilters.enable=true \ # enables SnippetsFilter feature
>
  --set nginx.image.repository=us-docker.pkg.dev/hmn-registry/docker-public/px-nginx-gateway-fabric \ # overrides the Data Plane image
>
  --set nginx.image.tag=v2.3.0-latest \ # overrides the Data Plane image tag
>
  --set nginx.image.pullPolicy=IfNotPresent

2. Create a SnippetsFilter resource, px-enforcer-sf, with your Enforcer configuration.

1
apiVersion: gateway.nginx.org/v1alpha1
2
kind: SnippetsFilter
3
metadata:
4
  name: px-enforcer-sf
5
spec:
6
  snippets:
7
    - context: main
8
      value: |
9
        load_module /usr/lib/nginx/modules/ngx_http_pxnginx_module.so;
10
        thread_pool px_pool threads=10;
11
    - context: http.server
12
      value: |
13
        px_enabled on;
14
        px_appId "--PX_APP_ID--";
15
        px_cookie_secret "--PX_COOKIE_SECRET--";
16
        px_auth_token "--PX_AUTH_TOKEN--";
17
        # add other Enforcer related settings here

3. Apply a new SnippetsFilter resource

$
kubectl apply -f px-enforcer-sf.yaml

4. Create and apply an HTTPRoute resource that references the SnippetsFilter

$
kubectl apply -f - <<EOF
>
apiVersion: gateway.networking.k8s.io/v1
>
kind: HTTPRoute
>
metadata:
>
  name: px-enforcer
>
spec:
>
  parentRefs: # reference your existing Gateway resource here
>
    - name: gateway
>
      sectionName: http
>
  rules:
>
    - filters: # inject the Enforer config by applying the SnippetsFilter to this HTTPRoute
>
        - type: ExtensionRef
>
          extensionRef:
>
            group: gateway.nginx.org
>
            kind: SnippetsFilter
>
            name: px-enforcer-sf
>
EOF