更新 EnvoyFilter 壓縮器設定

envoy.extensions.filters.http.compressor.v3.Compressor 篩選器的 API 介面中有幾個頂層欄位已在 Envoy 中淘汰 (請參閱來源定義)。這些設定已移至專屬的 response_direction_config.common_config 和 request_direction_config.common_config 區塊。

本指南提供更新EnvoyFilter資源的背景資訊和必要步驟，協助您將資源轉換為支援的格式。改用這種新式格式，可確保設定與後續更新保持相容，並享有結構更清楚的優點，同時符合 Cloud Service Mesh 現代化最佳做法。

瞭解現代化需求

Envoy Compressor 篩選器可即時壓縮及解壓縮 HTTP 主體，有助於減少頻寬用量及提升應用程式效能。

使用 TRAFFIC_DIRECTOR 控制層的 Cloud Service Mesh (請參閱「檢查控制層實作」)，需要使用支援的 EnvoyFilter API 版本。使用已淘汰頂層欄位 (例如 content_length、content_type、disable_on_etag_header、remove_accept_encoding_header 或 runtime_enabled) 的舊版部署作業仍可繼續運作，但建議立即更新，以確保可靠性。

使用這些已淘汰的欄位時，系統會逐步在各發布版本 (Rapid、Regular，然後是 Stable) 中推出驗證功能。控制層驗證會根據部署作業的發生時間套用：

部署作業類型 驗證行為
舊版部署作業 (在啟用驗證功能前部署) 控制層會在您的 EnvoyFilter 自訂資源 (CR) 上設定「警告」狀態，內容為：found usage of unsupported fields: [...]。為確保回溯相容性，系統仍會套用設定，但您必須遷移至支援的欄位，才能確保持續支援。
支援的部署作業 (在啟用驗證後部署) 控制層會嚴格禁止使用不支援的欄位。套用設定後，EnvoyFilter 資源會發生錯誤，並顯示「found usage of unsupported fields: [...]」訊息，系統也會拒絕不支援的設定。

更新設定即可解決資源狀態中的這些警告和錯誤，並確保設定符合驗證條件。

找出已淘汰的設定

如果您直接在 typed_config 區塊下方設定下列任何欄位，就必須更新 EnvoyFilter 設定：

  • min_content_length
  • content_length
  • content_type
  • disable_on_etag_header
  • remove_accept_encoding_header

您可以使用下列指令列出 EnvoyFilter：

kubectl get envoyfilters --all-namespaces -o yaml

檢查 EnvoyFilters 修補程式的輸出內容 envoy.filters.http.compressor。

設定格式

以下各節提供範例，說明 EnvoyFilter 資源中 Compressor Envoy 篩選器的已淘汰和新式設定。

已淘汰的設定範例

如果 EnvoyFilter 的修補程式部分類似下列程式碼片段，則表示使用已淘汰的格式：

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: compressor-filter-update
  namespace: istio-system
spec:
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: GATEWAY
      listener:
        filterChain:
          filter:
            name: envoy.filters.network.http_connection_manager
            subFilter:
              name: envoy.filters.http.router
    patch:
      operation: INSERT_BEFORE
      value:
        name: envoy.filters.http.compressor
        typed_config:
          '@type': type.googleapis.com/envoy.extensions.filters.http.compressor.v3.Compressor
          # These top-level fields are DEPRECATED
          min_content_length: 1024
          content_type:
          - "application/javascript"
          - "application/json"
          disable_on_etag_header: true
          remove_accept_encoding_header: true
          compressor_library:
            name: gzip
            typed_config:
              '@type': type.googleapis.com/envoy.extensions.compression.gzip.compressor.v3.Gzip

新版設定範例

已淘汰的欄位必須移至 response_direction_config 物件 (或 request_direction_config，如適用)：

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: compressor-filter-update
  namespace: istio-system
spec:
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: GATEWAY
      listener:
        filterChain:
          filter:
            name: envoy.filters.network.http_connection_manager
            subFilter:
              name: envoy.filters.http.router
    patch:
      operation: INSERT_BEFORE
      value:
        name: envoy.filters.http.compressor
        typed_config:
          '@type': type.googleapis.com/envoy.extensions.filters.http.compressor.v3.Compressor
          compressor_library:
            name: gzip
            typed_config:
              '@type': type.googleapis.com/envoy.extensions.compression.gzip.compressor.v3.Gzip
          response_direction_config:
            disable_on_etag_header: true # MOVED
            remove_accept_encoding_header: true # MOVED
            common_config:
              min_content_length: 1024  # MOVED
              content_type:          # MOVED
              - "application/javascript"
              - "application/json"
              enabled:
                default_value: true
                runtime_key: "compressor.enabled"

支援的欄位和遷移路徑

如需支援欄位的完整清單，請參閱「使用 EnvoyFilter 擴充資料平面」指南。下表詳細列出最常見的已淘汰欄位遷移對應關係。

已淘汰的欄位路徑 現代化欄位路徑 附註
typed_config.min_content_length typed_config.response_direction_config.common_config.min_content_length
或
typed_config.request_direction_config.common_config.min_content_length		 設定觸發壓縮的最低回應或要求大小。
typed_config.content_length typed_config.response_direction_config.common_config.min_content_length
或
typed_config.request_direction_config.common_config.min_content_length		 min_content_length 的舊別名，在新路徑中重新命名為 min_content_length。
typed_config.content_type typed_config.response_direction_config.common_config.content_type
或
typed_config.request_direction_config.common_config.content_type		 要壓縮的內容類型陣列。
typed_config.disable_on_etag_header typed_config.response_direction_config.disable_on_etag_header 如果回應含有 ETag 標頭，則停用壓縮功能。
typed_config.remove_accept_encoding_header typed_config.response_direction_config.remove_accept_encoding_header 在將要求傳送至上游之前，先從要求中移除 Accept-Encoding 標頭。

遷移計畫

建議您按照貴機構的標準部署和測試最佳做法，更新 EnvoyFilter 設定。遷移期間，請考慮執行下列一般步驟：

  • 找出：使用 Compressor 篩選器找出所有 EnvoyFilter 資源，並搭配已淘汰的欄位，如「找出已淘汰的設定」一文所述。
  • 測試：修改 EnvoyFilter 資源的 YAML，並在預先發布環境中測試變更。確認壓縮功能已針對預期的內容類型和大小啟用。
  • 監控及驗證：
    • 檢查 EnvoyFilter 資源狀態，確認 found usage of unsupported fields: [...] 警告或錯誤已不再出現。
    • 監控重要指標：CPU 使用率、延遲時間和頻寬用量。
    • 檢查回應標頭 (例如 Content-Encoding: gzip)，並確認壓縮。
  • 部署：將支援的 EnvoyFilter 設定套用至正式版工作負載。

現代化的福利

  • 資源狀態清楚明瞭：從壓縮器 EnvoyFilter 資源狀態中移除 found usage of unsupported fields: [...] 警告和錯誤。
  • 標準化：符合目前的 Envoy 設定最佳做法和TRAFFIC_DIRECTOR驗證。
  • 未來相容性：確保設定能與即將推出的 Envoy 和 Cloud Service Mesh 版本順暢運作。

疑難排解與支援

如果遇到問題，請考慮下列事項：

  • 請仔細檢查 YAML 語法和欄位位置。
  • 檢查 Envoy Proxy 記錄，瞭解詳細的錯誤訊息：kubectl logs -l app=your-app -c istio-proxy -n your-namespace。
  • 如有需要，請回復先前的 EnvoyFilter 設定。
  • 如需進一步協助，請與 Google Cloud 支援團隊聯絡。