監聽器配置 (proto)

config.listener.v3.AdditionalAddress

[config.listener.v3.AdditionalAddress proto]

監聽器正在監聽的其他位址。

{
  "address": {...},
  "socket_options": {...}
}

address: (config.core.v3.Address)

socket_options: (config.core.v3.SocketOptionsOverride) 可能不存在於 Envoy 原始碼或預編譯二進位檔中的其他通訊端選項。如果指定，這將覆寫監聽器中的 socket_options。如果指定時沒有 socket_options 或 socket_options 的空列表，表示不會套用任何通訊端選項。

config.listener.v3.Listener

[config.listener.v3.Listener proto]

{
  "name": ...,
  "address": {...},
  "additional_addresses": [],
  "stat_prefix": ...,
  "filter_chains": [],
  "filter_chain_matcher": {...},
  "use_original_dst": {...},
  "default_filter_chain": {...},
  "per_connection_buffer_limit_bytes": {...},
  "metadata": {...},
  "drain_type": ...,
  "listener_filters": [],
  "listener_filters_timeout": {...},
  "continue_on_listener_filters_timeout": ...,
  "transparent": {...},
  "freebind": {...},
  "socket_options": [],
  "tcp_fast_open_queue_length": {...},
  "traffic_direction": ...,
  "udp_listener_config": {...},
  "api_listener": {...},
  "connection_balance_config": {...},
  "reuse_port": ...,
  "enable_reuse_port": {...},
  "access_log": [],
  "tcp_backlog_size": {...},
  "max_connections_to_accept_per_socket_event": {...},
  "bind_to_port": {...},
  "internal_listener": {...},
  "enable_mptcp": ...,
  "ignore_global_conn_limit": ...,
  "bypass_overload_manager": ...
}

name: (字串) 此監聽器的唯一名稱。如果未提供名稱，Envoy 將為監聽器分配一個內部 UUID。如果監聽器要透過 LDS 動態更新或移除，則必須提供唯一的名稱。

address: (config.core.v3.Address) 監聽器應監聽的位址。一般而言，位址必須是唯一的，儘管這受作業系統的繫結規則約束。例如，多個監聽器可以在 Linux 上監聽連接埠 0，因為實際的連接埠將由作業系統分配。除非填寫 api_listener 或 listener_specifier，否則為必要欄位。

additional_addresses: (重複 config.listener.v3.AdditionalAddress) 監聽器應監聽的其他位址。這些位址在所有監聽器中必須是唯一的。可以提供多個連接埠為 0 的位址。在單個監聽器中使用多個位址時，所有位址都使用相同的協定，並且不支援多個內部位址。

stat_prefix: (字串) 要在監聽器統計資訊上使用的可選字首。如果為空，統計資訊將以 listener.<address as string>. 為根。如果為非空，統計資訊將以 listener.<stat_prefix>. 為根。

filter_chains

(重複 config.listener.v3.FilterChain) 要針對此監聽器考慮的篩選器鏈列表。具有最明確 FilterChainMatch 條件的 FilterChain 將用於連線上。

可以在常見問題條目中找到使用 SNI 進行篩選器鏈選擇的範例。

filter_chain_matcher: (.xds.type.matcher.v3.Matcher) 從網路屬性解析篩選器鏈名稱的 Matcher API。此比對器用作篩選器鏈比對條件 filter_chain_match 的替代方案。如果指定，所有 filter_chains 都必須具有非空且唯一的 name 欄位，並且不能指定 filter_chain_match 欄位。

注意

比對成功後，每個連線都會永久繫結到其篩選器鏈。如果比對器變更但篩選器鏈保持不變，則不會排空繫結到篩選器鏈的連線。但是，如果篩選器鏈被移除或結構修改，則會啟動其連線的排空。

警告

此 API 功能目前正在開發中。標記為正在開發中的 API 功能不被視為穩定，不受威脅模型的涵蓋範圍，不受安全團隊的支援，並且可能會發生重大變更。在未了解先前各點的情況下，請勿使用此功能。

use_original_dst: (BoolValue) 如果連線使用 iptables 重新導向，則 Proxy 接收連線的連接埠可能與原始目標位址不同。當此旗標設定為 true 時，監聽器會將重新導向的連線交給與原始目標位址相關聯的監聽器。如果沒有與原始目標位址相關聯的監聽器，則連線會由接收連線的監聽器處理。預設為 false。

default_filter_chain: (config.listener.v3.FilterChain) 如果沒有篩選器鏈比對，則為預設篩選器鏈。如果未提供預設篩選器鏈，則會關閉連線。此欄位中將忽略篩選器鏈比對。

per_connection_buffer_limit_bytes

(UInt32Value) 監聽器的新連線讀取和寫入緩衝區大小的軟限制。如果未指定，則會套用實作定義的預設值 (1MiB)。

注意

如果存在不受信任的下游，則應配置此欄位。

不受信任環境的範例配置

per_connection_buffer_limit_bytes: 32768.0

metadata: (config.core.v3.Metadata) 監聽器中繼資料。

drain_type: (config.listener.v3.Listener.DrainType) 要在監聽器層級執行的排空類型。

listener_filters: (重複 config.listener.v3.ListenerFilter) 監聽器篩選器有機會操作和擴充連線篩選器鏈比對中使用的連線中繼資料，例如。這些篩選器在 filter_chains 中的任何篩選器之前執行。順序很重要，因為這些篩選器會在監聽器接受通訊端之後，以及建立連線之前，依序處理。當 protocol 中監聽器通訊端位址的協定為 UDP，並且在 udp_listener_config 中未指定 quic_options 時，可以指定 UDP 監聽器篩選器。當在 udp_listener_config 中指定 quic_options 時，可以指定 QUIC 監聽器篩選器。它們會在建立連線之前依序處理。與 TCP 監聽器篩選器類似，它們可以用於操作連線中繼資料和通訊端。但不同之處在於它們不能用於暫停連線建立。

listener_filters_timeout: (Duration) 等待所有監聽器篩選器完成操作的逾時。如果達到逾時時間，則會關閉接受的通訊端，而不會建立連線，除非將 continue_on_listener_filters_timeout 設定為 true。指定 0 以停用逾時。如果未指定，則會使用預設逾時 15 秒。

continue_on_listener_filters_timeout: (布林值) 在監聽器篩選器逾時時是否應建立連線。預設值為 false。

注意

某些監聽器篩選器（例如 Proxy Protocol 篩選器）不應與此選項一起使用。當建立連線時，這會導致意外的行為。

transparent: (BoolValue) 決定是否應將監聽器設定為透明 Socket。當此標誌設定為 true 時，可以使用 iptables TPROXY 目標將連線重新導向至此監聽器，在此情況下，原始來源和目標位址與埠會保留在接受的連線上。此標誌應與 an original_dst 監聽器篩選器搭配使用，以將連線的本機位址標記為「已還原」。這可以用於將每個重新導向的連線交給另一個與連線的目標位址相關聯的監聽器。不使用 TPROXY 直接連線到 Socket 的行為，無法與使用 TPROXY 重新導向的連線區分，因此會被視為重新導向的連線。當此標誌設定為 false 時，監聽器的 Socket 會明確重設為非透明。設定此標誌需要 Envoy 以 CAP_NET_ADMIN 功能執行。當此標誌未設定（預設）時，Socket 不會被修改，也就是說，透明選項既不會設定也不會重設。

freebind: (BoolValue) 決定監聽器是否應設定 IP_FREEBIND Socket 選項。當此標誌設定為 true 時，監聽器可以繫結到 Envoy 執行所在的系統上未設定的 IP 位址。當此標誌設定為 false 時，會在 Socket 上停用 IP_FREEBIND 選項。當此標誌未設定（預設）時，Socket 不會被修改，也就是說，此選項既不會啟用也不會停用。

socket_options: (repeated config.core.v3.SocketOption) 可能不存在於 Envoy 原始碼或預編譯二進位檔中的其他 Socket 選項。當 enable_reuse_port 為 true 時，可以更新監聽器的 Socket 選項。否則，如果在監聽器更新期間 Socket 選項發生變更，則會拒絕更新，以明確表示選項未更新。

tcp_fast_open_queue_length

(UInt32Value) 決定監聽器是否應接受 TCP Fast Open (TFO) 連線。當此標誌設定為大於 0 的值時，會在 Socket 上啟用 TCP_FASTOPEN 選項，且佇列長度為指定的大小（請參閱 RFC7413 中的詳細資訊）。當此標誌設定為 0 時，會在 Socket 上停用 TCP_FASTOPEN 選項。當此標誌未設定（預設）時，Socket 不會被修改，也就是說，此選項既不會啟用也不會停用。

在 Linux 上，net.ipv4.tcp_fastopen 核心參數必須包含旗標 0x2 才能啟用 TCP_FASTOPEN。請參閱 ip-sysctl.txt。

在 macOS 上，只有 0、1 和未設定的值有效；其他值可能會導致錯誤。若要在 macOS 上設定佇列長度，請設定 net.inet.tcp.fastopen_backlog 核心參數。

traffic_direction: (config.core.v3.TrafficDirection) 指定相對於本機 Envoy 的流量預期方向。對於使用原始目標篩選器的監聽器，Windows 上需要此屬性，請參閱原始目標。

udp_listener_config: (config.listener.v3.UdpListenerConfig) 如果 protocol 中監聽器 Socket 位址的協定是 UDP，則此欄位會指定 UDP 監聽器特定的組態。

api_listener: (config.listener.v3.ApiListener) 用於表示 API 監聽器，該監聽器用於非代理用戶端。向非代理應用程式公開的 API 類型取決於 API 監聽器的類型。設定此欄位時，除了 name 以外，不應設定其他任何欄位。

注意

目前只能安裝一個 ApiListener；而且只能透過啟動組態進行安裝，而不是透過 LDS。

connection_balance_config

(config.listener.v3.Listener.ConnectionBalanceConfig) 監聽器的連線平衡器組態，目前僅適用於 TCP 監聽器。如果未指定組態，Envoy 將不會嘗試在工作執行緒之間平衡活動連線。

在監聽器 X 透過在 X 中設定 use_original_dst 並在 Y1 和 Y2 中將 bind_to_port 設定為 false 的情況下，將所有連線重新導向至監聽器 Y1 和 Y2 時，建議停用監聽器 X 中的平衡組態以避免平衡的成本，並在 Y1 和 Y2 中啟用平衡組態以平衡工作執行緒之間的連線。

reuse_port: (bool) 已棄用。請改用 enable_reuse_port。

enable_reuse_port

(BoolValue) 當此標誌設定為 true 時，監聽器會設定 SO_REUSEPORT Socket 選項，並為每個工作執行緒建立一個 Socket。這使得在連線數量較多的情況下，傳入連線可以在工作執行緒之間大致均勻地分配。當此標誌設定為 false 時，所有工作執行緒會共用一個 Socket。此欄位的預設值為 true。當執行階段旗標 envoy.reloadable_features.enable_update_listener_socket_options 啟用時，在監聽器更新期間將拒絕此欄位的變更。否則，此欄位的更新將會被靜默忽略。

注意

雖然此欄位的預設值為 true，但在不同平台上具有不同的行為。請參閱以下文字以取得更多資訊。

在 Linux 上，reuse_port 會同時針對 TCP 和 UDP 監聽器受到尊重。它也可以在熱重新啟動時正常運作。
在 macOS 上，TCP 的 reuse_port 與在 Linux 上的行為不同。最後一個 Socket 會勝出並接收所有連線/封包，而不是負載平衡。對於 TCP，會強制停用 reuse_port 並警告使用者。對於 UDP，則會啟用它，但只有一個工作執行緒會接收封包。對於 QUIC/H3，SW 路由會將封包傳送給其他工作執行緒。對於「原始」UDP，目前只有一個工作執行緒會接收封包。
在 Windows 上，TCP 的 reuse_port 具有未定義的行為。會強制停用它，並警告使用者，與 macOS 類似。目前會保留啟用 UDP 並具有未定義的行為。

access_log: (repeated config.accesslog.v3.AccessLog) 此監聽器發出的存取日誌組態。

tcp_backlog_size: (UInt32Value) TCP 監聽器的待處理連線佇列可成長的最大長度。如果未提供值，則會在 Linux 上使用 net.core.somaxconn，否則會使用 128。

max_connections_to_accept_per_socket_event: (UInt32Value) 每個 Socket 事件從核心接受的最大連線數量。Envoy 可能會在從核心接受這些連線後關閉它們，例如由於負載卸載或其他原則。如果待處理接受的連線數量超過 max_connections_to_accept_per_socket_event，則會於稍後的事件迴圈迭代中接受超過此閾值的連線。如果未提供值，Envoy 將接受核心的所有待處理接受連線。

bind_to_port: (BoolValue) 決定監聽器是否應繫結到埠。未繫結的監聽器只能接收從其他將 use_original_dst 設定為 true 的監聽器重新導向的連線。預設值為 true。

internal_listener

(config.listener.v3.Listener.InternalListenerConfig) 用於表示不接聽 OSI L4 位址的內部監聽器，但 Envoy 叢集可以使用它來建立使用者空間連線。內部監聽器充當 TCP 監聽器。它支援監聽器篩選器和網路篩選器鏈。上游叢集會透過其 name 參照內部監聽器。不得在內部監聽器上設定位址。

有一些源於實作的限制。已知的限制包括

ConnectionBalanceConfig 不允許使用，因為叢集連線和監聽器連線必須由同一個分派器擁有。
tcp_backlog_size
freebind
transparent

獨佔監聽器類型和對應的配置。

enable_mptcp: (bool) 在此監聽器上啟用 MPTCP（多路徑 TCP）。將允許用戶端建立 MPTCP 連線。非 MPTCP 用戶端將回退到常規 TCP。

ignore_global_conn_limit: (bool) 監聽器是否應根據 global_downstream_max_connections 的值來限制連線。

bypass_overload_manager: (bool) 監聽器是否繞過已設定的過載管理器動作。

config.listener.v3.Listener.ConnectionBalanceConfig

[config.listener.v3.Listener.ConnectionBalanceConfig proto]

監聽器連線負載平衡的配置。

{
  "exact_balance": {...},
  "extend_balance": {...}
}

exact_balance

(config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance) 如果指定，監聽器將使用精確連線平衡器。

必須設定 exact_balance 或 extend_balance 中的其中一個。

extend_balance

(config.core.v3.TypedExtensionConfig) 監聽器將根據 type_url 使用連線平衡器。如果 type_url 無效，Envoy 將不會嘗試在工作執行緒之間平衡活動連線。

提示

以下擴充功能僅在 contrib 映像檔中可用

envoy.network.connection_balance.dlb

必須設定 exact_balance 或 extend_balance 中的其中一個。

config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance

[config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance proto]

一種執行精確平衡的連線平衡器實作。這表示在平衡期間會持有鎖定，以便在工作執行緒之間幾乎完全平衡連線計數。這個「幾乎」精確是指連線可能會並行關閉，因此導致計數不正確，但這應該會在下一次接受時修正。此平衡器犧牲了接受吞吐量以換取準確性，應在少量連線且很少循環時使用（例如，服務網格 gRPC 出口）。

config.listener.v3.Listener.InternalListenerConfig

[config.listener.v3.Listener.InternalListenerConfig proto]

Envoy 內部監聽器的配置。所有未來的內部監聽器功能都應在此處新增。

列舉 config.listener.v3.Listener.DrainType

[config.listener.v3.Listener.DrainType proto]

DEFAULT: (預設) ⁣回應呼叫 /healthcheck/fail 管理端點（以及健康檢查篩選器）、監聽器移除/修改和熱重新啟動時進行排空。

MODIFY_ONLY: ⁣回應監聽器移除/修改和熱重新啟動時進行排空。此設定不包含 /healthcheck/fail。如果 Envoy 同時託管入口和出口監聽器，則可能需要此設定。