Ingress Nginx Controller

DataDome Ingress Nginx detects and protects against bot activity

For the ease of deployment, we provide you with an image from Kubernetes Ingress Nginx that has DataDome embedded. We highly recommend pulling the image on your own registry and use it from your own registry.

The image

The image can be found on DockerHub.

📘

Image tags

The images are tagged with the following syntax:
<Ingress version>-<DataDome module version>
Eg: v1.1.3-2.41 means using Ingress version 1.1.3 and DataDome module version 2.41

Requirements

To set up DataDome module on Ingress Nginx following this documentation, you will need:

  • kubectl
  • helm

Step 1: Prepare the installation (create secret and chart's values)

DataDome has to be configured in order to work properly.

  1. Create a dd-server-secret file following the example below.

  2. Update the value of YOUR_DATADOME_SERVER_SIDE_KEY by your own API server key provided by DataDome. You can find this key inside our dashboard

location = @datadome {
    data_dome_shield_key YOUR_DATADOME_SERVER_SIDE_KEY;
    proxy_pass https://datadome/validate-request/;
    proxy_method POST;
    proxy_http_version 1.1;
    proxy_set_header Connection "keep-alive";
    proxy_set_header Content-Type "application/x-www-form-urlencoded";
    proxy_set_body $data_dome_request_body;
    proxy_ignore_client_abort on;
    proxy_connect_timeout 150ms;
    proxy_read_timeout 50ms;
}
  1. Run the following command to create the secret (using the file we just created):
kubectl create secret generic dd-ingress-controller-secret \
  --from-file=datadome.conf=./dd-server-secret \
  --dry-run=client -o yaml \
  | kubectl apply -f -
  1. You should get the confirmation the secret was created:
secret/dd-ingress-controller-secret created
  1. Create a dd-values.yaml file like the example below:
controller:
    name: controller
    image:
      registry: docker.io
      image: datadome/datadome-ingress-nginx-controller
      tag: TAG
      digest: "sha256:HASH"
  # -- Additional volumeMounts to the controller main container.
    extraVolumeMounts:
    - name: dd-secret
      mountPath: /etc/nginx/config.d/
      readOnly: true
    extraVolumes:
    - name: dd-secret
      secret:
        secretName: dd-ingress-controller-secret
    config:
      main-snippet: |
        load_module /etc/nginx/modules/ngx_http_data_dome_auth_module.so;
        load_module /etc/nginx/modules/ngx_http_data_dome_shield_module.so;
        load_module /etc/nginx/modules/ngx_http_data_dome_upstream_dynamic_servers_module.so;
      http-snippet: |
        upstream datadome {
          dd_server api.datadome.co:443;
          keepalive 10;
        }
      server-snippet: |
        data_dome_auth @datadome;
        include /etc/nginx/config.d/datadome.conf;

In this file you should set:

  • the image tag you want (see first section)
  • the image digest that you can get on DockerHub in the tag section
14681468

or if you have pulled the image by running

docker image ls --digests datadome/datadome-ingress-nginx-controller

Step 2: Deploy the Ingress

  1. Add the ingress to the helm repository:
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
  1. Deploy the ingress by running:
helm install <Release Name> ingress-nginx/ingress-nginx --version <HELM_CHART_VERSION> --values dd-values.yaml

At this point, your pod should start and run.
When doing a curl request against your website, you should see the header “X-DataDome: protected”.

curl -v http://${MY_WEBSITE}
...
< x-datadome: protected
...

Update configuration

If you changed the secret you can run:

kubectl create secret generic dd-ingress-controller-secret --from-file=datadome.conf=./dd-server-secret --dry-run=client -o yaml | kubectl apply -f -

This will update the container filesystem too. It could take some time (about 30s) for the change to propagate.
Then you have to restart the controller.

If you have changed the dd-values.yml file, you will need to upgrade the controller with helm:

helm upgrade <Release Name> ingress-nginx/ingress-nginx --values dd-values.yml --install

Pull image

You can pull the docker image with:

docker pull datadome/datadome-ingress-nginx-controller:TAG

Settings

SettingDescriptionRequiredDefault
data_dome_shield_keyyour DataDome License keyyes
dd_serverhostname of the API Server
Available endpoints
optionalapi.datadome.co
data_dome_auth_uri_regexprocesses only matching URIs.

Note: should be added to the "server-snippet" section inside the dd-values.yml
optional
data_dome_auth_uri_regex_exclusionignores all matching URIs.

Note: should be added to the "server-snippet" section inside the dd-values.yml
optionalexclude static assets
proxy_connect_timeouttimeout set for the initial opening connectionoptional150ms
proxy_read_timeouttimeout set for regular API callsoptional50ms

FAQ

Can I disable DataDome dynamically with a variable (Lua for instance)?

You can set a variable to disable dynamically the DataDome module. Inside the section server-snippet of dd-values.yaml

# disable datadome
set $is_datadome_enabled off;
# enable datadome
# set $is_datadome_enabled @datadome

data_dome_auth $is_datadome_enabled;

Can I disable DataDome on specific domains?

To disable DataDome on a specific domain, update the config section of dd-values.yaml with:

    config:
      main-snippet: |
        load_module /etc/nginx/modules/ngx_http_data_dome_auth_module.so;
        load_module /etc/nginx/modules/ngx_http_data_dome_shield_module.so;
        load_module /etc/nginx/modules/ngx_http_data_dome_upstream_dynamic_servers_module.so;
      http-snippet: |
        upstream datadome {
          dd_server api.datadome.co:443;
          keepalive 10;
        }
        map $http_host $is_datadome_enabled { 
          default '@datadome';
          www.example.com 'off';
        }
      server-snippet: |
        data_dome_auth $is_datadome_enabled;
        include /etc/nginx/config.d/datadome.conf;