Description of ASMExtensionProvider CRD - Alibaba Cloud Service Mesh

ASMExtensionProvider is a component designed to enhance and configure the features of Alibaba Cloud Service Mesh (ASM), enabling flexible integration and custom configuration of key features, including tracing analysis and access logs. This topic describes how to configure ASMExtensionProvider and introduces specific fields.

Sample configurations

Configure tracing analysis using Zipkin

The following sample code provides an example on how to report tracing analysis using Zipkin.

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

Configure the format of access logs that are generated by Envoy proxies

The following sample code provides an example on how to configure the format of access logs generated by Envoy proxies.

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

Configure reporting methods for different clusters

The following sample code provides an example on the configuration for an aggregate provider, where cluster-a sends tracing data using Zipkin, while other clusters use OpenTelemetry.

Important

Only ASM of version 1.22.6.89 and later is supported.

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

Import providers in a Telemetry CRD

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

Configuration items

ASMExtensionProvider

Configuration item	Type	Required	Description
zipkin	ZipkinTracingProvider	No	Configures tracing analysis for Zipkin.
lightstep	LightstepTracingProvider	No	Configures tracing analysis for Lightstep.
datadog	DatadogTracingProvider	No	Configures tracing analysis for Datadog.
stackdriver	StackdriverProvider	No	Configures tracing analysis for Stackdriver.
opencensus	OpenCensusAgentTracingProvider	No	Configures tracing analysis for OpenCensus.
skywalking	SkywalkingTracingProvider	No	Configures tracing analysis for Skywalking.
opentelemetry	OpenTelemetryProvider	No	Configures tracing analysis for OpenTelemetry.
envoyFileAccesslog	EnvoyFileAccessLogProvider	No	Configures access logs of Envoy proxies
aggregate	AggregateProvider	No	An aggregate provider for configuring different providers for different clusters.

Important

Ensure the name of the provider corresponds to a service within the ASM before you configure a tracing provider. For external services, registration is required through ServiceEntry. For more information, see Service Entry.

ZipkinTracingProvider

Configuration item	Type	Required	Description
service	string	Yes	The name of the Zipkin service.
path	string	Yes	The request path of the Zipkin service.
port	uint32	No	The port of the Zipkin service.
maxTagLength	uint32	No	The maximum character length for each tag. The default value is 256.

LightstepTracingProvider

Configuration item	Type	Required	Description
service	string	Yes	The name of the Lightstep service.
port	uint32	Yes	The port of the Lightstep service.
accesstoken	string	No	The access token of the Lightstep service.
maxTagLength	uint32	No	The maximum character length for each tag. The default value is 256.

DatadogTracingProvider

Configuration item	Type	Required	Description
service	string	Yes	The name of the Datadog service.
port	uint32	Yes	The port of the Datadog service.
maxTagLength	uint32	No	The maximum character length for each tag. The default value is 256.

StackdriverProvider

Configuration item	Type	Required	Description
maxTagLength	uint32	No	The maximum character length for each tag. The default value is 256.
logging	StackdriverProvider_Logging	No	The logging of Stackdriver.

OpenCensusAgentTracingProvider

Configuration item	Type	Required	Description
service	string	Yes	The name of OpenCensusAgent service.
port	uint32	Yes	The port of OpenCensusAgent service.
context	[]string	No	The header propagation used for distributed tracing. Default value: `["W3C_TRACE_CONTEXT"]`.
maxTagLength	uint32	No	The maximum character length for each tag. The default value is 256.

SkywalkingTracingProvider

Configuration item	Type	Required	Description
service	string	Yes	The name of the Skywalking service.
port	uint32	Yes	The port of the Skywalking service.

OpenTelemetryProvider

Configuration item	Type	Required	Description
service	string	Yes	The name of the OpenTelemetry service.
port	uint32	Yes	The port of the OpenTelemetry service.
maxTagLength	uint32	No	The maximum character length for each tag. The default value is 256.
grpc	OpenTelemetryProvider_GrpcService	No	The gRPC protocol over which the data is reported.
http	OpenTelemetryProvider_HttpService	No	The HTTP protocol over which the data is reported. If not specified, gRPC protocol is used by default for data reporting.

EnvoyFileAccessLogProvider

Configuration item	Type	Required	Description
path	string	No	The path to which logs are output.
logFormat	EnvoyFileAccessLogProvider_LogFormat	No	The format of the logs. Either `text` or `labels`.

AggregateProvider

Configuration item	Type	Required	Description
defaultProvider	ProviderRef	Yes	The default provider used.
uniqueProviders	[]UniqueProvider	No	The Providers configured for different clusters.

UniqueProvider

Configuration item	Type	Required	Description
provider	ProviderRef	No	The Provider for reference.
clusters	[]ClusterRef	No	The clusters for reference.

StackdriverProvider_Logging

Configuration item	Type	Required	Description
labels	map[string]string	No	The label names and expressions to be included in log entries. Example: `path: request.url_path`.

OpenTelemetryProvider_HttpService

Configuration item	Type	Required	Description
path	string	Yes	The path of the service.
timeout	string	No	The timeout period for HTTP requests.
headers	[]HeaderValue	No	The custom HTTP request headers added to each HTTP request.

OpenTelemetryProvider_GrpcService

Configuration item	Type	Required	Description
timeout	string	No	The timeout period during which gRPC requests are responded.
initialMetaData	[]HeaderValue	No	The custom request headers added to each gRPC request.

HeaderValue

Configuration item	Type	Required	Description
name	string	Yes	The name of the request header.
value	string	Yes	The value of the request header.

EnvoyFileAccessLogProvider_LogFormat

Configuration item

Type

Required

Description

text

string

The log format of textual input. Example: text: "%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%".

labels

map[string]string

The format of Envoy access log in the JSON format. Example:

labels:
  status: "%RESPONSE_CODE%"
  message: "%LOCAL_REPLY_BODY%"

ProviderRef

Configuration item	Type	Required	Description
name	string	No	The name of the provider.

ClusterRef

Configuration item	Type	Required	Description
region	string	No	The region where the cluster is located.
name	string	No	The name of the cluster.
id	string	Yes	The ID of the cluster.