From 8e91adb811bb719e20a510bbaaea2547eb161137 Mon Sep 17 00:00:00 2001 From: "dominique.alessi" Date: Fri, 17 Jul 2026 14:50:52 -0400 Subject: [PATCH 1/3] Document CSI driver as the default SSI injection mode on Kubernetes Make CSI-based injection the documented default over init containers, add the CSI mechanism explanation to the injector guide, and complete the Helm/Operator configuration examples. Co-Authored-By: Claude Opus 4.8 --- content/en/tracing/guide/injectors.md | 13 ++++--- .../single-step-apm/kubernetes.md | 36 +++++++++++-------- 2 files changed, 28 insertions(+), 21 deletions(-) diff --git a/content/en/tracing/guide/injectors.md b/content/en/tracing/guide/injectors.md index 623443e84fb..01c4fbce1d0 100644 --- a/content/en/tracing/guide/injectors.md +++ b/content/en/tracing/guide/injectors.md @@ -32,12 +32,11 @@ To enable this, Datadog provides a custom `runc` shim that replaces Docker's def In Kubernetes environments, injection is handled by the Datadog Admission Controller, which uses a mutating admission webhook. When a pod is scheduled, the controller: 1. Evaluates whether the pod should be instrumented based on configured selectors (such as namespaces, labels, or specific pod properties). -1. Mutates the pod spec to: - - Use the Datadog CSI driver to mount the injector and SDKs - - Set environment variables (such as `LD_PRELOAD`) - - Mount volumes to persist injected libraries +1. Mutates the pod spec to mount the injector and SDKs, set environment variables (such as `LD_PRELOAD`), and mount the volumes needed to persist the injected libraries. -The default delivery method uses init containers, but SSI supports additional [injection modes][2] that may better suit your environment. +How the injector and SDK files are delivered depends on the configured [injection mode][2]. By default, SSI uses the Datadog CSI driver: a DaemonSet runs on every node, and when a pod is scheduled, the driver mounts the SDK directly from the node's file system into the container. No init container is created, and nothing needs to run before the application starts. The first time an SDK is used on a node, it's downloaded and cached; every subsequent pod on that node mounts the SDK from the cache. This lowers resource overhead and reduces pod startup time at scale. + +Alternatively, SSI can deliver the injector and SDK files using init containers. For details on each mode and how to configure it, see [injection modes][2]. ### Windows @@ -83,7 +82,7 @@ SSI instruments applications by loading a tracer or profiler into the applicatio While the injected code runs inside the application process, some deployment modes update OS or runtime configuration so that the injector loads automatically: -- **Kubernetes admission controller injection**: Mutates pod specs to mount the injector (using an init container or the [Datadog CSI driver][2]) and set environment variables. This is a Kubernetes API action, not a host OS modification. +- **Kubernetes admission controller injection**: Mutates pod specs to mount the injector (using the [Datadog CSI driver][2] by default, or an init container) and set environment variables. This is a Kubernetes API action, not a host OS modification. - **Linux host injection**: Configures the dynamic loader (typically through `/etc/ld.so.preload`) so that every new dynamically linked process loads the injection launcher. This is an OS-level configuration change, but it remains user-space dynamic linking, not kernel code. - **Docker runtime injection**: Configures Docker to use a wrapper runtime so that containers start with the tracer mounted and configured (typically by injecting an `LD_PRELOAD` environment variable into the container). This modifies Docker daemon configuration. - **Windows injection**: Installs a kernel driver that loads the injector DLL into new processes. The driver runs at the OS level. The injected code that runs inside each application process remains user-space. @@ -103,7 +102,7 @@ Privilege requirements at install time depend on the deployment mode: - Volume mounts used to communicate with the Agent (commonly a `hostPath` mount to a socket directory). - Specific `SecurityContext` or SCC allowances. - You can keep the injected init container and application container locked down (non-root, dropped capabilities, no privilege escalation) as long as your policies permit the required mounts. + You can keep the application container (and the init container, if you use `init_container` mode) locked down (non-root, dropped capabilities, no privilege escalation) as long as your policies permit the required mounts. #### Linux host diff --git a/content/en/tracing/trace_collection/single-step-apm/kubernetes.md b/content/en/tracing/trace_collection/single-step-apm/kubernetes.md index 0b9c791c936..c7783c2bbc1 100644 --- a/content/en/tracing/trace_collection/single-step-apm/kubernetes.md +++ b/content/en/tracing/trace_collection/single-step-apm/kubernetes.md @@ -167,42 +167,50 @@ SSI supports multiple injection modes, which control how the injector and APM li | Mode | Description | Requirements | |------|-------------|--------------| -| `init_container` | Uses init containers to copy injector and APM library files into application containers. | Agent deployed with Helm Chart or Datadog Operator | -| `csi` | **In Preview.** Mounts injector and APM library files using the [Datadog CSI driver][37]. Reduces pod startup time compared to init container mode. | Agent 7.76.0+, CSI driver 1.2.0+, Helm Chart 3.178.1+ or Datadog Operator 1.25.0+ | +| `csi` | **Default.** Mounts injector and APM library files using the [Datadog CSI driver][37]. Reduces pod startup time compared to init container mode. | Agent 7.76.0+, CSI driver 1.2.0+, Helm Chart 3.178.1+ or Datadog Operator 1.28.0+ | +| `init_container` | Uses init containers to copy injector and APM library files into application containers. Use this mode in environments that don't support the CSI driver. | Agent deployed with Helm Chart or Datadog Operator | -Before using `csi` mode, install and activate the Datadog CSI driver. If you are deploying with Helm, also set `datadog.csi.enabled: true` in your `datadog-values.yaml`. See the [CSI driver documentation][37] for installation steps and environment-specific requirements such as GKE Autopilot. +The `csi` mode requires the Datadog CSI driver. If you deploy with Helm, set `datadog.csi.enabled: true` in your `datadog-values.yaml` to install and activate it. See the [CSI driver documentation][37] for installation steps and environment-specific requirements. + +
The csi injection mode is not supported on GKE Autopilot. On GKE Autopilot clusters, use init_container mode.
#### Configure injection mode globally {{< tabs >}} {{% tab "Helm" %}} -To set the injection mode cluster-wide, add `injectionMode` to your `datadog-values.yaml`: +To set the injection mode cluster-wide, add `injectionMode` to your `datadog-values.yaml`. For `csi` mode, also enable the CSI driver with `datadog.csi.enabled`: ```yaml datadog: + csi: + enabled: true apm: instrumentation: - injectionMode: + injectionMode: csi ``` -Supported values: `init_container`, `csi`. +Supported values: `csi` (default), `init_container`. {{% /tab %}} {{% tab "Datadog Operator" %}} -To set the injection mode cluster-wide, add `injectionMode` to your `datadog-agent.yaml`: +To set the injection mode cluster-wide, add `injectionMode` to your `datadog-agent.yaml`. For `csi` mode, also enable the CSI driver with `global.csi.enabled`: ```yaml -features: - apm: - instrumentation: - injectionMode: +spec: + global: + csi: + enabled: true + features: + apm: + instrumentation: + injectionMode: csi ``` -Supported values: `init_container`, `csi`. +Supported values: `csi` (default), `init_container`. -If you are using Datadog Operator earlier than 1.25.0, use the [pod annotation](#configure-injection-mode-per-pod) to override the injection mode for specific pods. +If you are using Datadog Operator earlier than 1.28.0, use the [pod annotation](#configure-injection-mode-per-pod) to override the injection mode for specific pods. {{% /tab %}} {{< /tabs >}} @@ -217,7 +225,7 @@ metadata: admission.datadoghq.com/apm-inject.injection-mode: "" ``` -Supported values: `init_container`, `csi`. +Supported values: `auto`, `init_container`, `csi`. Use `auto` to apply the cluster's default injection mode. ### Target specific workloads From c8c4fe8683d6aca858f37a6ec0cd80064fb57c01 Mon Sep 17 00:00:00 2001 From: domalessi <111786334+domalessi@users.noreply.github.com> Date: Fri, 17 Jul 2026 15:02:28 -0400 Subject: [PATCH 2/3] Apply suggestion from @domalessi --- content/en/tracing/guide/injectors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/tracing/guide/injectors.md b/content/en/tracing/guide/injectors.md index 01c4fbce1d0..8414f72c671 100644 --- a/content/en/tracing/guide/injectors.md +++ b/content/en/tracing/guide/injectors.md @@ -34,7 +34,7 @@ In Kubernetes environments, injection is handled by the Datadog Admission Contro 1. Evaluates whether the pod should be instrumented based on configured selectors (such as namespaces, labels, or specific pod properties). 1. Mutates the pod spec to mount the injector and SDKs, set environment variables (such as `LD_PRELOAD`), and mount the volumes needed to persist the injected libraries. -How the injector and SDK files are delivered depends on the configured [injection mode][2]. By default, SSI uses the Datadog CSI driver: a DaemonSet runs on every node, and when a pod is scheduled, the driver mounts the SDK directly from the node's file system into the container. No init container is created, and nothing needs to run before the application starts. The first time an SDK is used on a node, it's downloaded and cached; every subsequent pod on that node mounts the SDK from the cache. This lowers resource overhead and reduces pod startup time at scale. +How the injector and SDK files are delivered depends on the configured [injection mode][2]. By default, SSI uses the Datadog CSI driver: a DaemonSet runs on every node, and when a pod is scheduled, the driver mounts the SDK directly from the node's file system into the container. No init container is created, and nothing needs to run before the application starts. The first time an SDK is used on a node, it is downloaded and cached; every subsequent pod on that node mounts the SDK from the cache. This lowers resource overhead and reduces pod startup time at scale. Alternatively, SSI can deliver the injector and SDK files using init containers. For details on each mode and how to configure it, see [injection modes][2]. From d57367908a5125abe34c6cd5b0220b66c9721e8e Mon Sep 17 00:00:00 2001 From: "dominique.alessi" Date: Fri, 17 Jul 2026 15:22:53 -0400 Subject: [PATCH 3/3] Apply editorial review fixes to SSI CSI docs Split a long sentence in the injector guide, align terminology, and use code formatting for init_container mode reference. Co-Authored-By: Claude Opus 4.8 --- content/en/tracing/guide/injectors.md | 4 ++-- .../en/tracing/trace_collection/single-step-apm/kubernetes.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/tracing/guide/injectors.md b/content/en/tracing/guide/injectors.md index 8414f72c671..08c1b422021 100644 --- a/content/en/tracing/guide/injectors.md +++ b/content/en/tracing/guide/injectors.md @@ -32,9 +32,9 @@ To enable this, Datadog provides a custom `runc` shim that replaces Docker's def In Kubernetes environments, injection is handled by the Datadog Admission Controller, which uses a mutating admission webhook. When a pod is scheduled, the controller: 1. Evaluates whether the pod should be instrumented based on configured selectors (such as namespaces, labels, or specific pod properties). -1. Mutates the pod spec to mount the injector and SDKs, set environment variables (such as `LD_PRELOAD`), and mount the volumes needed to persist the injected libraries. +1. Mutates the pod spec to mount the injector and SDKs, set environment variables (such as `LD_PRELOAD`), and attach the volumes needed to persist the injected SDKs. -How the injector and SDK files are delivered depends on the configured [injection mode][2]. By default, SSI uses the Datadog CSI driver: a DaemonSet runs on every node, and when a pod is scheduled, the driver mounts the SDK directly from the node's file system into the container. No init container is created, and nothing needs to run before the application starts. The first time an SDK is used on a node, it is downloaded and cached; every subsequent pod on that node mounts the SDK from the cache. This lowers resource overhead and reduces pod startup time at scale. +How the injector and SDK files are delivered depends on the configured [injection mode][2]. By default, SSI uses the Datadog CSI driver. A DaemonSet runs on every node. When a pod is scheduled, the driver mounts the SDK directly from the node's file system into the container, so no init container is created and nothing needs to run before the application starts. The first time an SDK is used on a node, it is downloaded and cached. Every subsequent pod on that node mounts the SDK from the cache. This lowers resource overhead and reduces pod startup time at scale. Alternatively, SSI can deliver the injector and SDK files using init containers. For details on each mode and how to configure it, see [injection modes][2]. diff --git a/content/en/tracing/trace_collection/single-step-apm/kubernetes.md b/content/en/tracing/trace_collection/single-step-apm/kubernetes.md index c7783c2bbc1..0dc07e8ae92 100644 --- a/content/en/tracing/trace_collection/single-step-apm/kubernetes.md +++ b/content/en/tracing/trace_collection/single-step-apm/kubernetes.md @@ -167,7 +167,7 @@ SSI supports multiple injection modes, which control how the injector and APM li | Mode | Description | Requirements | |------|-------------|--------------| -| `csi` | **Default.** Mounts injector and APM library files using the [Datadog CSI driver][37]. Reduces pod startup time compared to init container mode. | Agent 7.76.0+, CSI driver 1.2.0+, Helm Chart 3.178.1+ or Datadog Operator 1.28.0+ | +| `csi` | **Default.** Mounts injector and APM library files using the [Datadog CSI driver][37]. Reduces pod startup time compared to `init_container` mode. | Agent 7.76.0+, CSI driver 1.2.0+, Helm Chart 3.178.1+ or Datadog Operator 1.28.0+ | | `init_container` | Uses init containers to copy injector and APM library files into application containers. Use this mode in environments that don't support the CSI driver. | Agent deployed with Helm Chart or Datadog Operator | The `csi` mode requires the Datadog CSI driver. If you deploy with Helm, set `datadog.csi.enabled: true` in your `datadog-values.yaml` to install and activate it. See the [CSI driver documentation][37] for installation steps and environment-specific requirements.