Pin MSE Governance Agent Version on ACK and ECS - Microservices Engine

Microservices Engine (MSE) uses the latest stable agent version by default. To maintain consistency across environments, lock down a tested release, or control upgrade timing, you can pin the agent to a specific version.

The method depends on your deployment environment:

Environment	Method	Summary
Container Service for Kubernetes (ACK)	Pod label	Add `aliyun.com/agent-version` to your deployment YAML
Elastic Compute Service (ECS)	Manual download	Download a specific agent package and configure it manually

Check the current agent version

Log on to the MSE console and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Governance > Application Governance.
On the Application list page, click the resource card of the target application.
In the left-side navigation pane, click Node details.
In the All Nodes section, click the target node. On the Basic Information tab, find the version in the Probe Version column.

Agent version displayed in the Probe Version column

Specify the agent version on ACK (ack-onepilot)

Use this method if your application runs on ACK with the ack-onepilot component.

Prerequisites

ack-onepilot component version later than 3.0.16. If the installed version is 3.0.16 or earlier, upgrade it by following Install and update the Microservices Governance component

Pin the agent version

Add the aliyun.com/agent-version label to the pod spec in your deployment YAML. The following example pins the agent to version 4.2.5:

spec:
  template:
    metadata:
      labels:
        aliyun.com/agent-version: "4.2.5"
        mseNamespace: "default"                # MSE microservice namespace
        msePilotCreateAppName: "<yourAppName>"  # Replace with your application name

The following table describes the labels:

Label	Description	Required
`aliyun.com/agent-version`	Agent version to use (for example, `4.2.5`). When omitted, MSE uses the latest stable version.	No
`mseNamespace`	MSE microservice namespace the application belongs to	Yes
`msePilotCreateAppName`	Application name registered in MSE	Yes

Note

Before specifying a version, verify that the version exists by downloading the agent package from one of the following endpoints:

Public endpoint: http://arms-apm-${regionId}.oss-${regionId}.aliyuncs.com/${agentVersion}/ArmsAgent.zip
Internal endpoint: http://arms-apm-${regionId}.oss-${regionId}-internal.aliyuncs.com/${agentVersion}/ArmsAgent.zip

For a list of available versions, see Java agent versions.

To revert to the default behavior (latest stable version), remove the aliyun.com/agent-version label and restart the application.

Verify the result

After you apply the updated deployment and restart the application, confirm the agent version on the Node details page as described in the Check the current agent version section above.

Confirming the agent version after restart

Specify the agent version on ECS

If your application runs on ECS, download the agent package for the target version and enable Microservices Governance manually. For the complete setup procedure, see Enable Microservices Governance for microservice applications on ECS instances.

Download the agent package

Download the agent package from one of the following endpoints:

Public endpoint: http://arms-apm-${regionId}.oss-${regionId}.aliyuncs.com/${agentVersion}/ArmsAgent.zip
Internal endpoint: http://arms-apm-${regionId}.oss-${regionId}-internal.aliyuncs.com/${agentVersion}/ArmsAgent.zip

Replace the placeholders with your values:

Placeholder	Description	Example
`${regionId}`	Region ID where the application is deployed	`cn-hangzhou`, `ap-southeast-1`
`${agentVersion}`	Target agent version	`4.2.5`

Note

Use the internal endpoint in a Virtual Private Cloud (VPC) environment and the public endpoint in a non-VPC environment. For supported regions, see Supported regions. For available agent versions, see Java agent versions.

Note

To download the agent package for applications in the China East 1 Finance region, submit a ticket.