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.


Need a specific version of Ingress Nginx Controller ?

Please contact our support team and we will generate it for you

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


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 (TAG and sha256:HASH are going to be replaced, more information below)
    name: controller
      image: datadome/datadome-ingress-nginx-controller
      tag: TAG
      digest: "sha256:HASH"
  # -- Additional volumeMounts to the controller main container.
    - name: dd-secret
      mountPath: /etc/nginx/config.d/
      readOnly: true
    - name: dd-secret
        secretName: dd-ingress-controller-secret
      main-snippet: |
        load_module /etc/nginx/modules/;
        load_module /etc/nginx/modules/;
        load_module /etc/nginx/modules/;
      http-snippet: |
        upstream datadome {
          keepalive 10;
      server-snippet: |
        data_dome_auth @datadome;
        include /etc/nginx/config.d/datadome.conf;

In this file as previously mentioned, you should set:

  • TAG: with the image tag you want (explained in the first section)
  • sha256:HASH: the image digest

You can get those information on DockerHub. Below an example of values:

  tag: v1.2.1-2.41
  digest: "sha256:8e71e1255aad9a96329a549bc4248124da7d82cdf858e77b1ec2af30ebe4506d"

Below an example on how to get it:

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


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

Note: should be added to the "server-snippet" section inside the dd-values.yml
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


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:

      main-snippet: |
        load_module /etc/nginx/modules/;
        load_module /etc/nginx/modules/;
        load_module /etc/nginx/modules/;
      http-snippet: |
        upstream datadome {
          keepalive 10;
        map $http_host $is_datadome_enabled { 
          default '@datadome';
      server-snippet: |
        data_dome_auth $is_datadome_enabled;
        include /etc/nginx/config.d/datadome.conf;