Connect ACK microservice applications to the MSE governance center - Microservices Engine

Microservices Engine (MSE) provides a series of service governance capabilities for Spring Cloud and Dubbo applications running in Container Service for Kubernetes (ACK) or Container Compute Service (ACS) clusters. This helps improve the stability and development efficiency of online microservice applications. The ack-onepilot component injects a Java agent into your application pods to enable Microservices Governance.

Two access patterns control how the agent is injected:

Access pattern	When to use	Scope
Namespace access	Most applications in the namespace need governance	All pods in the selected Kubernetes namespace
Single application access	Only a few applications need governance	Individual Deployments you label

Prerequisites

Before you begin, make sure that you have:

An ACK cluster (dedicated, managed, or Serverless) or an ACS cluster. See Create an ACK dedicated cluster, Create an ACK managed cluster, or Create an ACK Serverless cluster
Microservices Governance activated
A JVM heap size greater than 256 MB for each application pod

Important

If your project uses both the open-source Sentinel library and com.alibaba.cloud.sentinel.feign.SentinelFeignAutoConfiguration, Microservices Governance may fail to start.

Label reference

The following Kubernetes labels control agent injection behavior. Add them under spec.template.metadata.labels in your Deployment YAML.

Label	Values	Default	Description
`msePilotAutoEnable`	`"on"` / `"off"`	--	Enables or disables governance for a specific application. Values must be quoted.
`mseNamespace`	Any string	`default`	MSE microservice namespace. If the specified namespace does not exist, it is created automatically.
`msePilotCreateAppName`	Any string	Deployment name	Application name displayed in the MSE console. Must be quoted.

Enable governance for all applications in a namespace

Use namespace access when most applications in a Kubernetes namespace need Microservices Governance. To exclude specific applications later, set msePilotAutoEnable: "off" on those Deployments.

Log on to the MSE console and select a region.
In the left-side navigation pane, choose Microservices Governance > Application Governance.
On the Application list page, click ACK Application Access.

In the ACK Application Access dialog box, configure the following parameters and click OK.

Namespace access dialog

Parameter	Description
Cluster type	Select ACK Cluster, ACK Serverless Cluster, or ACS Cluster. If the cluster has not been authorized to call MSE, click the authorization link to grant the AliyunCSManagedMseRole role.
Cluster Name/ID	Select the target cluster. Search by name or ID if needed.
ack-onepilot	Shows the component status. If not installed, click Click Install. After installation, the status changes to Installed. If you are a RAM user without the required permissions, log on to the ACK console, navigate to Operations > Add-ons, find ack-onepilot, and click Install.
Access Type	Select Namespace Access.
ACK Cluster Namespace	Select the Kubernetes namespace.
Microservices Governance Namespace	Select the MSE microservice namespace.

Redeploy existing applications or create new applications in the namespace.
Note
After ack-onepilot is installed, expect pod startup time to increase by up to 10 seconds.

Customize the application name

By default, the application name in the MSE console matches the Deployment name. To override it, add labels to the Deployment YAML:

spec:
  template:
    metadata:
      labels:
        mseNamespace: default                       # MSE microservice namespace
        msePilotCreateAppName: "your-deployment-name"      # Custom application name

Exclude an application from namespace-level governance

To prevent the agent from being injected into a specific application in a governed namespace, add the following label:

spec:
  template:
    metadata:
      labels:
        msePilotAutoEnable: "off"    # Must be quoted

Enable governance for a single application

Use single application access when only a few applications in a namespace need Microservices Governance.

Log on to the MSE console and select a region.
In the left-side navigation pane, choose Microservices Governance > Application Governance.
On the Application list page, click ACK Application Access.

In the ACK Application Access dialog box, configure the following parameters and click OK.

Single application access dialog

Parameter	Description
Cluster type	Select ACK Cluster, ACK Serverless Cluster, or ACS Cluster. If the cluster has not been authorized to call MSE, click the authorization link to grant the AliyunCSManagedMseRole role.
Cluster Name/ID	Select the target cluster. Search by name or ID if needed.
ack-onepilot	Shows the component status. If not installed, click Click Install. After installation, the status changes to Installed. If you are a RAM user without the required permissions, log on to the ACK console, navigate to Operations > Add-ons, find ack-onepilot, and click Install.
Access Type	Select Single Application Access.

Add governance labels to your Deployment YAML:

In the ACK console, navigate to Workloads > Deployments and select the target namespace.
Click the application name, then click View in YAML.
Add the following labels and click Update:

   spec:
     template:
       metadata:
         labels:
           msePilotAutoEnable: "on"                    # Enable governance (must be quoted)
           mseNamespace: 202401                         # MSE microservice namespace
           msePilotCreateAppName: "your-deployment-name"       # Application name (must be quoted)

Redeploy the application for the agent injection to take effect.

Verify the result

After you enable Microservices Governance and redeploy your applications:

Log on to the MSE console and select a region.
In the left-side navigation pane, choose Microservices Governance > Application Governance.
Select the MSE microservice namespace. Your governed applications appear in the list.

Limits

Item	Limit
JVM heap size	Must be greater than 256 MB
Pod startup overhead	Up to 10 seconds after ack-onepilot is installed
Sentinel conflict	If both the open-source Sentinel library and `SentinelFeignAutoConfiguration` are used, governance may fail to start

Network requirements for unsupported regions (namespace access)

If you want to enable Microservices Governance for applications in an ACK or ACS cluster namespace and the cluster is not in one of the following regions, it must have Internet access and be able to connect to acm.aliyun.com:8080:

China (Qingdao), China (Hangzhou), China (Beijing), China (Shanghai), China East 2 Finance, China (Shenzhen), China (Hong Kong), Singapore, Germany (Frankfurt), Australia (Sydney), US (Silicon Valley), US (Virginia)