ASMMeshConfig CRD description
ASMMeshConfig is a custom resource definition (CRD) that controls mesh-wide settings for an Alibaba Cloud Service Mesh (ASM) instance. It provides functionality similar to Istio's MeshConfig, with centralized management of global defaults for connection timeouts, TCP keepalive, path normalization, HTTP retry policies, and Prometheus metrics merging.
All fields described on this page require ASM 1.24 or later. The metadata.name field must be set to default. Other names are not valid.
Sample configuration
The following YAML applies connection, keepalive, path normalization, retry, and monitoring settings at the mesh level:
apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMMeshConfig
metadata:
name: default
spec:
connectTimeout: 30s
tcpKeepalive:
probes: 5
time: 7200s
interval: 72s
pathNormalization:
normalization: MERGE_SLASHES
defaultHttpRetryPolicy:
attempts: 3
perTryTimeout: 1s
retryOn: gateway-error,connect-failure,refused-stream
enablePrometheusMerge: trueField reference
Connection timeout
The Envoy sidecar waits up to connectTimeout when establishing an outbound TCP connection. If the upstream does not respond within this window, Envoy returns an upstream connect timeout error to the caller.
| Field path | Type | Description | Example |
|---|---|---|---|
.spec.connectTimeout | Duration (ns/ms/s/m/h) | Maximum time the Envoy proxy waits to establish an outbound TCP connection. Returns upstream connect timeout on expiry. Applies to all mesh-level outbound TCP connections. | 30s |
Protocol detection timeout
.spec.protocolDetectionTimeout is configurable only in ASM 1.19 and earlier.
Envoy uses protocol sniffing to detect whether inbound traffic is HTTP or HTTPS. If detection does not complete within the specified timeout, the traffic is forwarded using its original protocol without HTTP-specific processing.
| Field path | Type | Description | Example |
|---|---|---|---|
.spec.protocolDetectionTimeout | Duration | Timeout for automatic HTTP/HTTPS protocol detection. After expiry, traffic is processed as its original protocol. Applies to mesh-level protocol sniffing. | 30s |
TCP keepalive
TCP keepalive probes are sent by the Envoy sidecar on idle outbound connections to detect broken connections early. After a connection has been idle for time, the sidecar sends up to probes keepalive packets, spaced interval apart. If none receive a response, the connection is closed.
| Field path | Type | Description | Example |
|---|---|---|---|
.spec.tcpKeepalive.probes | Uint32 | Number of keepalive probes to send before closing an unresponsive connection. Set to 0 to disable keepalive. | 9 |
.spec.tcpKeepalive.time | Duration | Idle time before the first keepalive probe is sent. | 7200s |
.spec.tcpKeepalive.interval | Duration | Time between consecutive keepalive probes. Must be less than time. | 75s |
All three fields apply to outbound persistent TCP connections at the mesh level.
Path normalization
Before evaluating HTTP routing rules, Envoy can normalize URI paths to prevent routing bypasses caused by inconsistent path formats (such as //a//b vs. /a/b). Choose a normalization mode based on how strictly your routing rules depend on exact path matching.
| Field path | Type | Description | Example |
|---|---|---|---|
.spec.pathNormalization.normalization | Enum | URI path normalization mode applied to all mesh-level HTTP routing. See the following table for supported values. | NONE |
Supported values
| Value | Behavior |
|---|---|
NONE | No normalization. Paths are forwarded as-is. |
BASE | Merge slashes and retain path parameters (such as ;). |
MERGE_SLASHES | Only merge consecutive slashes. For example, /a//b becomes /a/b. |
Default HTTP retry policy
These fields set the mesh-wide default for HTTP retries. They take effect only when the target service's VirtualService does not define its own retry policy. When a VirtualService explicitly configures retries, those settings take precedence.
| Field path | Type | Description | Example |
|---|---|---|---|
.spec.defaultHttpRetryPolicy.attempts | Int32 | Maximum number of attempts, including the initial request. Only applies when the target VirtualService does not configure retries. | 2 |
.spec.defaultHttpRetryPolicy.perTryTimeout | Duration | Timeout for each individual attempt. Must be shorter than the overall request timeout defined in the VirtualService. 0s means unlimited. | 0s |
.spec.defaultHttpRetryPolicy.retryOn | String | Comma-separated list of conditions that trigger a retry. Supported values include 5xx, gateway-error, connect-failure, refused-stream, and reset. | gateway-error,connect-failure,refused-stream |
All three fields apply to the HTTP routing policy at the mesh level.
Prometheus metrics merging
When enabled, the ASM sidecar merges the application's native Prometheus metrics with the sidecar's own metrics into a single scrape endpoint. This prevents duplicate metric collection when both the application and the sidecar expose Prometheus endpoints.
| Field path | Type | Description | Example |
|---|---|---|---|
.spec.enablePrometheusMerge | Bool | Merge the pod's original prometheus.io annotations with the ASM sidecar monitoring configuration. Prevents duplicate metric collection. | true |