Add sidecar mode documentation for AAP Kubernetes injector#35547
Add sidecar mode documentation for AAP Kubernetes injector#35547eliottness merged 5 commits intomasterfrom
Conversation
Document the new sidecar deployment mode for App and API Protection on Kubernetes alongside the existing external mode. External mode remains the recommended approach. Key changes: - appsec.md: Add sidecar mode section, update Helm snippets with mode: "external", add istio-gateway proxy type, sidecar config reference table - istio.md: Rewrite automated config to use sidecar mode only, link to main page for external mode - envoy-gateway.md: Add mode: "external" to Helm snippets - All pages: Rename "external processor" to "security processor", fix vale warnings, apply style guide fixes
Sidecar mode requires Cluster Agent 7.76.0, not 7.73.0. External mode minimum (7.73.0) is unchanged.
Reference-style links don't resolve inside Hugo tab shortcodes. Use inline link instead.
- istio.md: replace placeholder with annotation + env override for sidecar mode - appsec.md, envoy-gateway.md: add DD_CLUSTER_AGENT_APPSEC_INJECTOR_MODE=external to existing Operator snippets since sidecar is now the default mode The annotation agent.datadoghq.com/appsec.injector.enabled is required for RBAC. The mode env var is set via spec.override.clusterAgent.env until the Operator exposes a dedicated field.
janine-c
left a comment
janine-c
left a comment
There was a problem hiding this comment.
Looks great, Eliott, thank you! The vast majority of my comments are standardizing things like capitalization or fixing up some funky Markdown rendering. If I can clarify anything or help you implement any of my suggestions, don't hesitate to reach out!
| ### Sidecar mode | ||
| - Requires Datadog Cluster Agent 7.76.0 or later | ||
| - Each gateway pod runs its own processor instance, which increases per-pod resource usage | ||
| - Datadog Operator does not yet support sidecar mode configuration |
There was a problem hiding this comment.
| - Datadog Operator does not yet support sidecar mode configuration | |
| - Datadog Operator does not support sidecar mode configuration |
Just to be on the safe side, I like to avoid temporal language like this, in case we wind up deprioritizing this in the future 🙂
There was a problem hiding this comment.
The operator is being released with it next week with this 😄
| - Check that the ClusterRoleBinding references the correct service account | ||
| - Make sure you are using the newest version of the Datadog Helm Chart or Operator. | ||
|
|
||
| ## Sidecar mode |
There was a problem hiding this comment.
| ## Sidecar mode | |
| ## Set up sidecar mode |
Updating the header so it doesn't conflict with the "Sidecar mode" header in the limitations section
| App and API Protection for Kubernetes supports two deployment modes: | ||
|
|
||
| - **External mode** (recommended): A single, centralized Application Security processor deployment serves all gateway traffic in your cluster. This is the preferred approach for most environments. | ||
| - **Sidecar mode**: The Application Security processor runs as a sidecar container injected directly into each gateway pod. No separate processor deployment is needed. See [Sidecar mode](#sidecar-mode) for setup details. |
There was a problem hiding this comment.
| - **Sidecar mode**: The Application Security processor runs as a sidecar container injected directly into each gateway pod. No separate processor deployment is needed. See [Sidecar mode](#sidecar-mode) for setup details. | |
| - **Sidecar mode**: The Application Security processor runs as a sidecar container injected directly into each gateway pod. No separate processor deployment is needed. See [Set up sidecar mode](#set-up-sidecar-mode) for setup details. |
This link was going up to the "Sidecar mode" section in the limitations section 🙂 I made a suggestion below to update the setup heading so links won't conflict anymore.
| - **Sidecar mode**: The Application Security processor runs as a sidecar container injected directly into each gateway pod. No separate processor deployment is needed. See [Sidecar mode](#sidecar-mode) for setup details. | ||
|
|
||
| ### Architecture | ||
| The following sections describe the external mode architecture and setup. For sidecar mode, skip to [Sidecar mode](#sidecar-mode). |
There was a problem hiding this comment.
I'm a little concerned that someone might do something like search for "app and API protection kubernetes architecture" and get directly linked to a section under this disclaimer, and therefore miss it. It's one of the evergreen challenges of creating docs; people rarely read everything in order 🙃 How would you feel about creating an "External mode" heading with all this under it, so it's parallel to the "Sidecar mode" section?
We could also think about popping the sidecar information into a collapsible section that's collapsed by default, if you want to emphasize external over sidecar instructions.
| ``` | ||
|
|
||
| The Datadog Cluster Agent will produce events for each operation done in the cluster whenever it resulted in failure or success. | ||
| The Datadog Cluster Agent produces events for each operation done in the cluster whenever it results in failure or success. |
There was a problem hiding this comment.
| The Datadog Cluster Agent produces events for each operation done in the cluster whenever it results in failure or success. | |
| The Datadog Cluster Agent produces events for each operation that results in failure or success done in the cluster. |
This was quite a noun-heavy sentence, so by the end, it was a little hard to figure out what "it" referred to (the Agent, the operation, or the cluster). I think maybe this is clearer?
| address: | ||
| socket_address: | ||
| # Address of the Datadog External Processor service | ||
| # Address of the Datadog Security Processor service |
There was a problem hiding this comment.
| # Address of the Datadog Security Processor service | |
| # Address of the Datadog security processor service |
| #observability_mode: true | ||
| ## Optional: When in asynchronous mode, the message_timeout is not used. This deferred | ||
| ## timeout starts when the http request is finished, to let the External Processor | ||
| ## timeout starts when the http request is finished, to let the Security Processor |
There was a problem hiding this comment.
| ## timeout starts when the http request is finished, to let the Security Processor | |
| ## timeout starts when the http request is finished, to let the security processor |
| address: | ||
| socket_address: | ||
| # Address of the Datadog External Processor service | ||
| # Address of the Datadog Security Processor service |
There was a problem hiding this comment.
| # Address of the Datadog Security Processor service | |
| # Address of the Datadog security processor service |
| {{< /tabs >}} | ||
|
|
||
| After applying the chosen `EnvoyFilter`, traffic passing through your Istio Ingress Gateway or selected sidecars will be processed by the Datadog External Processor service, enabling App and API Protection features. | ||
| After you apply the `EnvoyFilter`, traffic through your Istio Ingress Gateway or selected sidecars is processed by the Datadog Security Processor. |
There was a problem hiding this comment.
| After you apply the `EnvoyFilter`, traffic through your Istio Ingress Gateway or selected sidecars is processed by the Datadog Security Processor. | |
| After you apply the `EnvoyFilter`, the Datadog security processor starts processing traffic through your Istio Ingress Gateway or selected sidecars. |
Alternatively, handling instead of processing so we can avoid using "process" twice?
| Known limitations: | ||
|
|
||
| * Inspection of request and response bodies is supported when using the Datadog External Processor image version `v2.2.2` or later. | ||
| * Inspection of request and response bodies is supported when using the Datadog Security Processor image version `v2.2.2` or later. |
There was a problem hiding this comment.
| Known limitations: | |
| * Inspection of request and response bodies is supported when using the Datadog External Processor image version `v2.2.2` or later. | |
| * Inspection of request and response bodies is supported when using the Datadog Security Processor image version `v2.2.2` or later. | |
| Inspection of request and response bodies is supported when using the Datadog security processor image version `v2.2.2` or later. |
janine-c
left a comment
janine-c
left a comment
There was a problem hiding this comment.
Looks great, Eliott, thank you! The vast majority of my comments are standardizing things like capitalization or fixing up some funky Markdown rendering. If I can clarify anything or help you implement any of my suggestions, don't hesitate to reach out!
Signed-off-by: Eliott Bouhana <eliott.bouhana@datadoghq.com>
2 participants
What does this PR do? What is the motivation?
Documents the new sidecar deployment mode for App and API Protection (AAP) on Kubernetes, introduced in helm-charts#2494. The sidecar mode runs the security processor as a container injected directly into gateway pods, as an alternative to the existing external mode. Overall this PR also removes lot of AI-generated overly verbose language.
Changes by file:
content/en/containers/kubernetes/appsec.md(main page):mode: "external"to existing Helm snippets (external is no longer the default)istio-gatewayproxy type for native Istio Gateway resourcescontent/en/security/application_security/setup/kubernetes/istio.md:content/en/security/application_security/setup/kubernetes/envoy-gateway.md:mode: "external"to automated config Helm snippetAll pages: Renamed "external processor" to "security processor", fixed vale warnings, applied CONTRIBUTING.md style fixes
Merge instructions
Merge readiness:
Additional notes