Support Advisory: Transition of Java Agent DockerHub Images from Alpine to Scratch Base

Summary

Effective Java Agent 26.2.0, Splunk AppDynamics is transitioning the official JavaAgent DockerHub images from an Alpine-based image to a Scratch-based image. This change is part of an ongoing effort to enhance security by addressing vulnerabilities associated with the previous base image. The new Scratch-based image provides a significantly reduced attack surface, containing only the JavaAgent binaries and a minimal copy utility, with no shell present.

While a Scratch-based image was initially introduced in version 25.10.0, an Alpine-based version was temporarily re-released on November 14, 2025, to address compatibility issues involving Cluster Auto-Instrumentation and non-root user configurations. With the release of Cluster Agent version 26.2.0, these compatibility issues are resolved. Consequently, JavaAgent DockerHub releases 26.2.0 and later will be exclusively Scratch-based.

Key Characteristics of the Scratch Image

  • Includes only the Java Agent binaries and a minimal copy (cp) utility.
  • The cp command transfers files as defined in /opt/appdynamics/sources.ini from /opt/appdynamics to the destination directory.
  • The base destination directory must already exist; the cp command can create necessary subdirectories but will not create the root destination directory.
  • No shell or standard system utilities are included in the image.

Tag Changes and Image Selection Guidance

  • Version 26.2.0 and later: The latest tag now points to Scratch-based image.
  • Alpine-based images: To continue using Alpine-based image, use the latest-alpine tag or reference version 26.1.0 or earlier.
  • Recommended Action: Evaluate your deployment requirements and update your image tags to ensure compatibility with your preferred base image (Scratch or Alpine).

Compatibility Matrix & Required Actions

Review the compatibility matrix below and adjust your deployments as needed to ensure a smooth transition.

Table 1. For Auto-instrumentation Using Cluster Agent 26.2.0 or later
JavaAgent Image Version Required Action
Alpine-based (< 26.2.0) No action required
Scratch-based (≥ 26.2.0) No action required
Table 2. For Auto-Instrumentation Using Cluster Agent 26.1.0 or earlier
JavaAgent Image Version App Run As Required Action / Notes
Alpine-based (< 26.2.0) Any No action required
Scratch-based (≥ 26.2.0) Root No changes needed
Scratch-based (≥ 26.2.0) Non-root (with runAsUser / runAsGroup parameters in Cluster Agent Conifg) Mitigation required:

  • Remove runAsUser/runAsGroup parameters from Cluster Agent config.

  • Set a non-root user writable runtime directory by using:
    • ENV: APPDYNAMICS_AGENT_BASE_DIR or
    • Java System Property: appdynamics.agent.runtime.dir
    Example:
    CODE 
    containers:
- name: appcontainer8081
  env:
  - name: APPDYNAMICS_AGENT_BASE_DIR
    value: /opt/jalogs
Table 3. For Manual Init-Container Approach
JavaAgent Image Version App Run As Required Action / Notes
Alpine-based (< 26.2.0) Any No action required
Scratch-based (≥ 26.2.0) Root Use only -r with cp command: [ "cp", "-r", "/opt/appdynamics/.", "/opt/appdynamics-java" ]
Scratch-based (≥ 26.2.0) Non-root Mitigation required:
  • Use only -r with cp command: [ "cp", "-r", "/opt/appdynamics/.", "/opt/appdynamics-java" ]
  • Ensure Java Agent has write access, using one of the following methods:
    • Set Env variable APPDYNAMICS_AGENT_BASE_DIR or Java System Property, appdynamics.agent.runtime.dir to a non-root user writable runtime directory.
      CODE 
      containers:
- name: appcontainer8081
  env:
  - name: APPDYNAMICS_AGENT_BASE_DIR
    value: /opt/jalogs
    • Specify securityContext for the init container:
    CODE 
    initContainers:
  - name: appd-agent
    image: appdynamics/java-agent:26.2.0
    securityContext:
      runAsUser: 1001
      runAsGroup: 1001
    command:
      - cp
      - -r
      - /opt/appdynamics/.
      - /opt/appdynamics-java
    volumeMounts:
      - name: appd-agent-repo
        mountPath: /opt/appdynamics-java

Next Steps

  • Review your current deployment method and JavaAgent/Cluster Agent versions.
  • Apply the specified mitigations when upgrading to version 26.2.0 or later in environments with non-root configurations.
  • Contact your AppDynamics representative for further assistance or clarification.
Note:

  • For specific YAML or manifest guidance, contact AppDynamics support.

  • Verify shell or utility dependencies for deployments using custom scripts because these are not available in the Scratch-based image.