Envoyフィルター

EnvoyFilter は、Istio Pilot によって生成された Envoy の設定をカスタマイズするメカニズムを提供します。EnvoyFilter を使用して、特定のフィールドの値を変更したり、特定のフィルターを追加したり、完全に新しいリスナーやクラスターなどを追加したりできます。この機能は、誤った設定がメッシュ全体を不安定にする可能性があるため、注意して使用する必要があります。他の Istio ネットワークオブジェクトとは異なり、EnvoyFilter は加算的に適用されます。特定の名前空間の特定のワークロードに対して、任意の数の EnvoyFilter を存在させることができます。これらの EnvoyFilter の適用順序は次のとおりです。設定ルート名前空間内のすべての EnvoyFilter、次にワークロードの名前空間内の一致するすべての EnvoyFilter が続きます。

注 1: この API の一部の側面は、Istio ネットワーキングサブシステムおよび Envoy の XDS API の内部実装に深く結びついています。EnvoyFilter API 自体は下位互換性を維持しますが、このメカニズムを通じて提供される Envoy 構成は、Istio プロキシのバージョンアップグレード全体で注意深く監視し、非推奨のフィールドが削除され、適切に置き換えられていることを確認する必要があります。

注 2: 複数の EnvoyFilter が指定された名前空間の同じワークロードにバインドされている場合、すべてのパッチは作成順に順次処理されます。複数の EnvoyFilter 構成が相互に競合する場合、動作は未定義です。

注 3: システム内のすべてのワークロード (サイドカーとゲートウェイ) に EnvoyFilter リソースを適用するには、ワークロードセレクターなしで、設定ルート名前空間にリソースを定義します。

次の例は、istio-config というルート名前空間でグローバルなデフォルトの EnvoyFilter リソースを宣言し、システム内のすべてのサイドカーのアウトバウンドポート 9307 にカスタムプロトコルフィルターを追加します。フィルターは、効果を発揮するために、終了する tcp_proxy フィルターの前に追加する必要があります。さらに、ゲートウェイとサイドカーの両方で、すべての 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」を持つレビューサービスポッドのサービスポート 8080 に到着するすべてのインバウンド HTTP 呼び出しに対して、Envoy の Lua フィルターを有効にします。lua フィルターは、Envoy で特別なクラスター定義を必要とする外部サービス internal.org.net:8888 を呼び出します。クラスターは、この構成の一部としてサイドカーにも追加されます。

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

次の例では、SNI ホスト app.example.com の istio-system 名前空間のイングレスゲートウェイのリスナーで、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

次の例では、istio_operationId 属性を生成する attributegen フィルターを挿入します。この属性は、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 操作を使用します。フィールドを継承する必要がない場合は、MERGE よりも REPLACE が推奨されます。

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

次の例では、すべてのインバウンドサイドカー 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