Envoy 過濾器

EnvoyFilter 提供一種機制來自訂 Istio Pilot 產生的 Envoy 設定。使用 EnvoyFilter 修改特定欄位的值、新增特定篩選器，甚至新增全新的監聽器、叢集等。必須謹慎使用此功能，因為不正確的設定可能會導致整個網格不穩定。與其他 Istio 網路物件不同，EnvoyFilter 是以累加方式套用。在特定命名空間中，一個給定的工作負載可以存在任意數量的 EnvoyFilter。這些 EnvoyFilter 的套用順序如下：設定 根命名空間 中的所有 EnvoyFilter，然後是工作負載命名空間中的所有符合的 EnvoyFilter。

注意 1：此 API 的某些方面與 Istio 網路子系統和 Envoy 的 XDS API 的內部實作緊密相關。雖然 EnvoyFilter API 本身會保持向後相容性，但應在 Istio Proxy 版本升級時仔細監控透過此機制提供的任何 Envoy 設定，以確保已移除已棄用的欄位並適當取代。

注意 2：當多個 EnvoyFilter 在給定命名空間中繫結到相同的工作負載時，所有修補程式將依建立時間順序依序處理。如果多個 EnvoyFilter 設定彼此衝突，則行為未定義。

注意 3：若要將 EnvoyFilter 資源套用至系統中的所有工作負載（Sidecar 和閘道），請在設定 根命名空間 中定義資源，而不要使用 workloadSelector。

以下範例在根命名空間中宣告一個名為 istio-config 的全域預設 EnvoyFilter 資源，該資源會在系統中所有 sidecar 上針對出站連接埠 9307 新增自訂通訊協定篩選器。此篩選器應在終止的 tcp_proxy 篩選器之前新增，才會生效。此外，它會為閘道和 sidecar 中的所有 HTTP 連線設定 30 秒的閒置逾時。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: custom-protocol
  namespace: istio-config # as defined in meshConfig resource.
spec:
  configPatches:
  - applyTo: NETWORK_FILTER
    match:
      context: SIDECAR_OUTBOUND # will match outbound listeners in all sidecars
      listener:
        portNumber: 9307
        filterChain:
          filter:
            name: "envoy.filters.network.tcp_proxy"
    patch:
      operation: INSERT_BEFORE
      value:
        # This is the full filter config including the name and typed_config section.
        name: "envoy.extensions.filters.network.mongo_proxy"
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.mongo_proxy.v3.MongoProxy"
          ...
  - applyTo: NETWORK_FILTER # http connection manager is a filter in Envoy
    match:
      # context omitted so that this applies to both sidecars and gateways
      listener:
        filterChain:
          filter:
            name: "envoy.filters.network.http_connection_manager"
    patch:
      operation: MERGE
      value:
        name: "envoy.filters.network.http_connection_manager"
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"
          common_http_protocol_options:
            idle_timeout: 30s

以下範例針對 bookinfo 命名空間中標籤為「app: reviews」的 reviews 服務 Pod 的服務連接埠 8080 上收到的所有入站 HTTP 呼叫啟用 Envoy 的 Lua 篩選器。Lua 篩選器會呼叫外部服務 internal.org.net:8888，該服務需要在 Envoy 中進行特殊的叢集定義。此叢集也會做為此設定的一部分新增至 sidecar。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: reviews-lua
  namespace: bookinfo
spec:
  workloadSelector:
    labels:
      app: reviews
  configPatches:
    # The first patch adds the lua filter to the listener/http connection manager
  - applyTo: HTTP_FILTER
    match:
      context: SIDECAR_INBOUND
      listener:
        portNumber: 8080
        filterChain:
          filter:
            name: "envoy.filters.network.http_connection_manager"
            subFilter:
              name: "envoy.filters.http.router"
    patch:
      operation: INSERT_BEFORE
      value: # lua filter specification
       name: envoy.filters.http.lua
       typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua"
          defaultSourceCode:
            inlineString: |
              function envoy_on_request(request_handle)
                -- Make an HTTP call to an upstream host with the following headers, body, and timeout.
                local headers, body = request_handle:httpCall(
                 "lua_cluster",
                 {
                  [":method"] = "POST",
                  [":path"] = "/acl",
                  [":authority"] = "internal.org.net"
                 },
                "authorize call",
                5000)
              end
  # The second patch adds the cluster that is referenced by the lua code
  # cds match is omitted as a new cluster is being added
  - applyTo: CLUSTER
    match:
      context: SIDECAR_OUTBOUND
    patch:
      operation: ADD
      value: # cluster specification
        name: "lua_cluster"
        type: STRICT_DNS
        connect_timeout: 0.5s
        lb_policy: ROUND_ROBIN
        load_assignment:
          cluster_name: lua_cluster
          endpoints:
          - lb_endpoints:
            - endpoint:
                address:
                  socket_address:
                    protocol: TCP
                    address: "internal.org.net"
                    port_value: 8888

以下範例會針對 istio-system 命名空間中 SNI 主機 app.example.com 的輸入閘道上的接聽程式，覆寫 HTTP 連線管理員中的特定欄位 (HTTP 閒置逾時和 X-Forward-For 信任躍點)。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: hcm-tweaks
  namespace: istio-system
spec:
  workloadSelector:
    labels:
      istio: ingressgateway
  configPatches:
  - applyTo: NETWORK_FILTER # http connection manager is a filter in Envoy
    match:
      context: GATEWAY
      listener:
        filterChain:
          sni: app.example.com
          filter:
            name: "envoy.filters.network.http_connection_manager"
    patch:
      operation: MERGE
      value:
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"
          xff_num_trusted_hops: 5
          common_http_protocol_options:
            idle_timeout: 30s

以下範例會插入一個 attributegen 篩選器，該篩選器會產生 istio_operationId 屬性，供 istio.stats 篩選器取用。filterClass: STATS 會對此相依性進行編碼。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: reviews-request-operation
  namespace: myns
spec:
  workloadSelector:
    labels:
      app: reviews
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: SIDECAR_INBOUND
    patch:
      operation: ADD
      filterClass: STATS # This filter will run *before* the Istio stats filter.
      value:
        name: istio.request_operation
        typed_config:
         "@type": type.googleapis.com/udpa.type.v1.TypedStruct
         type_url: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
         value:
           config:
             configuration: |
               {
                 "attributes": [
                   {
                     "output_attribute": "istio_operationId",
                     "match": [
                       {
                         "value": "ListReviews",
                         "condition": "request.url_path == '/reviews' && request.method == 'GET'"
                       }]
                   }]
               }
             vm_config:
               runtime: envoy.wasm.runtime.null
               code:
                 local: { inline_string: "envoy.wasm.attributegen" }

以下範例會在 myns 命名空間中插入一個 http ext_authz 篩選器。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: myns-ext-authz
  namespace: myns
spec:
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: SIDECAR_INBOUND
    patch:
      operation: ADD
      filterClass: AUTHZ # This filter will run *after* the Istio authz filter.
      value:
        name: envoy.filters.http.ext_authz
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
          grpc_service:
            envoy_grpc:
              cluster_name: acme-ext-authz
            initial_metadata:
            - key: foo
              value: myauth.acme # required by local ext auth server.

myns 命名空間中的工作負載需要存取不接受初始中繼資料的不同 ext_auth 伺服器。由於 proto 合併無法移除欄位，因此下列設定會使用 REPLACE 作業。如果您不需要繼承欄位，則建議使用 REPLACE 而非 MERGE。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: mysvc-ext-authz
  namespace: myns
spec:
  workloadSelector:
    labels:
      app: mysvc
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: SIDECAR_INBOUND
    patch:
      operation: REPLACE
      value:
        name: envoy.filters.http.ext_authz
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
          grpc_service:
            envoy_grpc:
              cluster_name: acme-ext-authz-alt

以下範例會針對所有入站 sidecar HTTP 要求部署 Wasm 擴充功能。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: wasm-example
  namespace: myns
spec:
  configPatches:
  # The first patch defines a named Wasm extension and provides a URL to fetch Wasm binary from,
  # and the binary configuration. It should come before the next patch that applies it.
  # This resource is visible to all proxies in the namespace "myns". It is possible to provide
  # multiple definitions for the same name "my-wasm-extension" in multiple namespaces. We recommend that:
  # - if overriding is desired, then the root level definition can be overridden per namespace with REPLACE.
  # - if overriding is not desired, then the name should be qualified with the namespace "myns/my-wasm-extension",
  #   to avoid accidental name collisions.
  - applyTo: EXTENSION_CONFIG
    patch:
      operation: ADD
      value:
        name: my-wasm-extension
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
          config:
            root_id: my-wasm-root-id
            vm_config:
              vm_id: my-wasm-vm-id
              runtime: envoy.wasm.runtime.v8
              code:
                remote:
                  http_uri:
                    uri: http://my-wasm-binary-uri
            configuration:
              "@type": "type.googleapis.com/google.protobuf.StringValue"
              value: |
                {}
  # The second patch instructs to apply the above Wasm filter to the listener/http connection manager.
  - applyTo: HTTP_FILTER
    match:
      listener:
        filterChain:
          filter:
            name: envoy.filters.network.http_connection_manager
            subFilter:
              name: envoy.filters.http.router
    patch:
      operation: INSERT_BEFORE
      value:
        name: my-wasm-extension # This must match the name above
        config_discovery:
          config_source:
            ads: {}
          type_urls: ["type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm"]

以下範例會在 envoy.filters.listener.tls_inspector 之前插入 envoy.filters.listener.proxy_protocol 接聽程式篩選器。

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: listener-filter-example
  namespace: myns
spec:
  configPatches:
  - applyTo: LISTENER_FILTER
    match:
      context: SIDECAR_INBOUND # will match inbound listeners in all sidecars
      listener:
        portNumber: 15006
        listenerFilter: "envoy.filters.listener.tls_inspector"
    patch:
      operation: INSERT_BEFORE
      value:
        # This is the full filter config including the name and typed_config section.
        name: "envoy.filters.listener.proxy_protocol"
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol"

EnvoyFilter

EnvoyFilter.ProxyMatch

EnvoyFilter.ClusterMatch

EnvoyFilter.RouteConfigurationMatch

EnvoyFilter.ListenerMatch

EnvoyFilter.Patch

EnvoyFilter.EnvoyConfigObjectMatch

EnvoyFilter.EnvoyConfigObjectPatch

EnvoyFilter.RouteConfigurationMatch.RouteMatch

EnvoyFilter.RouteConfigurationMatch.VirtualHostMatch

EnvoyFilter.ListenerMatch.FilterChainMatch

EnvoyFilter.ListenerMatch.FilterMatch

EnvoyFilter.ListenerMatch.SubFilterMatch

EnvoyFilter.RouteConfigurationMatch.RouteMatch.Action

EnvoyFilter.Patch.Operation

EnvoyFilter.Patch.FilterClass

EnvoyFilter.ApplyTo

EnvoyFilter.PatchContext