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

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

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

4. You should get the confirmation the secret was created:

secret/dd-ingress-controller-secret created

5. Create a dd-values.yaml file like the example below (TAG and sha256:HASH are going to be replaced, more information 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 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 https://kubernetes.github.io/ingress-nginx
helm repo update

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

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;