Ingress NGINX controller

You can integrate your HUMAN NGINX Enforcer with Kubernetes’ ingress NGINX controller to deploy the Enforcer. An 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 (preferred)
2. Using a HUMAN-provided custom version of ingress NGINX Controller

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

Prerequisites

• Functioning Ingress NGINX controller
• Helm. See their documentation 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 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.

The image is hosted on a DockerHub repository: 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)
• Y.Y.Y is the NGINX Enforcer version (see 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.

1
controller:
2
    extraModules:
3
      - name: px-enforcer
4
        image:
5
            registry: docker.io
6
            image: perimeterx/px-extramodules
7
            tag: TAG # must match the current ingress version
8
            digest: DIGEST
9
    config:
10
      main-snippet: |
11
        thread_pool px_pool threads=10;
12
        load_module /modules_mount/ngx_http_pxnginx_module.so;
13
      server-snippet: |
14
        px_enabled on;
15
        px_appId "--REPLACE--";
16
        px_cookie_secret "--REPLACE--";
17
        px_auth_token "--REPLACE--";

2. Add any optional Enforcer configurations in the server-snippet. These are described in our Configuration Options article. Below is an example for the Advanced Blocking Response Flag configuration.

1
controller:
2
    name: controller
3
    extraModules:
4
        - name: px-enforcer
5
        ...
6
    config:
7
        ...
8
        server-snippet: |
9
            ...
10
            px_enable_json_response true;

3. Deploy the External Module by running:

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

The image is hosted on a DockerHub repository: 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)
• Y.Y.Y is the NGINX Enforcer version (see 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.

1
controller:
2
    name: controller
3
    image:
4
        registry: docker.io
5
        image: perimeterx/px-nginx-ingress-controller
6
        tag: TAG # must match the current ingress version
7
        digest: DIGEST
8
    config:
9
        server-snippet: |
10
            px_enabled on;
11
            px_appId "--REPLACE--";
12
            px_cookie_secret "--REPLACE--";
13
            px_auth_token "--REPLACE--";
14
            # add other PX related settings here

2. Add any optional Enforcer configurations in the server-snippet. These are described in our Configuration Options article. Below is an example for the Advanced Blocking Response Flag configuration.

1
controller:
2
    name: controller
3
        ...
4
    config:
5
        ...
6
        server-snippet: |
7
            ...
8
	        px_enable_json_response true;

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

$
helm upgrade nginx-ingress ingress-nginx/ingress-nginx --values values.yaml --install