You can enable Datadog App and API Protection for traffic managed by Envoy Gateway to inspect and protect traffic at the edge of your infrastructure.

Prerequisites

• A running Kubernetes cluster with Envoy Gateway installed.
• The Datadog Agent is installed and configured in your Kubernetes cluster.
  • Enable and configure Remote Configuration to enable blocking attackers through the Datadog UI.
  • Enable APM in the Agent to allow the security processor service to send its own traces to the Agent.
    • Optionally, enable the Cluster Agent Admission Controller to automatically inject the Datadog Agent host information to the App and API Protection security processor service.

Automated configuration with App and API Protection for Kubernetes

Setup

1. Deploy the security processor using the deployment manifest shown in Deploy the Datadog security processor service below.

2. Enable automatic configuration using the Datadog Operator or Helm.

   Add annotations to your DatadogAgent resource. The service name annotation is required and must match your security processor service:

   apiVersion: datadoghq.com/v2alpha1
   kind: DatadogAgent
   metadata:
     name: datadog
     annotations:
       agent.datadoghq.com/appsec.injector.enabled: "true"
       agent.datadoghq.com/appsec.injector.processor.service.name: "datadog-aap-extproc-service"  # Required
       agent.datadoghq.com/appsec.injector.processor.service.namespace: "datadog"
   spec:
     override:
       clusterAgent:
         env:
           - name: DD_CLUSTER_AGENT_APPSEC_INJECTOR_MODE
             value: "external"
   

   Apply the configuration:

   kubectl apply -f datadog-agent.yaml
   

   Add the following to your values.yaml:

   datadog:
     appsec:
       injector:
         enabled: true
         mode: "external"
         processor:
           service:
             name: datadog-aap-extproc-service  # Required: must match your security processor service name
             namespace: datadog                 # Must match the namespace where the service is deployed
   

   Install or upgrade the Datadog Helm chart:

   helm upgrade -i datadog-agent datadog/datadog -f values.yaml
   

   After you enable this, the Datadog Cluster Agent:

   • Detects your Envoy Gateway installations
   • Creates EnvoyExtensionPolicy resources for each Gateway
   • Configures the policies to route traffic to the security processor

3. Verify the configuration by checking for created policies:

   kubectl get envoyextensionpolicy -A
   

For configuration options and troubleshooting, see App and API Protection for Kubernetes.

Manual configuration (alternative)

For fine-grained control over specific gateways, use the manual setup:

1. Deploy the Datadog Security Processor service in your cluster.
2. Configure an EnvoyExtensionPolicy that points to it.

Step 1: Deploy the Datadog security processor service

This gRPC server receives requests and responses from Envoy for App and API Protection analysis.

Deploy it in a namespace accessible by your Envoy Gateway. The Docker image is on the Datadog Go tracer GitHub Registry.

Example manifest (datadog-aap-extproc-service.yaml):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: datadog-aap-extproc-deployment
  namespace: <your-preferred-namespace> # Change to your preferred namespace, ensure it's resolvable by the Envoy Gateway
  labels:
    app: datadog-aap-extproc
spec:
  replicas: 1 # Adjust replica count based on your load
  selector:
    matchLabels:
      app: datadog-aap-extproc
  template:
    metadata:
      labels:
        app: datadog-aap-extproc
    spec:
      containers:
      - name: datadog-aap-extproc-container
        image: ghcr.io/datadog/dd-trace-go/service-extensions-callout:v2.4.0 # Replace with the latest released version
        ports:
        - name: grpc
          containerPort: 443 # Default gRPC port for the security processor
        - name: health
          containerPort: 80  # Default health check port
        env:
        # Optional: Agent Configuration
        # If you enabled the Cluster Agent Admission Controller, you can skip this section as the Agent host information is automatically injected.
        # Otherwise, configure the address of your Datadog Agent for the security processor
        - name: DD_AGENT_HOST
          value: "<your-datadog-agent-service>.<your-datadog-agent-namespace>.svc.cluster.local"
        - name: DD_TRACE_AGENT_PORT # Optional if your Agent's trace port is the default 8126
          value: "8126"

        # Disable TLS for communication between Envoy Gateway and the security processor. Default is true.
        # Cannot be enabled for now
        - name: DD_SERVICE_EXTENSION_TLS
          value: "false"

        readinessProbe:
          httpGet:
            path: /
            port: health
          initialDelaySeconds: 5
          periodSeconds: 10
        livenessProbe:
          httpGet:
            path: /
            port: health
          initialDelaySeconds: 15
          periodSeconds: 20
---
apiVersion: v1
kind: Service
metadata:
  name: datadog-aap-extproc-service # This name will be used in the EnvoyExtensionPolicy configuration
  namespace: <your-preferred-namespace> # Change to your preferred namespace, ensure it's resolvable by the Envoy Gateway
  labels:
    app: datadog-aap-extproc
spec:
  ports:
  - name: grpc
    port: 443
    targetPort: grpc
    protocol: TCP
  selector:
    app: datadog-aap-extproc
  type: ClusterIP

Configuration options for the security processor

The Datadog Security Processor exposes some settings:

Configure the connection from the security processor to the Datadog Agent using these environment variables:

The security processor is built on top of the Datadog Go Tracer and inherits all of its environment variables. See Configuring the Go Tracing Library and App and API Protection Library Configuration.

Step 2: Configure an EnvoyExtensionPolicy

Use an EnvoyExtensionPolicy to instruct Envoy Gateway to call the Datadog security processor. You can attach the policy to a Gateway or to specific HTTPRoute/GRPCRoute resources.

This sends all traffic on the selected Gateway to the security processor. Example manifest (datadog-aap-extproc-eep.yaml):

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyExtensionPolicy
metadata:
  name: datadog-aap-extproc-eep
  namespace: <your-preferred-namespace> # same namespace as the Gateway
spec:
  targetRefs:
  # Target the entire Gateway
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: <your-gateway-name> # update to your specific gateway name
  # Target specific HTTPRoutes/GRPCRoutes
  #- group: gateway.networking.k8s.io
  #  kind: HTTPRoute
  #  name: <your-http-route-name>
  extProc:
  - backendRefs:
    - group: ""
      kind: Service
      name: datadog-aap-extproc-service
      namespace: <your-preferred-namespace> # namespace of the security processor Service
      port: 443

    # Optional: Enable fail open mode. Default is false.
    # Normally, if the security processor fails or times out, the filter fails and Envoy
    # returns a 5xx error to the downstream client. Setting this to true allows requests
    # to continue without error if a failure occurs.
    failOpen: true

    # Optional: Set a timeout by processing message. Default is 200ms.
    # There is a maxium of 2 messages per requests with headers only and 4 messages maximum
    # with body processing enabled.
    # Note: This timeout also includes the data communication between Envoy and the security processor.
    # The timeout should be adjusted to accommodate the additional possible processing time.
    # Larger payloads will require a longer timeout.
    messageTimeout: 200ms

    processingMode:
      # The security processor can dynamically override the processing mode as needed, instructing
      # Envoy to forward request and response bodies to the security processor.
      allowModeOverride: true
      # Only enable the request and response header modes by default.
      request: {}
      response: {}

Cross‑namespace reference

If your security processor Service is in a different namespace than the policy, add a ReferenceGrant in the processor’s namespace. For example, you can do this with a manifest such as datadog-aap-eep-rg.yaml.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: datadog-aap-eep-rg
  namespace: <your-extproc-namespace>   # namespace of the security processor Service
spec:
  from:
  - group: gateway.envoyproxy.io
    kind: EnvoyExtensionPolicy
    namespace: <your-policy-namespace>  # namespace of the EnvoyExtensionPolicy (and the Gateway)
  to:
  - group: ""
    kind: Service
    name: datadog-aap-extproc-service

Step 3: Validate

After applying the policy, traffic through the targeted Gateway/Routes is inspected by App and API Protection.

After this configuration is complete, the library collects security data from your application and sends it to the Agent. The Agent sends the data to Datadog, where out-of-the-box detection rules flag attacker techniques and potential misconfigurations so you can take steps to remediate.

1. To see App and API Protection threat detection in action, send known attack patterns to your application. For example, trigger the Security Scanner Detected rule by running a file that contains the following curl script:

   for ((i=1;i<=250;i++)); 
   do
   # Target existing service's routes
   curl https://your-application-url/existing-route -A dd-test-scanner-log;
   # Target non existing service's routes
   curl https://your-application-url/non-existing-route -A dd-test-scanner-log;
   done

   Note: The dd-test-scanner-log value is supported in the most recent releases.

   A few minutes after you enable your application and send known attack patterns to it, threat information appears in the Application Signals Explorer and vulnerability information appears in the Vulnerabilities explorer.

Limitations

Observability mode (asynchronous analysis) is not available for Envoy Gateway.

For additional details on the Envoy Gateway integration compatibilities, see the Envoy Gateway integration compatibility page.

Further Reading

Additional helpful documentation, links, and articles:

Envoy integration source codeSOURCE CODE OOTB App and API Protection RulesDOCUMENTATION Troubleshooting App and API ProtectionDOCUMENTATION