Specify the version of ARMS agents - Application Real-Time Monitoring Service

The ack-onepilot component manages the automatic update of Application Real-Time Monitoring Service (ARMS) agents in Kubernetes clusters. To maintain a specific agent version instead of following automatic updates, use this guide to lock an agent version. After successful validation in your test environment, perform phased agent version updates across all applications.

Solution 1 (recommended): Manually specify an agent version

Required ack-onepilot version

The ack-onepilot must be V3.0.17 or later.

To view the ack-onepilot version of a Container Service for Kubernetes (ACK) cluster, go to the ACK console, click Add-ons, find ack-onepilot, and check its version. If the version does not meet the requirement, click Upgrade to update it.

Specify an agent version by modifying the label field in the application YAML file. This operation will override the automatic update of the ARMS agent, ensuring that the agent of the specified version is used.

Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Agent Management > Agent Release Notes to view the available online agent versions. We recommend that you select the latest version.
On the Agent Online Status tab, check the current agent version of your application for rollback if necessary.
Specify the agent version for your application.
Note
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 has a higher priority than that specified by method 1.
- Method 1: Modify the application YAML file. Add "aliyun.com/agent-version: Agent version" under the labels field and click Update. The application will automatically restart to apply the modification.
  This modification only takes effect on the current application. For other applications, modify their YAML files accordingly.
  If the ack-onepilot component is V3.3.0 or later, you can control the agent version in progressive update mode by adding the following label under aliyun.com/agent-version.
```
aliyun.com/enable-progressive-update: 'true'
```
  Note
  When you re-deploy a workload (Deployment or StateSet) in an ACK cluster in progressive update mode, the agent of only one to two instances is updated to the version specified by aliyun.com/agent-version. The version of the agent installed in other instances remain unchanged.
  If the application workload contains fewer than three replicas, progressive update does not take effect. Even if you specify an agent version, all the replicas do not update to the specified version. In this case, we recommend that you do not enable progressive update for the workload.
- Method 2: When deploying an application to a Kubernetes cluster in the Enterprise Distributed Application Service (EDAS) console, specify the agent version in the Monitoring and Governance Configurations section on the Advanced Settings tab.
  Note
  To adjust the available agent versions, contact EDAS technical support.
- Method 3: If an application is created or deployed in a Kubernetes cluster by calling the InsertK8sApplication or DeployK8sApplication operation of the EDAS API, you can use the CustomAgentVersion parameter to specify the agent version for the application.
Verify the specified agent version in the test environment before you update the agents for other applications.
If the new agent version encounters issues, you can roll back the agent version by performing the operations in Step 3.

Solution 2: Contact technical support to specify an agent version

For ack-onepilot versions earlier than 3.0.17 or environments requiring manual YAML modifications, use version locking to migrate agents from deprecated or unsupported versions to the latest:

Select an application to verify the update in the test environment. Contact ARMS technical support to update the locked agent version of the application to the latest version. After the update is complete, restart the application to verify the update.
After the new version is verified in the test environment, contact ARMS technical support to update the locked agents in batches for clusters that need to be updated. After the new online version takes effect, restart the applications in batches.