Skip to content

Commit 278a4f5

Browse files
eliottnessmichaelcretzman
eliottness
and
michaelcretzman
authored
[APPSEC-59890] AAP Kubernetes Gateway Injector preview documentation (#33117)
* [APPSEC-59890] AAP Kubernetes Gateway Injector preview documentation * [APPSEC-59890] AAP Kubernetes Gateway Injector preview documentation * [APPSEC-59890] AAP Kubernetes Gateway Injector preview documentation * revert claude settings Signed-off-by: Eliott Bouhana <[email protected]> * fix bad interpretation of claude Signed-off-by: Eliott Bouhana <[email protected]> * fuse both docs Signed-off-by: Eliott Bouhana <[email protected]> * document opt-out label Signed-off-by: Eliott Bouhana <[email protected]> * Apply suggestions from @michaelcretzman Co-authored-by: Michael Cretzman <[email protected]> * rename most places from appsec injector to gateway injector to make it clear its about proxies Signed-off-by: Eliott Bouhana <[email protected]> * fix last comments Signed-off-by: Eliott Bouhana <[email protected]> --------- Signed-off-by: Eliott Bouhana <[email protected]> Co-authored-by: Michael Cretzman <[email protected]>
1 parent 30c5981 commit 278a4f5

File tree

4 files changed

+465
-9
lines changed

4 files changed

+465
-9
lines changed

‎content/en/containers/kubernetes/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ For Agent commands, see the [Agent Commands guides][9]. For information on the D
7171
{{< nextlink href="/agent/kubernetes/configuration">}}<u>Further Configuration</u>: Collect events, override proxy settings, send custom metrics with DogStatsD, configure container allowlists and blocklists, and reference the full list of available environment variables.{{< /nextlink >}}
7272
{{< nextlink href="/agent/kubernetes/distributions">}}<u>Distributions</u>: Review base configurations for major Kubernetes distributions, including AWS Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), Red Hat OpenShift, Rancher, and Oracle Container Engine for Kubernetes (OKE).{{< /nextlink >}}
7373
{{< nextlink href="/agent/kubernetes/apm">}}<u>APM</u>: Set up trace collection: configure the Agent to accept traces, configure your Pods to communicate with the Agent, and configure your application tracers to emit traces.{{< /nextlink >}}
74+
{{< nextlink href="/agent/kubernetes/appsec">}}<u>App & API Protection</u>: Configure your ingress controller to analyze and protect your cluster API endpoints and applications.{{< /nextlink >}}
7475
{{< nextlink href="/agent/kubernetes/csi">}}<u>CSI Driver</u>: Install and set up Datadog CSI driver, and mount DogStatsD and Trace Agent UDS socket using Datadog CSI volumes.{{< /nextlink >}}
7576
{{< nextlink href="/agent/kubernetes/log">}}<u>Log collection</u>: Set up log collection in a Kubernetes environment.{{< /nextlink >}}
7677
{{< nextlink href="/agent/kubernetes/tag">}}<u>Tag extraction</u>: Configure the Agent to create and assign tags to all metrics, traces, and logs emitted by a container, Pod, or Node, based on Kubernetes labels or annotations.{{< /nextlink >}}

‎content/en/containers/kubernetes/appsec.md‎

Lines changed: 349 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,349 @@
1+
---
2+
title: Kubernetes Application Security using Gateway Injector
3+
description: Automatically enable Application Security monitoring for ingress proxies and gateways in Kubernetes
4+
aliases:
5+
- /agent/kubernetes/appsec
6+
- /security/application_security/setup/kubernetes/appsec-injector
7+
further_reading:
8+
- link: "/containers/kubernetes/apm/"
9+
tag: "Documentation"
10+
text: "Collect your application traces"
11+
- link: "/containers/kubernetes/log/"
12+
tag: "Documentation"
13+
text: "Collect your application logs"
14+
- link: "/security/application_security/setup/kubernetes/envoy-gateway"
15+
tag: "Documentation"
16+
text: "App and API Protection for Envoy Gateway"
17+
- link: "/security/application_security/setup/kubernetes/istio"
18+
tag: "Documentation"
19+
text: "App and API Protection for Istio"
20+
- link: "/security/default_rules/?category=cat-application-security"
21+
tag: "Documentation"
22+
text: "OOTB App and API Protection Rules"
23+
- link: "/security/application_security/troubleshooting"
24+
tag: "Documentation"
25+
text: "Troubleshooting App and API Protection"
26+
---
27+
28+
{{< callout url="#" btn_hidden="true" header="Gateway Security Injector is in Preview" >}}
29+
The Injector feature is in Preview. Use the following instructions to try the preview.
30+
{{< /callout >}}
31+
32+
This page describes how to set up the Datadog Gateway Injector to automatically enable Application Security monitoring, API Posture and catalog and protection for your Kubernetes ingress proxies and gateways.
33+
34+
## Overview
35+
36+
The Datadog AppSec Gateway Injector automatically configures ingress proxies and gateways in your Kubernetes cluster to enable Application Security monitoring. This eliminates the need for manual proxy configuration and provides API-wide security coverage without modifying individual services or deploying tracers across your application fleet.
37+
38+
### What is the Gateway Injector?
39+
40+
The Gateway Injector is a Kubernetes controller that:
41+
- **Automatically detects** supported proxies in your cluster (Envoy Gateway, Istio)
42+
- **Configures proxies** to route traffic through an external Application Security processor
43+
- **Enables threat detection** for all traffic passing through your ingress layer
44+
- **Simplifies operations** through centralized configuration with Helm
45+
46+
### Supported proxies
47+
48+
- **Envoy Gateway**: Automatically creates `EnvoyExtensionPolicy` resources
49+
- **Istio**: Automatically creates `EnvoyFilter` resources in the Istio system namespace
50+
51+
More proxies are available via manual installation on the global [setup page][10].
52+
53+
## Limitations
54+
55+
- Requires Datadog Cluster Agent 7.73.0 or later
56+
- External processor must be manually deployed and scaled
57+
- Deployed service may require an appropriate network policy:
58+
- From the proxy pods on the service port
59+
- To the Datadog Agent for traces
60+
- For specific proxy version compatibility, see:
61+
- [Envoy Gateway compatibility][8]
62+
- [Istio compatibility][9]
63+
64+
## Prerequisites
65+
66+
Before enabling the Security Injector, ensure you have:
67+
68+
- 1. A running Kubernetes cluster (version 1.20 or later)
69+
- 2. [Datadog Cluster Agent 7.73.0+][1] installed and configured in your cluster
70+
- 3. One or more supported proxies installed:
71+
- - [Envoy Gateway][2]
72+
- - [Istio][3]
73+
- 4. [Remote Configuration][4] enabled to allow blocking attackers through the Datadog UI
74+
75+
## How it works
76+
77+
The Gateway Injector operates in **External Mode**, where a single Application Security processor deployment serves all gateway traffic in your cluster.
78+
79+
### Architecture
80+
81+
- **External Processor Deployment**: You deploy a centralized Application Security processor as a Kubernetes Deployment with an associated Service.
82+
- **Automatic Proxy Detection**: The Injector controller watches for supported proxy resources in your cluster using Kubernetes informers.
83+
- **Automatic Configuration**: When proxies are detected, the injector creates the necessary configuration:
84+
- For Envoy Gateway: Creates `EnvoyExtensionPolicy` resources that reference the external processor service
85+
- For Istio: Creates `EnvoyFilter` resources in the Istio system namespace
86+
- **Traffic Processing**: Gateways route traffic to the external processor via the Kubernetes service for security analysis.
87+
88+
### Benefits
89+
90+
- **Resource Efficient**: A single shared processor handles traffic from all gateways
91+
- **Centralized Management**: One deployment to monitor, scale, and configure
92+
- **Infrastructure-as-Code**: Manage configuration through Helm values
93+
- **Non-Invasive**: No application code changes required
94+
- **Scalable**: Easily add new gateways without additional configuration
95+
96+
## Setup
97+
98+
### Step 1: Deploy the external processor
99+
100+
Deploy the Datadog Application Security external processor service. This processor analyzes traffic forwarded from your gateways.
101+
102+
For detailed deployment instructions and configuration options, see the [Envoy Gateway documentation][6] or [Istio documentation][7].
103+
104+
Example processor deployment:
105+
106+
```yaml
107+
apiVersion: apps/v1
108+
kind: Deployment
109+
metadata:
110+
name: datadog-aap-extproc-deployment
111+
namespace: datadog
112+
spec:
113+
replicas: 2
114+
selector:
115+
matchLabels:
116+
app: datadog-aap-extproc
117+
template:
118+
metadata:
119+
labels:
120+
app: datadog-aap-extproc
121+
spec:
122+
containers:
123+
- name: datadog-aap-extproc-container
124+
image: ghcr.io/datadog/dd-trace-go/service-extensions-callout:v2.4.0
125+
ports:
126+
- name: grpc
127+
containerPort: 443
128+
- name: health
129+
containerPort: 80
130+
env:
131+
# Use the address of the datadog agent service in your cluster
132+
- name: DD_AGENT_HOST
133+
value: "datadog-agent.datadog.svc.cluster.local"
134+
135+
- name: DD_SERVICE_EXTENSION_TLS
136+
value: "false"
137+
readinessProbe:
138+
httpGet:
139+
path: /
140+
port: health
141+
initialDelaySeconds: 5
142+
periodSeconds: 10
143+
livenessProbe:
144+
httpGet:
145+
path: /
146+
port: health
147+
initialDelaySeconds: 15
148+
periodSeconds: 20
149+
---
150+
apiVersion: v1
151+
kind: Service
152+
metadata:
153+
name: datadog-aap-extproc-service
154+
namespace: datadog
155+
spec:
156+
ports:
157+
- name: grpc
158+
port: 443
159+
targetPort: grpc
160+
selector:
161+
app: datadog-aap-extproc
162+
type: ClusterIP
163+
```
164+
165+
Apply the manifest:
166+
167+
```bash
168+
kubectl apply -f datadog-aap-extproc-service.yaml
169+
```
170+
171+
### Step 2: Configure the Injector
172+
173+
Enable the injector and configure it to use your external processor service.
174+
175+
Configure the Gateway Injector using Helm values. Add the following to your `values.yaml`:
176+
177+
```yaml
178+
datadog:
179+
appsec:
180+
injector:
181+
enabled: true
182+
183+
# Enable automatic proxy detection (enabled by default)
184+
autoDetect: true
185+
186+
# External processor configuration (required)
187+
processor:
188+
service:
189+
name: datadog-aap-extproc-service # Required: name of the processor service
190+
namespace: datadog # Optional: defaults to Cluster Agent namespace
191+
port: 443
192+
```
193+
194+
Install or upgrade the Datadog Helm chart:
195+
196+
```bash
197+
helm upgrade -i datadog-agent datadog/datadog -f values.yaml
198+
```
199+
200+
### Step 3: Verify installation
201+
202+
After applying your configuration, verify the injector is running:
203+
204+
```bash
205+
kubectl logs -n datadog deployment/datadog-cluster-agent | grep appsec
206+
```
207+
208+
Look for log messages indicating the injector has started and detected proxies.
209+
210+
#### Verify proxy configuration
211+
212+
For **Envoy Gateway**, check that `EnvoyExtensionPolicy` resources were created:
213+
214+
```bash
215+
kubectl get envoyextensionpolicy -A
216+
```
217+
218+
For **Istio**, check that `EnvoyFilter` resources were created:
219+
220+
```bash
221+
kubectl get envoyfilter -n istio-system
222+
```
223+
224+
The Injector will produce events for each operation done in the cluster whenever it resulted in failure or success.
225+
226+
#### Test traffic processing
227+
228+
Send requests through your gateway and verify they appear in the Datadog App and API Protection UI:
229+
230+
1. Navigate to [Security > Application Security][5] in Datadog.
231+
2. Look for security signals from your gateway traffic.
232+
3. Verify that threat detection is active.
233+
234+
## Configuration reference
235+
236+
### Injector options
237+
238+
| Parameter | Type | Default | Description |
239+
|-----------|------|---------|-------------|
240+
| `enabled` | Boolean | `false` | Enable or disable the Appsec Injector |
241+
| `autoDetect` | Boolean | `true` | Automatically detect and configure supported proxies |
242+
| `proxies` | Array | `[]` | Manual list of proxy types to configure. Valid values: `"envoy-gateway"`, `"istio"` |
243+
| `processor.service.name` | String | | **Required.** Name of the external processor Kubernetes Service |
244+
| `processor.service.namespace` | String | Cluster Agent namespace | Namespace where the external processor Service is deployed. Defaults to the namespace where the Cluster Agent is running |
245+
| `processor.address` | String | `{service.name}.{service.namespace}.svc` | (Optional) Full service address override |
246+
| `processor.port` | Integer | `443` | Port of the external processor service |
247+
248+
### Proxy types
249+
250+
- `envoy-gateway`: Configures Envoy Gateway using `EnvoyExtensionPolicy` resources
251+
- `istio`: Configures Istio using global `EnvoyFilter` resources in the Istio system namespace
252+
253+
### Opting out specific resources
254+
255+
You can exclude specific Gateway or GatewayClass resources from automatic Appsec Injector configuration by adding a label:
256+
257+
```yaml
258+
apiVersion: gateway.networking.k8s.io/v1
259+
kind: Gateway
260+
metadata:
261+
name: my-gateway
262+
namespace: my-namespace
263+
labels:
264+
appsec.datadoghq.com/enabled: "false" # Exclude this gateway from automatic configuration
265+
spec:
266+
# ... gateway configuration
267+
```
268+
269+
Resources with the `appsec.datadoghq.com/enabled: "false"` label will be ignored by the injector. This is useful when you want to:
270+
- Manually configure specific gateways
271+
- Temporarily disable Appsec for testing
272+
- Exclude certain gateways from security monitoring
273+
274+
**Note**: By default, all resources are included. Only resources with the label explicitly set to `"false"` are excluded.
275+
276+
## Troubleshooting
277+
278+
All errors are logs as Kubernetes events. Make sure to check for events on the Gateway or GatewayClass you wish to instrument.
279+
280+
### Injector not detecting proxies
281+
282+
**Symptom**: No `EnvoyExtensionPolicy` or `EnvoyFilter` resources are created.
283+
284+
**Solutions**:
285+
- Check that `autoDetect` is set to `true` or proxies are manually specified
286+
- Verify the Cluster Agent logs for proxy detection messages
287+
- Ensure your proxies are installed and have the expected Kubernetes resources (Gateway, GatewayClass)
288+
- Try manually specifying proxy types using the `proxies` parameter
289+
290+
### EnvoyExtensionPolicy or EnvoyFilter not created
291+
292+
**Symptom**: Injector is running but configuration resources are missing.
293+
294+
**Solutions**:
295+
- Check Cluster Agent logs for RBAC permission errors
296+
- Verify the Cluster Agent service account has permissions to create `EnvoyExtensionPolicy` or `EnvoyFilter` resources
297+
- Ensure the processor service exists and is accessible
298+
- Check for conflicting existing policies or filters
299+
300+
### Traffic not being processed
301+
302+
**Symptom**: No security events appear in the Datadog UI.
303+
304+
**Solutions**:
305+
- Verify the external processor deployment is running: `kubectl get pods -n datadog -l app=datadog-aap-extproc`
306+
- Look for warning logs in your reverse proxies concerning this part of the configuration.
307+
- Check processor logs for connection errors: `kubectl logs -n datadog -l app=datadog-aap-extproc`
308+
- Verify the processor service is correctly configured and resolvable
309+
- Test connectivity from gateway pods to the processor service
310+
- Ensure [Remote Configuration][4] is enabled in your Datadog Agent
311+
312+
### External processor connection issues
313+
314+
**Symptom**: Gateways cannot reach the external processor.
315+
316+
**Solutions**:
317+
- Verify the processor service name and namespace match your configuration
318+
- Check for NetworkPolicy rules blocking cross-namespace traffic
319+
- For Envoy Gateway: Ensure `ReferenceGrant` resources exist for cross-namespace service references
320+
- Test DNS resolution from gateway pods: `nslookup datadog-aap-extproc-service.datadog.svc.cluster.local`
321+
- Verify the processor port configuration matches the service definition
322+
323+
### RBAC permission errors
324+
325+
**Symptom**: Cluster Agent logs show permission denied errors.
326+
327+
**Solutions**:
328+
- Verify the Cluster Agent ClusterRole includes permissions for:
329+
- `gateway.envoyproxy.io/envoyextensionpolicies`
330+
- `networking.istio.io/envoyfilters`
331+
- `gateway.networking.k8s.io/gateways`
332+
- `gateway.networking.k8s.io/gatewayclasses`
333+
- Check that the ClusterRoleBinding references the correct service account
334+
- Make sure you are using the newest version of the Datadog Helm Chart or Operator.
335+
336+
## Further Reading
337+
338+
{{< partial name="whats-next/whats-next.html" >}}
339+
340+
[1]: /containers/kubernetes/installation/
341+
[2]: https://gateway.envoyproxy.io/
342+
[3]: https://istio.io/
343+
[4]: /agent/remote_config/?tab=helm#enabling-remote-configuration
344+
[5]: https://app.datadoghq.com/security/appsec
345+
[6]: /security/application_security/setup/kubernetes/envoy-gateway
346+
[7]: /security/application_security/setup/kubernetes/istio
347+
[8]: /security/application_security/setup/compatibility/envoy-gateway
348+
[9]: /security/application_security/setup/compatibility/istio
349+
[10]: /security/application_security/setup/kubernetes/

0 commit comments

Comments
 (0)