Customize the mount path for a Java agent

By default, the ack-onepilot component injects the JAVA_TOOL_OPTIONS environment variable into your pods to set the Java agent mount path. To use a custom path instead -- for example, to manage agent paths through a Kubernetes ConfigMap or store agent files on a persistent volume claim (PVC) -- disable automatic injection and specify the path manually.

Prerequisites

Before you begin, make sure that you have:

ack-onepilot 4.1.0 or later
ARMS Java agent 4.2.2 or later (to pin a specific version, see Control the Java agent version)
kubectl access to your ACK cluster

How it works

In a standard deployment, ack-onepilot specifies the Java agent mount path by injecting the JAVA_TOOL_OPTIONS environment variable. The default path is /home/admin/.opt/AliyunJavaAgent/aliyun-java-agent.jar.

To use a custom mount path, add the disableJavaToolOptionsInjection: "true" label to your pod template. This tells ack-onepilot to stop injecting JAVA_TOOL_OPTIONS and other JVM parameters. Other environment variables such as the reporting region and license key are still injected. Then, specify the -javaagent flag in your application startup command to point to your custom path.

Procedure

Important

The ack-onepilot component is shared by Application Real-Time Monitoring Service (ARMS) and Microservice Engine (MSE). This procedure also applies to MSE service administration applications.

Step 1: Disable automatic JAVA_TOOL_OPTIONS injection

Add the disableJavaToolOptionsInjection label to the pod template of your Deployment or other workload.

Important

Add the labels under spec.template.metadata, not under the top-level spec.metadata. Labels on the workload itself do not affect pod injection behavior.

View the current Deployment configuration:
```
kubectl get deployment <your-deployment-name> -o yaml
```
Note
If you do not know the Deployment name, list all Deployments first:
```
kubectl get deployments --all-namespaces
```

Open the Deployment for editing:

kubectl edit deployment <your-deployment-name>

Under spec.template.metadata, set the following labels:

labels:
  armsPilotAutoEnable: "on"
  armsPilotCreateAppName: "<your-app-name>"               # Replace with your application name
  disableJavaToolOptionsInjection: "true"                  # Disables automatic JAVA_TOOL_OPTIONS injection

Save the file. Kubernetes rolls out new pods with the updated labels.

Step 2: Specify the custom agent path in your startup command

In your Dockerfile, entrypoint script, or Kubernetes container command, add the -javaagent flag with your custom path:

java -javaagent:<custom-agent-path>/aliyun-java-agent.jar -jar <your-application>.jar

Replace the following placeholders with your values:

Placeholder	Description	Example
`<custom-agent-path>`	Directory where the agent JAR is mounted	`/opt/arms-agent`
`<your-application>`	Application JAR file name	`myapp`

The default agent path is /home/admin/.opt/AliyunJavaAgent/aliyun-java-agent.jar. Replace it with the path to your custom-mounted agent JAR.

Note

Other configuration such as the reporting region and license key is still injected by ack-onepilot through environment variables. No additional configuration is required for these settings.

Step 3: Verify the configuration

After the new pods start, confirm that the custom path is in effect and automatic injection is disabled.

Check the pod's environment variables:
```
kubectl describe pod <pod-name> | grep JAVA_TOOL_OPTIONS
```
If disableJavaToolOptionsInjection is working correctly, JAVA_TOOL_OPTIONS does not appear in the output.
Check the application logs to confirm the agent loaded from your custom path:
```
kubectl logs <pod-name> | grep -i "javaagent"
```
Look for a log entry that shows the agent JAR path matches your custom location.

Common use cases

Use case	Description
Centralized configuration management	Store agent paths in a Kubernetes ConfigMap and reference them in container environment variables. This keeps the agent path configurable across multiple environments without modifying each Deployment individually.
Persistent storage	Mount a PVC to your pods and place the agent JAR at the mounted path. This approach meets enterprise security policies or O&M requirements that mandate storing agent files on persistent storage.

In both cases, set disableJavaToolOptionsInjection: "true" as described in this topic, then point the -javaagent flag to the path where the agent JAR is available in the container.