diff --git a/content/en/tracing/guide/injectors.md b/content/en/tracing/guide/injectors.md index 623443e84fb..08c1b422021 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 attach the volumes needed to persist the injected SDKs. -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. 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]. ### 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..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,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