> 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.

# Ingress NGINX controller

> **Warning**
>
> The Kubernetes team [has deprecated Ingress NGINX,](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/) and it will no longer receive new features or updates. As it is not longer supported, we recommend using the [NGINX Gateway Fabric with HUMAN Enforcer](/applications/nginx-gateway-fabric) instead.

You can integrate your HUMAN NGINX Enforcer with Kubernetes’ [**ingress NGINX controller**](https://github.com/kubernetes/ingress-nginx) to deploy the Enforcer. An [**ingress**](https://kubernetes.io/docs/concepts/services-networking/ingress/) may be configured to give services externally reachable URLs, load balance traffic, terminate SSL/TLS, and offer name-based virtual hosting An ingress controller is responsible for fulfilling the ingress, usually with a load balancer, though it may also configure your edge router or additional frontends to help handle the traffic.

You can integrate the Enforcer with the ingress NGINX controller in two ways:

1. [Attach as an external module to an ingress NGINX Controller](#human-external-module-for-ingress-nginx-controller) (preferred)
2. [Using a HUMAN-provided custom version of ingress NGINX Controller](#human-ingress-nginx-controller-image)

You can learn how to integrate using either of these methods below.

## Prerequisites

* Functioning Ingress NGINX controller
* Helm. See their [documentation](https://helm.sh/docs/intro/install/) to learn how to install.
* 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.**

## HUMAN External Module for ingress NGINX controller

This integration method uses an **External Module,** which is a [Docker image](https://hub.docker.com/r/perimeterx/px-extramodules/) that contains the HUMAN Enforcer NGINX module. This image is attached to an ingress NGINX controller, and once deployed, the Enforcer NGINX module is available for your use.

> **Note**
>
> The External Module is the **preferred** method of integration due to the following:
>
> * It is only a single file, and the Enforcer module is copied to the original ingress NGINX Controller container
> * The original ingress NGINX controller container stays intact
> * It supports for multiple platforms: `amd64`, `arm64`, `arm32v7`
> * It has a smaller Docker image
>
> For these reasons, we **highly recommend** using the External Module if possible.

The image is hosted on a DockerHub repository: [https://hub.docker.com/r/perimeterx/px-extramodules](https://hub.docker.com/r/perimeterx/px-extramodules).

The images are tagged with the syntax `px-`extramodules`:vX.X.X-Y.Y.Y`, where:

* `vX.X.X` is the **ingress version** (see [changelog](https://github.com/kubernetes/ingress-nginx/releases/))
* `Y.Y.Y` is the **NGINX Enforcer version** (see [changelog](/applications/nginx-c-module/changelog)). The `latest` tag always uses the latest stable version.

To integrate with the external module:

1. Create a `values.xml` file with the minimum configurations as shown below. `TAG` and `DIGEST` can be found from the [Docker Image](https://hub.docker.com/r/perimeterx/px-extramodules/tags).

> **Warning**
>
> The `TAG` **must** match the current ingress version. For example, if your ingress version is v1.12.0, then your `TAG` must be `v1.12.0-latest`.

```yaml
controller:
    extraModules:
      - name: px-enforcer
        image:
            registry: docker.io
            image: perimeterx/px-extramodules
            tag: TAG # must match the current ingress version
            digest: DIGEST
    config:
      main-snippet: |
        thread_pool px_pool threads=10;
        load_module /modules_mount/ngx_http_pxnginx_module.so;
      server-snippet: |
        px_enabled on;
        px_appId "--REPLACE--";
        px_cookie_secret "--REPLACE--";
        px_auth_token "--REPLACE--";
```

2. Add any optional Enforcer configurations in the `server-snippet`. These are described in our [Configuration Options](/applications/ingress-nginx-enforcer-configuration-options) article. Below is an example for the **Advanced Blocking Response Flag** configuration.

```yaml
controller:
    name: controller
    extraModules:
        - name: px-enforcer
        ...
    config:
        ...
        server-snippet: |
            ...
            px_enable_json_response true;
```

3. Deploy the **External Module** by running:

```shell
helm install nginx-ingress ingress-nginx/ingress-nginx --version <HELM CHART VERSION> --values px-values.xml
```

## HUMAN Ingress NGINX controller image

This integration method uses a custom version of ingress NGINX controller, which includes an NGINX server with a built-in HUMAN Enforcer.

> **Note**
>
> We **highly recommend** using the preferred method for integration using the [**External Module**](#human-external-module-for-ingress-nginx-controller) if possible.

The image is hosted on a DockerHub repository: [https://hub.docker.com/r/perimeterx/px-nginx-ingress-controller](https://hub.docker.com/r/perimeterx/px-nginx-ingress-controller).

The images are tagged with the syntax `px-nginx-ingress-controller:vX.X.X-Y.Y.Y-Z`, where:

* `vX.X.X` is the **ingress version** (see [changelog](https://github.com/kubernetes/ingress-nginx/releases/))
* `Y.Y.Y` is the **NGINX Enforcer version** (see [changelog](/applications/nginx-c-module/changelog)). The `latest` tag always uses the latest stable version.
* Z: PerimeterX module configuration type (server or location)

To replace the original Ingress NGINX controller image with the custom image:

1. Create a `values.xml` file with the minimum configurations as shown below. `TAG` and `DIGEST` can be found from the [Docker Image](https://hub.docker.com/r/perimeterx/px-nginx-ingress-controller/tags).

> **Warning**
>
> The `TAG` **must** match the current ingress version. For example, if your ingress version is v1.12.0, then your `TAG` must be `v1.12.0-latest`.

```yaml
controller:
    name: controller
    image:
        registry: docker.io
        image: perimeterx/px-nginx-ingress-controller
        tag: TAG # must match the current ingress version
        digest: DIGEST
    config:
        server-snippet: |
            px_enabled on;
            px_appId "--REPLACE--";
            px_cookie_secret "--REPLACE--";
            px_auth_token "--REPLACE--";
            # add other PX related settings here
```

2. Add any optional Enforcer configurations in the `server-snippet`. These are described in our [Configuration Options](/applications/ingress-nginx-enforcer-configuration-options) article. Below is an example for the **Advanced Blocking Response Flag** configuration.

```yaml
controller:
    name: controller
        ...
    config:
        ...
        server-snippet: |
            ...
	        px_enable_json_response true;
```

3. Install HUMAN Ingress NGINX Controller with the Enforcer by running:

```shell
helm upgrade nginx-ingress ingress-nginx/ingress-nginx --values values.yaml --install
```