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.

📘

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.

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.

🚧

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.

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 article. Below is an example for the Advanced Blocking Response Flag configuration.

controller:
    name: controller
    extraModules:
        - name: px-enforcer
        ...
    config:
        ...
        server-snippet: |
            ...
            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.

📘

Note

We highly recommend using the preferred method for integration using the External Module if possible.

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.
   

🚧

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.

controller:
    name: controller
    image:
        registry: docker.io
        image: perimeterx/px-nginx-ingress-controller
        tag: TAG # must match the current ingress version
        digest: DIGEST
    config:
        main-snippet: |
            thread_pool px_pool threads=10;
        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 article. Below is an example for the Advanced Blocking Response Flag configuration.

controller:
    name: controller
        ...
    config:
        ...
        server-snippet: |
            ...
	        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