Automate ASM Lifecycle with servicemesh-operator - Container Service for Kubernetes

The servicemesh-operator component automates the deployment and lifecycle management of Alibaba Cloud Service Mesh (ASM) in a Container Service for Kubernetes (ACK) cluster. After installation, it handles provisioning, cluster enrollment, and configuration syncing — so you interact with ASM entirely through Kubernetes-native custom resources instead of switching between consoles. This enables you to quickly enable powerful ASM features such as traffic management, security, and observability.

Prerequisites

Before you begin, ensure that you have:

An ACK cluster running Kubernetes 1.28 or later
An activated ASM instance

How it works

Installing servicemesh-operator triggers the following sequence automatically:

A controller named servicemesh-operator is deployed in the cluster control plane. It watches for and reconciles ServiceMesh custom resources.
The CustomResourceDefinition (CRD) servicemesh.istio.alibabacloud.com is created.
A ServiceMesh custom resource (CR) named mesh is created automatically.
The controller provisions a Standard Edition ASM instance named mesh-for-${cluster ID} and enrolls the ACK cluster into it.

After provisioning completes, query the mesh CR to track progress and monitor the current state.

Monitor ASM instance status

Console

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

On the Custom Resources page, search for ServiceMesh. In the results, click the ServiceMesh name under istio.alibabacloud.com. Click Actions > 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

Get the cluster kubeconfig and connect with kubectl.

View 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

Reading the status conditions

The controller reconciles the ASM instance through four ordered steps. Each step appears as a condition in status.conditions. A healthy instance shows all four conditions with status: "True":

Condition type	What it means	Expected reason
`PreChecked`	Pre-flight checks passed	`Passed`
`ServiceMeshAvailable`	ASM instance is provisioned and available	`Available`
`ClusterEnrolled`	ACK cluster is enrolled into the ASM instance	`Succeeded`
`MeshConfigApplied`	Mesh configuration is applied to the cluster	`Succeeded`

If a condition shows status: "False" or status: "Unknown", check the message field on that condition for details on what failed.

Limitations

servicemesh-operator supports only a one-to-one binding between an ASM instance and an ACK cluster. To update an existing ASM instance, use the ASM console.
Standard Edition is free but has no Service-Level Agreement (SLA), supports up to 50 pods, and is available only in the Chinese mainland. Creating a Standard Edition instance in other regions fails. To use a different edition, set .spec.clusterSpec to Enterprise or Ultimate in the ServiceMesh CR. For billing details, see Billing overview.

Warning

Deleting a ServiceMesh CR removes the ACK cluster from ASM. If the cluster is actively using ASM resources such as gateways or Sidecar proxies, the removal fails. Check status.conditions to confirm the current state before deleting.

Warning

The deletion annotation controls whether the ASM instance itself is deleted when the ServiceMesh CR is removed. Set this annotation intentionally — the default behavior is Retain. See Deletion policy for details.

ServiceMesh CRD reference

The ServiceMesh resource defines the desired and actual state of an ASM service mesh in a Kubernetes cluster. Some .spec fields 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 set, the system generates one. Specify this to create a new service mesh or add the cluster to an existing mesh. Takes precedence over `name`.	N/A	No	No
`name`	string	The service mesh name. If not set, defaults to `mesh-for-${cluster ID}`. Specify this to create a new service mesh or add the cluster to an existing mesh.	N/A	No	Yes
`clusterSpec`	string	The ASM edition. Valid values: `Standard`, `Enterprise`, `Ultimate`.	`Standard` (Chinese mainland) / `Enterprise` (other regions)	No	Yes

Status (.status)

Field	Type	Description
`serviceMeshName`	string	The unique name of the ASM instance created by the controller. Recorded before the first creation request and immutable during reconciliation to prevent duplicate instances.
`serviceMeshId`	string	The ID of the successfully created ASM instance, retrieved from Alibaba Cloud after provisioning.
`clusterSpec`	string	The edition of the ASM instance that was created.
`conditions`	[]ServiceMeshCondition	The ordered list of reconciliation steps and their current statuses.

ServiceMeshCondition

Field	Type	Description
`lastTransitionTime`	metav1.Time	The timestamp when this condition last changed status.
`status`	string	`True` (condition met), `False` (condition not met), or `Unknown`.
`type`	string	The reconciliation step: `PreChecked`, `ServiceMeshAvailable`, `ClusterEnrolled`, `MeshConfigApplied`, `Retried`, or `ServiceMeshDeleted`.
`message`	string	Additional context about the condition, especially useful when a step fails.
`reason`	string	A machine-readable reason code: `Reconciling`, `Succeeded`, `Failed`, `Available`, `Unavailable`, `Passed`, `WaitSteady`, or `Retried`.

Special annotations

Retry

When a reconciliation error occurs, set the operator.istio.alibabacloud.com/retry-at annotation to trigger a retry:

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

The controller automatically retries the failed operation.

Deletion policy

Use the operator.istio.alibabacloud.com/deletion-policy annotation to control what happens to the ASM instance when the ServiceMesh CR is deleted:

Retain (default): The ASM instance remains in Alibaba Cloud.
Delete: The ASM instance is deleted from Alibaba Cloud.

Set this annotation when creating the resource:

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

Important

If the annotation is set to Delete, deleting the ACK cluster also deletes the ASM instance.