servicemesh-operator - Container Service for Kubernetes - Alibaba Cloud Documentation Center

The servicemesh-operator component simplifies the deployment, upgrade, and configuration management of Service Mesh (ASM) in an ACK cluster. This lets you quickly enable powerful ASM features, such as traffic management, security, and observability.

Scope

ACK clusters must be version 1.28 or later.
You have activated ASM.

Instructions

After you install the servicemesh-operator component in an ACK cluster, the system automatically deploys the following:

A controller named servicemesh-operator is deployed to the cluster. The controller runs on the control plane of the cluster and is responsible for monitoring and processing custom resources related to Service Mesh.
The servicemesh.istio.alibabacloud.com CustomResourceDefinition (CRD) is created.
A ServiceMesh Custom Resource (CR) named `mesh` is automatically created.

The servicemesh-operator controller creates a Standard Edition ASM instance named mesh-for-${cluster-ID} and adds the ACK cluster to the instance after it is created.

You can query the ServiceMesh CR to monitor the creation progress and current status of the ASM instance in real time.

Console

On the ACK Clusters page, click the name of the target cluster. In the left navigation pane, choose Workloads > Custom Resources.

On the Custom Resources page, search for ServiceMesh. In the search results, locate the ServiceMesh resource under istio.alibabacloud.com and click Edit YAML in the Actions column.

The following is a sample YAML file:

apiVersion: istio.alibabacloud.com/v1beta1
kind: ServiceMesh
metadata:
  annotations:
    operator.istio.alibabacloud.com/deletion-policy: Retain
  creationTimestamp: "2026-01-09T02:25:12Z"
  finalizers:
  - servicemeshoperator.finalizers.alibabacloud.com
  generation: 2
  name: asm
  resourceVersion: "36619976"
  uid: 94967e01-fc25-477e-9da9-4df42cede8ba
spec:
  clusterSpec: Enterprise
status:
  clusterSpec: Enterprise
  conditions:
  - lastTransitionTime: "2026-01-09T02:25:19Z"
    message: ""
    observedGeneration: 2
    reason: Passed
    status: "True"
    type: PreChecked
  - lastTransitionTime: "2026-01-09T02:25:32Z"
    message: ""
    observedGeneration: 2
    reason: Available
    status: "True"
    type: ServiceMeshAvailable
  - lastTransitionTime: "2026-01-09T02:25:32Z"
    message: ""
    observedGeneration: 2
    reason: Succeeded
    status: "True"
    type: ClusterEnrolled
  - lastTransitionTime: "2026-01-09T02:25:38Z"
    message: ""
    observedGeneration: 2
    reason: Succeeded
    status: "True"
    type: MeshConfigApplied
  serviceMeshId: c6490deb776cc458c82c4c22a69315bae
  serviceMeshName: mesh-for-cf17b23e9fa6b4fb081c58a33964cd3dc

kubectl

Obtain the cluster's KubeConfig file and use kubectl to connect to the cluster.

You can view the YAML file of the ServiceMesh CR.

kubectl get servicemesh mesh -n istio-system -o yaml

Expected output:

apiVersion: istio.alibabacloud.com/v1beta1
kind: ServiceMesh
metadata:
  annotations:
    operator.istio.alibabacloud.com/deletion-policy: Retain
  creationTimestamp: "2026-01-09T02:25:12Z"
  finalizers:
  - servicemeshoperator.finalizers.alibabacloud.com
  generation: 2
  name: asm
  resourceVersion: "36619976"
  uid: 94967e01-fc25-477e-9da9-4df42cede8ba
spec:
  clusterSpec: Enterprise
status:
  clusterSpec: Enterprise
  conditions:
  - lastTransitionTime: "2026-01-09T02:25:19Z"
    message: ""
    observedGeneration: 2
    reason: Passed
    status: "True"
    type: PreChecked
  - lastTransitionTime: "2026-01-09T02:25:32Z"
    message: ""
    observedGeneration: 2
    reason: Available
    status: "True"
    type: ServiceMeshAvailable
  - lastTransitionTime: "2026-01-09T02:25:32Z"
    message: ""
    observedGeneration: 2
    reason: Succeeded
    status: "True"
    type: ClusterEnrolled
  - lastTransitionTime: "2026-01-09T02:25:38Z"
    message: ""
    observedGeneration: 2
    reason: Succeeded
    status: "True"
    type: MeshConfigApplied
  serviceMeshId: c6490deb776cc458c82c4c22a69315bae
  serviceMeshName: mesh-for-cf17b23e9fa6b4fb081c58a33964cd3dc

Quotas and limits

The current version of servicemesh-operator supports only a one-to-one mapping between an ASM instance and an ACK cluster. To update an ASM instance, go to the ASM console.
When you delete a ServiceMesh resource, the corresponding ACK cluster is removed from the ASM instance. If the ACK cluster uses ASM resources such as gateways or sidecar proxies, the removal operation fails. You can view the current status in the Status field of the ServiceMesh resource.
If a ServiceMesh resource contains the operator.istio.alibabacloud.com/deletion-policy: Delete annotation, the corresponding ASM instance is also deleted when the ACK cluster is deleted. Otherwise, the ASM instance is retained.
By default, this component creates a Standard Edition ASM instance. This edition is free, provides no Service-Level Agreement (SLA), and supports a maximum cluster size of 50 pods. The Standard Edition is available only in the Chinese mainland. If you try to create a Standard Edition instance in other regions or countries, the operation fails. To create or upgrade an instance, change the .spec.clusterSpec field of the ServiceMesh resource to Enterprise or Ultimate. For more information about editions and billing, see Billing.

ServiceMesh CRD details

The ServiceMesh resource defines the desired and actual states for declaring and managing an ASM service mesh in a Kubernetes cluster. Some fields in the spec are mutable. Modifying these fields triggers changes to the corresponding mesh properties.

Spec (.spec)

Field	Type	Description	Default	Required	Mutable
`id`	string	The ID of the service mesh. If you do not specify an ID, the system generates a random one. Specify this ID to create a new service mesh or add the current cluster to an existing mesh. This field has a higher priority than the `name` field.	N/A	No	No
`name`	string	The name of the service mesh. If you do not specify a name, the system generates one in the format `mesh-for-${cluster-ID}`. Specify this name to create a new service mesh or add the current cluster to an existing mesh.	N/A	No	Yes
`clusterSpec`	string	The edition of the created service mesh instance. It defines the features and performance level of the instance. Valid values: Standard Enterprise Edition Ultimate	Standard for regions in the Chinese mainland Enterprise for other regions or countries	No	Yes

Status (.status)

Field	Type	Description
`serviceMeshName`	string	The unique name of the actual service mesh created by the controller. This field is recorded before the initial creation request is sent and is immutable throughout the reconciliation process to prevent the creation of duplicate service mesh instances.
`serviceMeshId`	string	The ID of the successfully created service mesh. This value is retrieved from the cloud after the service mesh instance is created.
`clusterSpec`	string	Service Mesh instance specifications.
`conditions`	[]ServiceMeshCondition	A list of conditions and their statuses that the service mesh goes through during the reconciliation process. It provides a detailed record of the key steps from resource creation to readiness.

ServiceMeshCondition

Field	Type	Description
`lastTransitionTime`	metav1.Time	The timestamp of the last time the condition's status changed.
`status`	string	The current status of the condition. Valid values: True: The condition is met. False Unknown
`type`	string	The type of condition, which represents a specific step in the reconciliation process. Examples: PreChecked ServiceMeshAvailable: The service mesh is available. ClusterEnrolled: The cluster is enrolled. MeshConfigApplied: The mesh configuration is applied. Retried: The retry status. ServiceMeshDeleted: The service mesh is deleted.
`message`	string	An informational message about the condition's status. It is typically used to provide additional context when an error occurs or when the resource is in a specific state.
`reason`	string	The reason for the condition's status. Examples: Reconciling: The resource is being updated. Succeeded: The operation is successful. The operation failed. Available. Unavailable: The resource is unavailable. Passed. WaitSteady: Waiting for the mesh update to complete. Retried: The operation was retried.

Special annotations

The ServiceMesh resource supports special annotations for configuration. The following annotations are supported:

Retry

Use the operator.istio.alibabacloud.com/retry-at annotation to trigger a retry of the reconciliation process. If an error occurs during reconciliation, set this annotation to trigger a retry.

kubectl annotate servicemesh mesh operator.istio.alibabacloud.com/retry-at=""

After you run this command, a retry is automatically triggered.

Deletion policy

Use the operator.istio.alibabacloud.com/deletion-policy annotation to configure the deletion policy:

Retain (Default): When the ServiceMesh resource is deleted, the ASM instance in Alibaba Cloud is retained.
Delete: When the ServiceMesh resource is deleted, the ASM instance is also deleted from Alibaba Cloud.

apiVersion: istio.alibabacloud.com/v1beta1
kind: ServiceMesh
metadata:
  name: advanced-mesh
  annotations:
    operator.istio.alibabacloud.com/deletion-policy: Delete  # or Retain
spec:
  name: advanced-service-mesh
  clusterSpec: Ultimate