Ztunnel configuration - Alibaba Cloud Service Mesh - Alibaba Cloud Documentation Center

In Service Mesh (ASM) ambient mode, the Ztunnel component loads its runtime configuration from the ztunnel-config ConfigMap in the istio-system namespace. The config.yaml field in this ConfigMap defines settings for egress policy, L7 observability, and other configurations. Ztunnel watches the file for changes and applies them automatically without a restart.

Configuration

The ztunnel-config ConfigMap has the following structure:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ztunnel-config
  namespace: istio-system
data:
  ztunnel-config.yaml: |
    l7Config:
      enabled: false

    egressPolicies: [ ]

Field	Type	Required	Description
`l7Config`	`L7Config`	No	Configuration for L7 observability. If not specified, default values are used.
`egressPolicies`	`EgressPolicy[]`	No	Egress policy rules for traffic to services outside the cluster. If empty or not specified, all egress traffic is allowed by default.

Important

EgressPolicy configurations apply only to services outside the cluster. Services registered within the cluster, such as Service and ServiceEntry resources, are not affected.

Configuration examples

Example 1: Enable L7 access logs

Enable L7 access log generation. Ztunnel parses HTTP and TLS traffic and outputs access logs.

l7Config:
  enabled: true

Example 2: Deny access to private CIDR blocks

Deny access from all namespaces to private CIDR blocks, without enabling L7 observability.

egressPolicies:
- matchCidrs:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16
  policy: Deny

Example 3: Enable L7 access logs and layered egress control

Enable L7 access logs combined with layered egress control: allow passthrough for a specific namespace, deny access to the metadata service on specific ports, and deny access to private CIDR blocks.

l7Config:
  enabled: true
egressPolicies:
# Allow passthrough for the egress-gateway namespace to prevent the fallback rule from blocking the egress proxy itself.
- namespaces:
  - egress-gateway
  policy: Passthrough

# Deny access to the cloud provider's metadata service on ports 80 and 443.
- matchCidrs:
  - 169.254.169.254/32
  - fd00:ec2::254/128
  matchPorts:
  - 80
  - 443
  policy: Deny

# Deny access to private CIDR blocks.
- matchCidrs:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16
  - fc00::/7
  policy: Deny

Field details

L7Config

Field	Type	Required	Description
`enabled`	`bool`	No	Enables L7 traffic observability. Default: `false`.

Note

L7 observability currently supports access log generation only. Request-level metric collection and distributed tracing are not yet supported.
The supported protocols are HTTP and TLS.
Enabling this feature can add approximately 5% performance overhead. Evaluate your workload requirements before enabling it.

Additional HTTP fields

When L7 observability is enabled, each HTTP request/response transaction generates a separate access log entry with the following additional fields:

Field	Description	Example value
`method`	HTTP request method	`GET`, `POST`, `PUT`, `DELETE`
`path`	Request path	`/api/v1/users`
`protocol`	Protocol version	`HTTP/1.0`, `HTTP/1.1`
`host`	Request host	`httpbin:8000`
`response_code`	HTTP response status code	`200`, `404`, `503`
`user_agent`	The `User-Agent` request header. If the header is missing, the value is `"-"`.	`curl/7.88.1`
`bytes_sent`	Size of the request body in bytes, per request	`0`
`bytes_recv`	Size of the response body in bytes, per request	`512`
`duration`	Total time for a single request, from when it is sent until the response is received	`15ms`

Additional TLS fields

When L7 observability is enabled for TLS traffic (not HTTP over TLS), Ztunnel parses the ClientHello handshake message and adds the following fields to the log entry:

Field	Description	Example value
`protocol`	Fixed value	`TLS`
`tls.sni`	The Server Name Indication (SNI) from the ClientHello message	`example.com`
`tls.alpn`	The first Application-Layer Protocol Negotiation (ALPN) protocol from the ClientHello message. If no ALPN is specified, the value is `"-"`.	`h2`, `http/1.1`

EgressPolicy

Each EgressPolicy rule consists of three match conditions (namespaces, matchCidrs, and matchPorts) and a policy action. Ztunnel evaluates rules from top to bottom and applies the first rule whose conditions all match.

Field	Type	Required	Description
`namespaces`	`string[]`	No	A list of client namespaces to which the rule applies. If empty, it matches all namespaces.
`matchCidrs`	`string[]`	No	A list of destination IP address ranges in CIDR format. If empty, it matches all destination IP addresses. To control both IPv4 and IPv6 traffic, you must configure their respective CIDR ranges separately.
`matchPorts`	`int[]`	No	A list of destination ports. If empty, it matches all ports.
`policy`	`string`	Yes	The action to take. Valid values are: `Passthrough` `Deny`

EgressPolicyAction

The following values are available for the policy field:

Value	Description
`Passthrough`	Forwards traffic directly to the destination IP address over TCP, bypassing the mesh proxy.
`Deny`	Immediately drops the request, preventing it from reaching the destination.

Configuration constraints

Ztunnel evaluates rules in egressPolicies in order and applies the first rule whose namespaces, matchCidrs, and matchPorts conditions all match. Subsequent rules are ignored.
The namespaces field matches the namespace of the client (the source of the request), not the namespace of the destination service.
The matchCidrs field matches the destination IP address, not the domain name. To control traffic based on domain names, you must register the external service as a ServiceEntry in the mesh.
The matchPorts field matches the destination port (the remote port of the request), not the client's source port.
If a request matches no rules in egressPolicies, the default action is Passthrough.
Ztunnel automatically loads configuration changes through file-watching, without requiring a pod restart. If the configuration format is invalid, Ztunnel retains the last known good configuration.