cloudNativeFullStack applicationMonitoring
On Kubernetes 1.35+, image volume injection is the recommended way to deliver OneAgent code modules to application pods. It requires no CSI driver, no privileged access, and the container runtime handles node-level caching natively. For clusters on older Kubernetes versions, ephemeral volume and CSI driver delivery remain available.
Notable use cases:
| Delivery mode | CSI driver enabled | Storage overhead | When it applies | Notes |
|---|---|---|---|---|
Image Volume Recommended | No, image volume | Node-level cache (via container runtime) | Recommended for Kubernetes 1.35+. Opt-in via | Best combination of storage efficiency and security posture. See Migrate to image volume. |
No, ephemeral volume | Per-pod storage consumption | Default since Operator v1.10 when no CSI driver is enabled | Uses Node credentials. Image cached on each node. | |
Yes, CSI volume | Node-level cache | CSI driver enabled | Requires | |
Yes, CSI volume | Node-level cache | CSI driver enabled. Opt-in via | Uses Node credentials alongside the |
Because images are pulled by the Kubernetes node using node-level credentials, no customPullSecret is needed for private registries as long as the nodes are already configured to authenticate against the registry. For details, see Prerequisites.
Each code modules delivery mode instruments the application pod using a different volume type.
| Image volume | Ephemeral volume | CSI volume | |
|---|---|---|---|
CSI driver required | No | No | Yes |
Storage of Code Modules binary | Node-level cache (managed by container runtime) | Per-pod (each pod gets its own copy) | Node-level cache (shared across pods on the same node) |
Credentials for private registries | Node credentials or pod-level | Node credentials or pod-level |
|
When to use | Kubernetes 1.35+ environment. Recommended for all new and existing deployments | Kubernetes version older than 1.35, or when image volumes are not yet available | Kubernetes version older than 1.35 with CSI driver already deployed |
Image volume injection is available from Kubernetes version 1.35+ and is the recommended delivery mode for new and existing deployments. The container runtime mounts the code modules image directly as a read-only volume in each injected pod. Because the runtime handles image caching at the node level, only one copy of the code modules image is stored per node regardless of how many pods are instrumented.
Image volume injection requires no CSI driver and no additional privileges, which makes it well suited for security-sensitive environments.
For setup instructions, see Use image volumes for code modules injection. To migrate an existing deployment, see Migrate to image volumes.
Add the feature.dynatrace.com/mount-code-modules-via-image-volume annotation to your DynaKube:
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubeannotations:feature.dynatrace.com/mount-code-modules-via-image-volume: "true"
When the CSI driver is not enabled, code modules are copied into the application pod's ephemeral volume.
Node Image Pull via Ephemeral Volume delivers OneAgent code modules by having the Kubernetes node pull the code modules image and copy the binaries into an ephemeral volume on each injected pod. No CSI driver is required, but each pod gets its own copy of the binaries, which increases per-pod storage consumption compared to node-level caching.
Since Dynatrace Operator version 1.10, Node Image Pull via ephemeral volumes is the default when no CSI driver is enabled. In previous versions, this behavior is gated by the feature.dynatrace.com/node-image-pull: "true" feature flag.
When using a private registry, the DynaKube customPullSecret does not apply to injected pods. Dynatrace Operator does not replicate pull secrets into application namespaces or add them to pods outside the dynatrace namespace. If the Kubernetes node is not authenticated to your private registry, the init container image pull fails. Ensure that all nodes are authenticated to the registry, or distribute a pull secret to your application namespaces, nodes, or pods. For details, see Provide pull secrets for injected workloads.
Enable automatic image resolution via the feature.dynatrace.com/use-public-registry annotation, or set the codeModulesImage field directly. For image sources and tag format, see Use a public registry or Use a private registry.
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubeannotations:feature.dynatrace.com/use-public-registry: "true" # enables automatic image resolution; omit if setting codeModulesImage manuallyspec:oneAgent:# example, can also be used with `cloudNativeFullStack`applicationMonitoring:codeModulesImage: <dynatrace-codemodules-image> # optional if resolved automatically
Deprecated as of Dynatrace Operator version 1.11. Not supported on Latest Dynatrace environments. Use Image Volume or Node Image Pull via Ephemeral Volume instead.
The injected init container downloads and unpacks the code module ZIP archive from your Dynatrace Environment into an ephemeral volume at pod startup. This delivery method is used when no code modules image is configured and the CSI driver is not enabled.
Drawbacks compared to image-based delivery:
Dynatrace Operator uses this mode automatically when no code modules image is set and the CSI driver is not enabled. Ensure that codeModulesImage is absent from your DynaKube, and that the automatic resolution does not apply:
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubespec:oneAgent:# example, can also be used with `applicationMonitoring`cloudNativeFullStack: {}
OneAgent version 1.315+
When code modules are delivered via ephemeral volumes, each injected pod receives its own copy of the code module binaries. To reduce storage consumption, you can scope injection to specific application technologies (for example, Java), preventing unnecessary binaries from being copied.
If storage optimization is not configured (that is, the oneagent.dynatrace.com/technologies annotation is missing), storage consumption follows the guidelines outlined in the storage requirements.
The technologies specified are copied into a shared volume, consuming ephemeral storage.
The following identifiers are available per technology:
To reduce the data copied into application pods, you can specify which OneAgent technologies are relevant for your application. Annotate your application pods as shown in the pod snippet below:
...metadata:annotations:oneagent.dynatrace.com/technologies: "java,nginx"
When specifying a comma-separated list of technology identifiers, ensure there are no whitespace characters within the annotation value.
Annotation values must use the exact technology identifiers listed in the table above.
If no oneagent.dynatrace.com/technologies annotation is provided, all technologies are copied to application pods.
If a single technology is used across your cluster, or if you want to set a default technology for Dynatrace code module injection, you can configure it at the DynaKube level to apply to all injected application pods.
Modify your DynaKube configuration by restricting code module injection to a specific technology or a set of multiple technologies:
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubeannotations:oneagent.dynatrace.com/technologies: "java"spec:...
When specifying a comma-separated list of technology identifiers, ensure there are no whitespace characters within the annotation value.
When code modules are delivered with the CSI driver, the code modules binaries are cached on the host filesystem and shared between pods, avoiding per-pod copies.
The CSI driver pulls the code modules image from a container image registry and exposes the code modules binaries on the host filesystem, where each injected application pod mounts them through a CSI volume.
customPullSecret. Note that customPullSecret does not apply to injected pods in application namespaces. For details, see Provide pull secrets for injected workloads.Enable automatic image resolution via the feature.dynatrace.com/use-public-registry annotation, or set the codeModulesImage field directly. For image sources and tag format, see Use a public registry or Use a private registry.
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubeannotations:feature.dynatrace.com/use-public-registry: "true" # enables automatic image resolution; omit if setting codeModulesImage manuallyspec:oneAgent:# example, can also be used with `cloudNativeFullStack`applicationMonitoring:codeModulesImage: <dynatrace-codemodules-image> # optional if resolved automatically
Dynatrace Operator version 1.5
The CSI driver schedules a pull job on each node where the container runtime pulls the code modules image directly. The code modules binaries are then exposed on the host filesystem, where each injected application pod mounts them through a CSI volume.
This approach simplifies Kubernetes-native integration with supply chain security tooling and reduces the need for a customPullSecret when sourcing images from private registries.2 Because the node pulls the image, ensure that the node is authenticated to the private registry. For details, see Provide pull secrets for injected workloads.
Since Dynatrace Operator version 1.10, the node-image-pull feature flag only affects the CSI driver. For ephemeral-volume deployments, Node Image Pull via Ephemeral Volume is the default.
Starting from Dynatrace Operator version 1.8, the download jobs inherit the same PriorityClass as the CSI driver to ensure fast scheduling and preemption on congested clusters. You can configure the value through csidriver.priorityClassValue in the Helm values file. For guidance, see Use priorityClass for critical Dynatrace components.
Enable the node-image-pull feature flag and the use-public-registry annotation for automatic image resolution, or set the codeModulesImage field directly. For image sources and tag format, see Use a public registry or Use a private registry.
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubeannotations:feature.dynatrace.com/node-image-pull: "true"feature.dynatrace.com/use-public-registry: "true" # enables automatic image resolution; omit if setting codeModulesImage manuallyspec:oneAgent:# example, can also be used with `cloudNativeFullStack`applicationMonitoring:codeModulesImage: <dynatrace-codemodules-image> # optional if resolved automatically
GKE Autopilot dynamically provisions nodes and their sizes based on the aggregated resource requests of pods. This makes GKE Autopilot unsuitable for the node image pull feature in combination with the CSI driver. Dynatrace recommends either disabling node image pull on GKE Autopilot with the CSI driver, or using ephemeral-volume delivery instead—see Node Image Pull via Ephemeral Volume.
Deprecated as of Dynatrace Operator version 1.11. Not supported on Latest Dynatrace environments. Use Image Volume or Node Image Pull via Ephemeral Volume instead.
The CSI driver downloads, extracts, and exposes the code modules ZIP on the host filesystem, where each injected application pod mounts them through a CSI volume. This delivery method is used when the CSI driver is enabled and no code modules image is configured.
Dynatrace Operator uses this mode automatically when the CSI driver is enabled and no code modules image is set. Ensure that codeModulesImage is absent from your DynaKube, and that the automatic resolution does not apply:
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubespec:oneAgent:# example, can also be used with `applicationMonitoring`cloudNativeFullStack: {}
applicationMonitoring cloudNativeFullStack OneAgent version 1.315+
You can selectively configure Dynatrace code module injection to use ephemeral volumes, even when the CSI driver is available on the node. In this case, code module injection behaves as described in Node Image Pull via Ephemeral Volume and Storage optimization.
To do this, use the oneagent.dynatrace.com/volume-type: "ephemeral" annotation on the Pod, as shown in the code block below. The oneagent.dynatrace.com/technologies annotation is an additional optimization—see Annotate the application pod.
metadata:annotations:oneagent.dynatrace.com/volume-type: "ephemeral" # no CSI driver involvedoneagent.dynatrace.com/technologies: "nginx" # minimize storage consumption
This approach combines the storage optimizations provided by the CSI driver with the performance gains and enhanced resiliency of ephemeral-volume injection for selected pods and applications.
Example scenarios: