ASMMeshConfig CRD overview-Alibaba Cloud Service Mesh-阿里云帮助中心

ASMMeshConfig is a custom resource (CR) from Alibaba Cloud Service Mesh (ASM) that defines mesh-wide configuration for the service mesh. Similar to Istio's MeshConfig, this CR allows you to centrally manage mesh-level parameters such as connection timeout, protocol detection, path normalization, and a retry policy. You can also use it to control the behavior and resource quota of the sidecar injector.

Configuration example

The following example specifies mesh-wide settings for an ASM instance, including connection configuration, path normalization, the HTTP retry policy, sidecar injector configuration, and the global rate limiting service.

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: true
  sidecarInjectorWebhookConfiguration:
    rewriteAppHTTPProbe: true
    replicaCount: 2
    resources:
      requests:
        cpu: 100m
        memory: 256Mi
      limits:
        cpu: '2'
        memory: 2Gi
  rateLimitService:
    enabled: true
    redis:
      authSecret: redis-secret
      url: redis.istio-system.svc:6379
    replicas: 1
  accessLogConfiguration:
    logEncoding: JSON
    logProject: test-project
    sidecarEnabled: true
  manifestPatch:
  - targetRef:
      kind: DaemonSet
      group: apps
      namespace: kube-system
      selector:
        labels:
          app: istio-cni
    patch: |
      metadata:
        labels:
          custom.example.com/managed-by: asm
        annotations:
          custom.example.com/cni-version: "1.29"

Important

To use all fields of the ASMMeshConfig CRD, your ASM instance must be version 1.24 or later. The rateLimitService configuration requires instance version 1.25.6.84. In addition, the ASMMeshConfig CR is not namespaced, and its name must be default. ASMMeshConfig CRs with any other name are ignored.

Field reference

Spec (Mesh configuration)

Field path	Type	Description	Example value
`tcpKeepalive`	TcpKeepalive	Configures TCP keepalive settings.	`probes: 5`
`connectTimeout`	Duration	Specifies the maximum wait time for the Envoy proxy to establish a TCP connection. A timeout triggers an `upstream connect timeout` error. The supported units are `ns`/`ms`/`s`/`m`/`h`.	`30s`
`protocolDetectionTimeout`	Duration	The timeout for protocol detection, used to identify HTTP/HTTPS traffic. If the protocol is not detected within this duration, the traffic is treated as raw TCP. Important This field is configurable only in ASM versions 1.19 and earlier.
`pathNormalization`	PathNormalization	Configures path normalization for HTTP requests.
`defaultHttpRetryPolicy`	DefaultHttpRetryPolicy	Defines the default HTTP retry policy for sidecars.
`enablePrometheusMerge`	Bool	If `true`, merges a pod's `prometheus.io` annotations with the ASM monitoring configuration to prevent duplicate metric collection.	`true`
`sidecarInjectorWebhookConfiguration`	SidecarInjectorWebhookConfiguration	Configures the sidecar injector.
`accessLogConfiguration`	AccessLogConfiguration	Configures the format and collection of access logs.
`rateLimitService`	RatelimitService	Configures the global rate limiting service. Important This field is configurable only in ASM versions 1.25 and later.
`manifestPatch`	[]PatchConfig	The `manifestPatch` field allows you to apply a Strategic Merge Patch to Kubernetes resources rendered by the ASM control plane, thereby customizing automatically managed resources such as Deployments, Services, and ConfigMaps without modifying the control plane code. Important This field is configurable only in ASM versions 1.27 and later.

TcpKeepalive

Field path	Type	Description	Example value	Scope
`probes`	Uint32	The maximum number of TCP keepalive probes to send. A value of `0` disables the keepalive mechanism.	`9`	Outbound long-lived TCP connections.
`time`	Duration	The idle time before the first keepalive probe is sent.	`7200s`
`interval`	Duration	The keep-alive probe sending interval must be less than the `time` parameter.	`75s`

PathNormalization

Field path

Type

Description

Example value

Scope

normalization

Enum

The URI path processing policy:

NONE: Disables standardization.
BASE: Merges slashes and retains path parameters (such as ;).
MERGE_SLASHES: Only merges consecutive slashes.

NONE

Mesh-wide HTTP routing.

DefaultHttpRetryPolicy

Field path	Type	Description	Example value	Scope
`attempts`	Int32	The maximum number of attempts for an HTTP request. This global setting applies only if a VirtualService does not explicitly define its own retry policy.	`2`	HTTP routing policy.
`perTryTimeout`	Duration	The timeout for each attempt. This value must be less than the overall request timeout defined in the VirtualService.	`0s` (unlimited)
`retryOn`	String	Specifies the conditions that trigger a retry. Supported standard error types include `5xx`, `gateway-error`, `connect-failure`, and `reset`. Separate multiple values with commas.	`gateway-error`, `connect-failure`, `refused-stream`

SidecarInjectorWebhookConfiguration

Field path	Type	Description	Example value	Scope
`rewriteAppHTTPProbe`	Bool	If `true`, rewrites a pod's HTTP readiness probe, redirecting it to the sidecar proxy.	`true`	Sidecar injection behavior.
`replicaCount`	Int	The number of replicas for the sidecar injector controller to improve high availability.	`2`	Sidecar injector component.
`resources`	Object	The resource quota configuration: `requests`: The minimum resources required for the container to start. `limits`: The maximum amount of resources that a container can use.	`... resources: requests: cpu: 100m memory: 256Mi limits: cpu: '2' memory: 2Gi`	Sidecar injector component.

AccessLogConfiguration

Field path	Type	Description	Example value
`logEncoding`	String	The output format for logs. Valid values are `JSON` and `TEXT`.	`JSON`
`logProject`	String	The destination Alibaba Cloud Log Service (SLS) project for the logs. Important This field is configurable only in ASM versions 1.25 and later.	`log-project-test`
`gatewayEnabled`	Boolean	If `true`, collects and sends access logs from the gateway to Alibaba Cloud Log Service (SLS).	`true`
`sidecarEnabled`	Boolean	If `true`, collects and sends access logs from sidecars to Alibaba Cloud Log Service (SLS).	`true`
`ztunnelEnabled`	Boolean	If `true`, collects and sends access logs from Ztunnel to Alibaba Cloud Log Service (SLS). Important This field is configurable only in ASM versions 1.25 and later.	`true`
`gatewayLifecycle`	Integer	The retention period in days for gateway access logs. Default: 90.	`30`
`sidecarLifecycle`	Integer	The retention period in days for sidecar access logs. Default: 90.	`30`
`ztunnelLifecycle`	Integer	The retention period in days for Ztunnel access logs. Default: 90. Important This field is configurable only in ASM versions 1.25 and later.	`30`

RatelimitService

Field path	Type	Description	Example value	Scope
`enabled`	Bool	Specifies whether to enable the global rate limiting service.	`true`	Global rate limiting capability.
`replicas`	Int	The number of replicas for the rate limiting service.	`1`	Availability and performance of the rate limiting service.
`resources`	Object	The resource configuration for the rate limiting service.	`limits: cpu: 500m memory: 512Mi requests: cpu: 100m memory: 128Mi`	Availability and performance of the rate limiting service.
`redis`	Object	Configuration for the Redis instance used by the rate limiting service. Note The global rate limiting service uses Redis to store rate limiting policies and decisions.	`redis: authSecret: redis-secret url: redis.istio-system.svc:6379`	Rate limiting state backend.
`redis.type`	String	The type of the Redis cluster. The valid values are `single`, `cluster`, and `sentinel`. The default value is `single`.	`single`	Rate limiting state backend.
`redis.url`	String	The Redis address.	`redis.istio-system.svc.cluster.local:6379`	Rate limiting state backend.
`redis.auth`	String	The authentication information for Redis. The format is `password` or `user:password`. (For security, we recommend that you use an AuthSecret.)	xxxxxx	Credential security management.
`redis.authSecret`	String	The name of the Secret that stores the Redis authentication credentials. Note This Secret must be deployed in the `istio-system` namespace and contain the Base64-encoded authentication information in its `redis-auth` key.	`apiVersion: v1 data: redis-auth: ${BASE64_ENCODED_CREDENTIALS} kind: Secret metadata: name: redis-secret namespace: istio-system type: Opaque`	Credential security management.
`redis.cacheKeyPrefix`	String	The prefix for Redis cache keys. Defaults to empty.	N/A	Rate limiting state backend.

Note

We recommend that you use Alibaba Cloud Redis to ensure high availability. You can configure the rateLimitService.redis.type parameter based on the type of your Redis instance and the following table.

Instance type	Architecture	Connection mode	`redis.type` configuration
Single-node	N/A	N/A	`single`
High-availability	Standard (cluster disabled)	N/A	`single`
	Cluster (cluster enabled)	Direct connection mode	`cluster`
	Cluster (cluster enabled)	Proxy mode	`single`

ASM aggregates all configurations and automatically generates a rate limiting service configuration named ratelimit-service-config in the istio-system namespace. When you enable the rate limiting service, this configuration is automatically mounted. You do not need to manually update the rate limiting service configuration.

PatchConfig

Field path	Type	Description
`targetRef`	TargetRef	Specify the target resource to patch. When ASM reconciles each resource, it matches the actual information of the resource with the conditions in `targetRef`.
`patch`	string	The content of the Strategic Merge Patch, in either YAML or JSON format. ASM merges this patch into the target resource.

TargetRef

Field path	Type	Required	Description
`kind`	string	Yes	The Kubernetes Kind of the target resource, such as `Deployment`, `Service`, and `ConfigMap`.
`group`	string	No	The API Group of the target resource, such as `apps`. If this parameter is not specified, the API Group is not validated.
`name`	string	No	The name of the target resource. If not specified, the patch applies to all resources of the specified `Kind`.
`namespace`	string	No	The `Namespace` where the target resource is located. If not specified, the `Namespace` is not validated.
`selector`	PatchSelector	No	Further filters target resources using a label selector. If not specified, labels are not matched.

PatchSelector

Field path	Type	Required	Description
`labels`	map[string]string	No	A map of key-value pairs. A resource must contain all specified labels to be matched (AND logic).

Important

When ASM reconciles resources, it uses the following rules to determine whether targetRef matches the current resource:

kind must be identical to the Kind of the resource.
If group is specified, it must match the API Group of the resource.
If you specify name, it must match the name of the resource.
If a namespace is specified, it must be the same as the namespace of the resource.
If selector.labels is specified, the resource must contain all the specified labels (AND relationship).