Ztunnel 配置说明 - 服务网格 ASM

ASM Ambient 模式下，ztunnel 组件可以通过 istio-system 命名空间下的 ztunnel-config ConfigMap 加载运行时配置。该 ConfigMap 中的 config.yaml 字段定义了出站流量策略、L7 可观测性等配置项。ztunnel 通过文件监听机制感知配置变更，无需重启即可生效。本文介绍 ztunnel-config 的 YAML 示例和字段说明。

配置方式

ztunnel-config ConfigMap 的整体结构如下：

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

    egressPolicies: [ ]

字段	类型	是否必须	说明
`l7Config`	`L7Config`	否	L7 层可观测性配置。不配置时使用默认值。
`egressPolicies`	`EgressPolicy[]`	否	集群外服务出站流量策略规则列表。为空或不配置时，所有出站流量默认放行。

重要

EgressPolicy配置只对集群外服务生效，Service，ServiceEntry等注册进集群内的服务不受该配置影响。

配置示例

示例一：启用 L7 访问日志

启用 L7 层访问日志打印，ztunnel 将对 HTTP 和 TLS 协议的流量进行解析并输出访问日志。

l7Config:
  enabled: true

示例二：禁止访问指定内网地址段

不对 L7 可观测性做额外配置，仅通过 EgressPolicy 禁止所有命名空间访问内网地址段。

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

示例三：启用 L7 访问日志并配置分层出站管控

同时启用 L7 访问日志和出站流量策略，允许指定命名空间放行、禁止通过特定端口访问元数据服务、禁止访问内网地址段。

l7Config:
  enabled: true
egressPolicies:
# 允许 egress-gateway 命名空间放行，避免兜底规则循环拦截出口代理自身
- namespaces:
  - egress-gateway
  policy: Passthrough

# 禁止通过 80 和 443 端口访问云厂商元数据服务地址
- matchCidrs:
  - 169.254.169.254/32
  - fd00:ec2::254/128
  matchPorts:
  - 80
  - 443
  policy: Deny

# 禁止访问内网地址段
- matchCidrs:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16
  - fc00::/7
  policy: Deny

字段说明

L7Config

字段	类型	是否必须	说明
`enabled`	`bool`	否	是否启用 L7 层流量可观测性。默认值为 `false`。

说明

当前 L7 可观测性仅支持访问日志（Access Log）打印，暂不支持请求级指标采集和分布式链路追踪。
支持的协议范围为 HTTP 和 TLS。
启用后会产生约 5% 的性能损耗，请根据业务需要评估是否开启。

HTTP 新增字段

启用 L7 后，每个 HTTP 请求/响应事务产生一条独立的访问日志，在基础字段之上新增以下字段：

字段	说明	示例值
`method`	HTTP 请求方法	`GET`、`POST`、`PUT`、`DELETE`
`path`	请求路径	`/api/v1/users`
`protocol`	协议版本	`HTTP/1.0`、`HTTP/1.1`
`host`	请求主机	`httpbin:8000`
`response_code`	HTTP 响应状态码	`200`、`404`、`503`
`user_agent`	`User-Agent` 请求头，缺失时为 `"-"`	`curl/7.88.1`
`bytes_sent`	请求体大小（字节），粒度为单次请求	`0`
`bytes_recv`	响应体大小（字节），粒度为单次请求	`512`
`duration`	单次请求耗时（从发出请求到收到响应）	`15ms`

TLS 新增字段

启用 L7 后，对于 TLS 流量（非 HTTP over TLS），ztunnel 解析 ClientHello 握手消息，在基础字段之上新增以下字段：

字段	说明	示例值
`protocol`	固定值	`TLS`
`tls.sni`	ClientHello 中的 Server Name Indication	`example.com`
`tls.alpn`	ClientHello 中的首个 ALPN 协议，缺失时为 `"-"`	`h2`、`http/1.1`

EgressPolicy

每条 EgressPolicy 规则由 namespaces、matchCidrs 和 matchPorts 三个匹配条件和一个 policy 动作组成。ztunnel 按照规则列表从上到下逐条匹配，第一个同时满足所有条件的规则即为命中规则。

字段	类型	是否必须	说明
`namespaces`	`string[]`	否	限定规则生效的客户端命名空间列表。为空时匹配所有命名空间。
`matchCidrs`	`string[]`	否	限定规则匹配的目标 IP 地址范围，使用 CIDR 格式。为空时匹配所有目标地址。如需同时管控 IPv4 和 IPv6 流量，需分别配置对应的 CIDR。
`matchPorts`	`int[]`	否	限定规则匹配的目标端口号列表。为空时匹配所有端口。
`policy`	`string`	是	规则动作。可选值： `Passthrough` `Deny`

EgressPolicyAction

policy 字段的可选值如下：

取值	说明
`Passthrough`	放行流量。请求以 TCP 协议直接转发到目标地址，不经过网格代理。
`Deny`	拒绝流量。请求被直接丢弃，不发送到目标地址。

配置约束

egressPolicies 中的规则按列表顺序匹配，第一条同时满足 namespaces、matchCidrs 和 matchPorts 条件的规则即为最终生效规则，后续规则不再继续匹配。
namespaces 匹配的是请求发起方（客户端）所在的命名空间，不是目标服务的命名空间。
matchCidrs 匹配的是目标 IP 地址，而非域名。如需基于域名进行管控，请通过 ServiceEntry 将外部服务纳入网格管理。
matchPorts 匹配的是目标端口号（即请求发往的远端端口），而非客户端的源端口。
如果所有 egressPolicies 规则均未命中，默认按 Passthrough 处理。
配置变更通过文件监听机制自动加载，无需重启 ztunnel Pod。如配置格式有误，ztunnel 将保留上一次有效配置。