> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# 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`
* Artifact Registry URL: [https://console.cloud.google.com/artifacts/docker/hmn-registry/us/docker-public/px-nginx-gateway-fabric](https://console.cloud.google.com/artifacts/docker/hmn-registry/us/docker-public/px-nginx-gateway-fabric)
* Versioning schema: `px-nginx-gateway-fabric:vX.X.X-Y.Y.Y`, where:
  * `vX.X.X`: NGINX Gateway Fabric version. See [releases](https://github.com/nginx/nginx-gateway-fabric/releases)
  * `Y.Y.Y`: NGINX Enforcer version. See [changelog](/applications/nginx-c-module/changelog)

#### Available Tags

* `v2.7.0-latest`: NGINX Gateway Fabric v2.7.0 with the latest stable HUMAN Enforcer.
* `v2.6.2-latest`: NGINX Gateway Fabric v2.6.2 with the latest stable HUMAN Enforcer.
* `v2.6.1-latest`: NGINX Gateway Fabric v2.6.1 with the latest stable HUMAN Enforcer.
* `v2.5.1-latest`: NGINX Gateway Fabric v2.5.1 with the latest stable HUMAN Enforcer.
* `v2.5.0-latest`: NGINX Gateway Fabric v2.5.0 with the latest stable HUMAN Enforcer.
* `v2.4.2-latest`: NGINX Gateway Fabric v2.4.2 with the latest stable HUMAN Enforcer.
* `v2.3.0-latest`: NGINX Gateway Fabric v2.3.0 with the latest stable HUMAN Enforcer.

### 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.6.2-latest`

```bash
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.6.2-latest \ # overrides the Data Plane image tag
  --set nginx.image.pullPolicy=IfNotPresent
```

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

```yaml
apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: px-enforcer-sf
spec:
  snippets:
    - context: main
      value: |
        load_module /usr/lib/nginx/modules/ngx_http_pxnginx_module.so;
        thread_pool px_pool threads=10;
    - context: http.server
      value: |
        px_enabled on;
        px_appId "--PX_APP_ID--";
        px_cookie_secret "--PX_COOKIE_SECRET--";
        px_auth_token "--PX_AUTH_TOKEN--";
        # add other Enforcer related settings here
```

3. Apply a new SnippetsFilter resource

```shell
kubectl apply -f px-enforcer-sf.yaml
```

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

```shell
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
```