Microservices Engine (MSE) governance adds traffic management, canary releases, graceful startup and shutdown, and throttling to your Spring Cloud and Dubbo applications -- without code changes. This guide walks you through connecting applications deployed in Container Service for Kubernetes (ACK) or Container Compute Service (ACS) to the MSE governance center.
How it works
MSE uses the ack-onepilot component to inject a Java agent into your application pods automatically. The agent connects each pod to the MSE governance center.
You enable governance at one of two levels:
| Approach | When to use | What happens |
|---|---|---|
| Namespace-level access | All or most applications in a namespace need governance | Every new or redeployed pod in the namespace is automatically connected |
| Single-application access | Only a few applications need governance | You explicitly opt in each application through YAML labels |
Prerequisites
Before you begin, make sure that you have:
An ACK managed cluster, ACK Serverless cluster, or ACS cluster. To create an ACK managed cluster, see Create an ACK managed cluster
MSE microservice governance enabled for your account
The ACK or ACS cluster and the MSE governance center in the same region
At least 256 MB of JVM heap memory for each application to be connected
(If using a RAM user) The permissions described in RAM user permissions for MSE integration
Verify cluster permissions
The ACK cluster must have permissions to access MSE resources. If the cluster has an ARMS add-on token, MSE grants password-free authorization automatically. ACK managed clusters include this token by default, but some older clusters may not.
To check for the ARMS add-on token:
Log on to the Container Service for Kubernetes console. On the Clusters page, click the target cluster name.
In the left-side navigation pane, choose Configuration Management > Secrets.
Set Namespace to kube-system and look for addon.arms.token.
If the token does not exist, you must manually grant the required permissions.
If your project uses the open-source Sentinel component together with
com.alibaba.cloud.sentinel.feign.SentinelFeignAutoConfiguration, the connection to the MSE governance center fails.After ack-onepilot is installed, the injected agent may increase application startup time by up to 10 seconds.
Enable governance for all applications in a namespace
After you enable governance at the namespace level, every new or redeployed pod in that namespace connects to the MSE governance center automatically. No per-application configuration is required.
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 ACK Application Access.
In the ACK Application Access dialog box, configure the following parameters, and then click OK.
| Parameter | Description |
|---|---|
| Cluster type | Select ACK Cluster, ACK Serverless Cluster, or ACS Cluster. If you have not authorized Container Service for Kubernetes to call MSE, click Please Authorize to grant the AliyunCSManagedMseRole role. |
| Cluster Name/ID | Select the cluster to connect. Search by keyword if needed. |
| ack-onepilot | Displays the component status. If ack-onepilot is installed, the console displays "Installed" followed by the version number, for example, Installed 4.2.0. If ack-onepilot is not installed, the system installs it automatically when you select the cluster. If your RAM user does not have the required permissions, install it manually: open the Container Service for Kubernetes console, go to the cluster details page, click Add-ons, find ack-onepilot, and click Install. For version details, see ack-onepilot component and Install and upgrade the MSE microservice governance component. |
| Access Type | Select Namespace Access. |
| Cluster Namespace | Select the namespace that contains your applications. |
| Microservices Governance Namespace | Select the MSE governance namespace to associate with your cluster namespace. |
If you connect by namespace and your 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), Shanghai-Finance Cloud, China (Shenzhen), Hong Kong (China), Singapore, Germany (Frankfurt), Australia (Sydney), US (Silicon Valley), and US (Virginia).
Customize the application display name
By default, the MSE console uses the deployment name as the application display name. To set a custom name, add the following labels to the deployment YAML:
spec:
template:
metadata:
labels:
# MSE governance namespace. Default: default
mseNamespace: default
# Custom application name displayed in the MSE console
msePilotCreateAppName: "your-deployment-name"Exclude an application from namespace-level governance
To opt out a specific application from namespace-level governance, add the msePilotAutoEnable label set to "off":
spec:
template:
metadata:
labels:
# Disable MSE governance for this application. The value must be quoted.
msePilotAutoEnable: "off"Enable governance for a single application
If only a few applications in your namespace need governance, connect them individually rather than enabling namespace-level access.
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 ACK Application Access.
In the ACK Application Access dialog box, configure the following parameters, and then click OK.
| Parameter | Description |
|---|---|
| Cluster type | Select ACK Cluster, ACK Serverless Cluster, or ACS Cluster. If you have not authorized Container Service for Kubernetes to call MSE, click Please Authorize to grant the AliyunCSManagedMseRole role. |
| Cluster Name/ID | Select the cluster to connect. Search by keyword if needed. |
| ack-onepilot | Displays the component status. If ack-onepilot is installed, the console displays "Installed" followed by the version number, for example, Installed 4.2.0. If ack-onepilot is not installed, the system installs it automatically when you select the cluster. If your RAM user does not have the required permissions, install it manually: open the Container Service for Kubernetes console, go to the cluster details page, click Add-ons, find ack-onepilot, and click Install. |
| Access Type | Select Single Application Access. |
Configure the application deployment YAML in the Container Service for Kubernetes console:
Go to Workloads > Deployments and switch to the namespace of your application.
Find the target application and click View In YAML.
Add the following labels and click Update:
spec:
template:
metadata:
labels:
# Enable MSE governance. The value must be quoted.
msePilotAutoEnable: "on"
# MSE governance namespace. If the namespace does not exist, it is created automatically.
mseNamespace: default
# Application name displayed in the MSE console. Must be quoted.
msePilotCreateAppName: "your-deployment-name"Verify the connection
After completing the configuration, restart your application and verify the connection:
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.
Select the target microservices governance namespace from the namespace dropdown.
Confirm that your application appears in the list with an active status.
If your application does not appear, check the following:
| Symptom | Possible cause | Resolution |
|---|---|---|
| Application not listed | Application was not restarted after configuration | Restart or redeploy the application |
| Application not listed | ack-onepilot is not installed or not running | Open the ACK console, go to Add-ons, and verify ack-onepilot status |
| Application not listed | Cluster and MSE governance center are in different regions | Create a new cluster in the same region or select the matching region in the MSE console |
| Application not listed | JVM heap memory is below 256 MB | Increase the JVM heap memory to at least 256 MB |
| Connection fails | Project uses the Sentinel component with SentinelFeignAutoConfiguration | Remove the Sentinel auto-configuration from your project |
What to do next
With your application connected to the MSE governance center, you can use features such as end-to-end canary release, graceful startup and shutdown, and traffic throttling. For more information, see Get started with service governance in 15 minutes (Java).
YAML label reference
| Label | Values | Purpose |
|---|---|---|
msePilotAutoEnable | "on" / "off" | Enable or disable MSE governance for a specific application |
mseNamespace | Any string (default: default) | MSE governance namespace for the application |
msePilotCreateAppName | Any string | Custom application display name in the MSE console |
All label values that contain lowercase alphabetic strings (such as "on" and "off") must be enclosed in double quotes in the YAML file to prevent them from being interpreted as booleans.