All Products
Search

This Product

    Alibaba Cloud Service Mesh:ASMExtensionProvider CRD

    Document Center

    Alibaba Cloud Service Mesh:ASMExtensionProvider CRD

    Last Updated:Mar 10, 2026

    ASMExtensionProvider is a Custom Resource Definition (CRD) that configures telemetry backends for Alibaba Cloud Service Mesh (ASM). Each ASMExtensionProvider resource maps to a backend service such as Zipkin, OpenTelemetry, or an Envoy file-based access logger.

    To activate a provider, reference it by name in a Telemetry CRD.

    Before you begin

    • The provider name must correspond to a Kubernetes service accessible within the mesh. For external services, register them through a ServiceEntry first.

    • The service field uses the fully qualified domain name (FQDN) format: <service-name>.<namespace>.svc.cluster.local. To reference a service in a different namespace, include the namespace in the FQDN.

    Examples

    Report traces to Zipkin

    apiVersion: istio.alibabacloud.com/v1
kind: ASMExtensionProvider
metadata:
  name: zipkin
spec:
  zipkin:
    port: 8090
    service: zipkin.istio-system.svc.cluster.local

    Customize the Envoy access log format

    Define a custom JSON log format for Envoy proxy access logs and output them to stdout:

    apiVersion: istio.alibabacloud.com/v1
kind: ASMExtensionProvider
metadata:
  name: envoy
spec:
  envoyFileAccessLog:
    logFormat:
      text: '{"bytes_received":"%BYTES_RECEIVED%","bytes_sent":"%BYTES_SENT%","downstream_local_address":"%DOWNSTREAM_LOCAL_ADDRESS%","downstream_remote_address":"%DOWNSTREAM_REMOTE_ADDRESS%","duration":"%DURATION%","istio_policy_status":"%DYNAMIC_METADATA(istio.mixer:status)%","method":"%REQ(:METHOD)%","path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","protocol":"%PROTOCOL%","request_id":"%REQ(X-REQUEST-ID)%","requested_server_name":"%REQUESTED_SERVER_NAME%","response_code":"%RESPONSE_CODE%","response_flags":"%RESPONSE_FLAGS%","route_name":"%ROUTE_NAME%","start_time":"%START_TIME%","trace_id":"%REQ(X-B3-TRACEID)%","upstream_cluster":"%UPSTREAM_CLUSTER%","upstream_host":"%UPSTREAM_HOST%","upstream_local_address":"%UPSTREAM_LOCAL_ADDRESS%","upstream_service_time":"%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%","upstream_response_time":"%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%","upstream_transport_failure_reason":"%UPSTREAM_TRANSPORT_FAILURE_REASON%","user_agent":"%REQ(USER-AGENT)%","x_forwarded_for":"%REQ(X-FORWARDED-FOR)%","authority_for":"%REQ(:AUTHORITY)%"}'
    path: /dev/stdout

    The format string uses Envoy command operators such as %RESPONSE_CODE% and %DURATION%. Include only the fields relevant to your use case. The example above is a comprehensive template.

    Route traces to different backends per cluster

    Use an aggregate provider to send tracing data from specific clusters to designated backends. In the following example, cluster-a reports traces to Zipkin while all other clusters use OpenTelemetry.

    Important

    The aggregate provider requires ASM version 1.22.6.89 or later.

    Step 1: Define the aggregate provider and the individual tracing providers.

    apiVersion: istio.alibabacloud.com/v1
kind: ASMExtensionProvider
metadata:
  name: aggregate-provider
spec:
  aggregate:
    defaultProvider:
      name: opentelemetry
    uniqueProviders:
    - clusters:
      - id: cluster-a
        region: cn-hangzhou
      provider:
        name: zipkin
---
apiVersion: istio.alibabacloud.com/v1
kind: ASMExtensionProvider
metadata:
  name: zipkin
spec:
  zipkin:
    port: 8090
    service: zipkin.istio-system.svc.cluster.local
---
apiVersion: istio.alibabacloud.com/v1
kind: ASMExtensionProvider
metadata:
  name: opentelemetry
spec:
  opentelemetry:
    port: 8090
    service: otel.istio-system.svc.cluster.local

    Step 2: Reference the providers in a Telemetry CRD to activate them.

    apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: default
  namespace: istio-system
spec:
  accessLogging:
  - disabled: false
    providers:
    - name: envoy
  tracing:
  - providers:
    - name: zipkin

    Field reference

    ASMExtensionProvider

    Each ASMExtensionProvider resource contains exactly one provider configuration. Set the field that matches your target backend.

    FieldTypeRequiredDescription
    zipkinZipkinTracingProviderNoZipkin tracing backend. See ZipkinTracingProvider.
    lightstepLightstepTracingProviderNoLightstep tracing backend. See LightstepTracingProvider.
    datadogDatadogTracingProviderNoDatadog tracing backend. See DatadogTracingProvider.
    stackdriverStackdriverProviderNoStackdriver tracing backend. See StackdriverProvider.
    opencensusOpenCensusAgentTracingProviderNoOpenCensus tracing backend. See OpenCensusAgentTracingProvider.
    skywalkingSkywalkingTracingProviderNoSkywalking tracing backend. See SkywalkingTracingProvider.
    opentelemetryOpenTelemetryProviderNoOpenTelemetry tracing backend. See OpenTelemetryProvider.
    envoyFileAccesslogEnvoyFileAccessLogProviderNoEnvoy file-based access log provider. See EnvoyFileAccessLogProvider.
    aggregateAggregateProviderNoRoutes telemetry to different providers based on cluster identity. See AggregateProvider.

    ZipkinTracingProvider

    FieldTypeRequiredDescription
    servicestringYesFQDN of the Zipkin service. Example: zipkin.istio-system.svc.cluster.local.
    pathstringYesAPI endpoint path for the Zipkin service.
    portuint32NoPort of the Zipkin service.
    maxTagLengthuint32NoMaximum character length per tag. Default: 256.

    LightstepTracingProvider

    FieldTypeRequiredDescription
    servicestringYesFQDN of the Lightstep service.
    portuint32YesPort of the Lightstep service.
    accesstokenstringNoAccess token for authenticating with Lightstep.
    maxTagLengthuint32NoMaximum character length per tag. Default: 256.

    DatadogTracingProvider

    FieldTypeRequiredDescription
    servicestringYesFQDN of the Datadog agent service.
    portuint32YesPort of the Datadog agent service.
    maxTagLengthuint32NoMaximum character length per tag. Default: 256.

    StackdriverProvider

    FieldTypeRequiredDescription
    maxTagLengthuint32NoMaximum character length per tag. Default: 256.
    loggingStackdriverProvider_LoggingNoLogging configuration for Stackdriver. See StackdriverProvider_Logging.

    OpenCensusAgentTracingProvider

    FieldTypeRequiredDescription
    servicestringYesFQDN of the OpenCensus agent service.
    portuint32YesPort of the OpenCensus agent service.
    context[]stringNoTrace context propagation headers. Default: ["W3C_TRACE_CONTEXT"].
    maxTagLengthuint32NoMaximum character length per tag. Default: 256.

    SkywalkingTracingProvider

    FieldTypeRequiredDescription
    servicestringYesFQDN of the Skywalking service.
    portuint32YesPort of the Skywalking service.

    OpenTelemetryProvider

    FieldTypeRequiredDescription
    servicestringYesFQDN of the OpenTelemetry collector service.
    portuint32YesPort of the OpenTelemetry collector service.
    maxTagLengthuint32NoMaximum character length per tag. Default: 256.
    grpcOpenTelemetryProvider_GrpcServiceNogRPC transport configuration. See OpenTelemetryProvider_GrpcService.
    httpOpenTelemetryProvider_HttpServiceNoHTTP transport configuration. If omitted, gRPC is used by default. See OpenTelemetryProvider_HttpService.

    EnvoyFileAccessLogProvider

    FieldTypeRequiredDescription
    pathstringNoFile path for log output. Example: /dev/stdout.
    logFormatEnvoyFileAccessLogProvider_LogFormatNoLog output format. Supports text or labels (JSON). See EnvoyFileAccessLogProvider_LogFormat.

    AggregateProvider

    FieldTypeRequiredDescription
    defaultProviderProviderRefYesThe provider used for clusters that do not match any entry in uniqueProviders.
    uniqueProviders[]UniqueProviderNoPer-cluster provider assignments. See UniqueProvider.

    UniqueProvider

    FieldTypeRequiredDescription
    providerProviderRefNoThe provider to use for the specified clusters. See ProviderRef.
    clusters[]ClusterRefNoThe clusters assigned to this provider. See ClusterRef.

    StackdriverProvider_Logging

    FieldTypeRequiredDescription
    labelsmap[string]stringNoLabel names and expressions included in log entries. Example: path: request.url_path.

    OpenTelemetryProvider_HttpService

    FieldTypeRequiredDescription
    pathstringYesAPI endpoint path of the collector service.
    timeoutstringNoTimeout for HTTP requests.
    headers[]HeaderValueNoCustom HTTP headers appended to each request. See HeaderValue.

    OpenTelemetryProvider_GrpcService

    FieldTypeRequiredDescription
    timeoutstringNoTimeout for gRPC requests.
    initialMetaData[]HeaderValueNoCustom metadata headers appended to each gRPC request. See HeaderValue.

    HeaderValue

    FieldTypeRequiredDescription
    namestringYesHeader name.
    valuestringYesHeader value.

    EnvoyFileAccessLogProvider_LogFormat

    Specify the log format as either plain text or structured JSON. Use Envoy command operators to reference request and response attributes.

    FieldTypeRequiredDescription
    textstringNoPlain text log format. Example: "%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%".
    labelsmap[string]stringNoJSON-structured log format. Example: status: "%RESPONSE_CODE%", message: "%LOCAL_REPLY_BODY%".

    ProviderRef

    FieldTypeRequiredDescription
    namestringNoName of the ASMExtensionProvider resource to reference.

    ClusterRef

    FieldTypeRequiredDescription
    idstringYesCluster ID.
    namestringNoCluster name.
    regionstringNoRegion where the cluster is deployed.