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

The servicemesh-operator component simplifies deploying, upgrading, and managing configurations for Alibaba Cloud Service Mesh (ASM) in an ACK cluster. This enables you to quickly enable powerful ASM features such as traffic management, security, and observability.

Scope

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

Usage

After you install the servicemesh-operator component in your ACK cluster, the system automatically performs the following steps:

Deploys a controller named servicemesh-operator in the cluster control plane. This controller listens for and processes ServiceMesh custom resources.
Creates the CustomResourceDefinition (CRD): servicemesh.istio.alibabacloud.com.
Automatically creates a ServiceMesh custom resource (CR) named mesh.

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

Query the ServiceMesh custom resource to monitor the ASM instance creation progress and current status in real time.

Console

On the ACK Clusters page, click the name of your cluster. On the cluster details page, in the navigation pane on the left, click Workloads > Custom Resources.

On the Custom Resources page, search for ServiceMesh. In the list below, click the ServiceMesh name under istio.alibabacloud.com. Then click Actions and select Edit YAML.

Sample YAML:

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 KubeConfig and connect to the cluster using kubectl.

View the ServiceMesh custom resource YAML.

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 one-to-one binding between an ASM instance and an ACK cluster. To update an ASM instance, go to the ASM console.
Deleting a ServiceMesh resource removes the ACK cluster from ASM. If the ACK cluster uses ASM resources such as gateways or Sidecar proxies, the removal fails. Check the current status in the ServiceMesh resource Status field.
If the ServiceMesh resource includes the annotation operator.istio.alibabacloud.com/deletion-policy: Delete, deleting the ACK cluster also deletes the ASM instance. Otherwise, the ASM instance is retained.
This component creates a Standard Edition ASM instance by default. Standard Edition is free but has no Service-Level Agreement (SLA). It supports up to 50 pods. Standard Edition is available only in regions in the Chinese mainland. Creating a Standard Edition instance in other regions fails. To create or upgrade to a different edition, set the ServiceMesh resource .spec.clusterSpec to Enterprise or Ultimate. For more information about editions and billing, see Billing overview.

ServiceMesh CRD reference

The ServiceMesh resource defines the desired and actual state of an ASM service mesh in a Kubernetes cluster. Some fields in Spec are mutable. Changing them triggers updates to the corresponding mesh properties.

Spec (.spec)

Field	Type	Description	Default	Required	Mutable
`id`	string	The service mesh ID. If not specified, the system generates a random ID. You can specify this ID to create a new service mesh or add the current cluster to an existing mesh. This field takes precedence over the name field.	N/A	No	No
`name`	string	The service mesh name. If not specified, the system generates a name in the format `mesh-for-${cluster ID}`. You can 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 initial edition of the created service mesh instance. It defines the mesh instance's features and performance level. Valid values are: Standard Enterprise Edition. Ultimate	Standard in regions in the Chinese mainland Enterprise in other regions	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 first creation request is sent and remains immutable during reconciliation to prevent 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	The specifications of the Service Mesh instance created.
`conditions`	[]ServiceMeshCondition	A list of conditions and their statuses that the service mesh goes through during reconciliation. It records key steps from resource creation to readiness.

ServiceMeshCondition

Field	Type	Description
`lastTransitionTime`	metav1.Time	The timestamp when the condition status last changed.
`status`	string	The current condition status. Valid values are: True (condition met) False (condition not met) Unknown (status unknown)
`type`	string	The condition type, representing a specific reconciliation step. Examples include the following: PreChecked (precheck complete) ServiceMeshAvailable (service mesh available) ClusterEnrolled (cluster enrolled) MeshConfigApplied (mesh configuration applied) Retried (retry status) ServiceMeshDeleted (service mesh deleted)
`message`	string	A descriptive message about the condition status. This provides additional context during errors or specific states.
`reason`	string	The reason for the condition status. Examples include the following: Reconciling (updating) Succeeded (success) Failed (failure) Available (available) Unavailable (unavailable) Passed (passed) WaitSteady (waiting for mesh update to complete) Retried (retried)

Special annotations

The ServiceMesh resource supports special annotations for configuration. Currently supported annotations include the following:

Retry

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

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

After running this command, the system automatically retries the operation.

Deletion policy

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

Retain (default): Retains the ASM instance in Alibaba Cloud when the ServiceMesh resource is deleted.
Delete: Deletes the ASM instance from Alibaba Cloud when the ServiceMesh resource is deleted.

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