The ack-onepilot component automatically updates Application Real-Time Monitoring Service (ARMS) agents in Kubernetes clusters. When you need to validate a new agent version before a broad rollout, or keep a specific version for stability, pin the agent to a fixed version instead of accepting automatic updates.
Choose a method based on the ack-onepilot version in your cluster:
| Task | Method | ack-onepilot version |
|---|---|---|
| Pin a specific agent version (self-service) | Specify the version through a label or API | V3.0.17 or later |
| Roll out a version to a subset of instances first | Enable progressive update | V3.3.0 or later |
| Pin a version when self-service is not available | Contact technical support | Earlier than V3.0.17 |
Specify an agent version
Required: ack-onepilot V3.0.17 or later. To check the version, go to the Container Service Management Console, click Add-ons, find ack-onepilot, and check its version. If an upgrade is available, click Upgrade.
This is the recommended approach for controlling agent versions. Three methods are available. If you use both Method 1 and Method 2, or both Method 1 and Method 3, the version specified by Method 2 or Method 3 takes priority over Method 1.
Step 1: Find the target agent version
Log on to the ARMS console.
In the left-side navigation pane, choose .
Note the version number to use. Select the latest stable version unless your environment requires a specific version.
On the Agent Online Status tab, record the current agent version of each application. This version serves as the rollback target if issues arise.
Step 2: Apply the version
Choose one of the following methods.
Method 1: YAML label
Add the aliyun.com/agent-version label to the application YAML file:
metadata:
labels:
aliyun.com/agent-version: "<agent-version>"Replace <agent-version> with the version number from Step 1.
After you save the file and click Update, the application restarts automatically to apply the specified version.
This label applies only to the current application. Repeat this step for each application that requires version pinning.
Method 2: EDAS console
When deploying an application to a Kubernetes cluster through the Enterprise Distributed Application Service (EDAS) console, specify the agent version in the Monitoring and Governance Configurations section on the Advanced Settings tab.
To adjust the available agent versions in EDAS, contact EDAS technical support.
Method 3: EDAS API
When creating or deploying an application through the EDAS API, set the CustomAgentVersion parameter in the InsertK8sApplication or DeployK8sApplication operation.
Step 3: Verify and roll out
Apply the version to a test application first.
Validate that the application runs as expected with the new agent version.
After validation succeeds, repeat Step 2 for the remaining applications.
If the new agent version causes issues, change the label or parameter back to the previous version recorded in Step 1 to roll back.
Enable progressive update
Required: ack-onepilot V3.3.0 or later. The application workload must have three or more replicas.
Progressive update lets you validate a new agent version on a small subset of instances before it reaches the full workload.
Add both labels to the application YAML:
metadata:
labels:
aliyun.com/agent-version: "<agent-version>"
aliyun.com/enable-progressive-update: "true"When you redeploy a Deployment or StatefulSet workload in an ACK cluster with progressive update enabled, only one to two instances receive the specified agent version. The remaining instances keep their current version.
Limitations
Progressive update requires at least three replicas. If the workload has fewer than three replicas, no instances update to the specified version even if the label is set. In this case, do not enable progressive update for the workload.
Progressive update applies only to Deployment and StatefulSet workloads.
Contact technical support to pin a version
Use this method if ack-onepilot is earlier than V3.0.17 or if your environment requires manual YAML modifications. This approach uses version locking to migrate agents from deprecated or unsupported versions to the latest.
Select a test application. Contact ARMS technical support to lock the agent to the target version.
Restart the test application and validate the new agent version.
After validation succeeds, contact ARMS technical support to update the locked version across the remaining clusters in batches.
Restart the applications in each batch to apply the update.
Best practices
Validate before broad rollout: Pin the new version on a single test application first. Confirm normal operation before updating the remaining applications.
Use progressive update for production workloads: For workloads with three or more replicas, enable progressive update to limit the blast radius during version changes.
Record current versions before changes: Before pinning a new version, note the current agent version on the Agent Online Status tab so you can roll back quickly.
Keep ack-onepilot up to date: Upgrade ack-onepilot to V3.0.17 or later to access self-service version pinning, or to V3.3.0 or later for progressive update, without relying on technical support.