Ztunnel 配置說明 - Alibaba Cloud Service Mesh

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 將保留上一次有效配置。