Istio EnvoyFilter

#kubernetes/object #cncf/istio/extensibility/envoy-filter #cncf/envoy

개요

엔보이 필터는 말 그대로 엔보이 설정을 직접적으로 만드는 리소스이다.
기본적으로 이스티오에서 제공하는 엔보이 관련 설정 이외에, 지원되지 않고 있는 기능이나 직접적으로 커스텀한 필터를 넣고 싶을 때 직접적으로 엔보이 관련 설정 리소스를 만들고 이것이 엔보이에 적용되도록 할 수 있다.

엔보이 필터는 엔보이 설정을 넣는 방식이다보니 자유도가 매우 높고 커스텀이 자유롭다.
그래서 휴먼 에러로 인해 잘못 설정했다가 서비스 메시 전체가 망가질 수도 있기 때문에 조심하게 사용할 필요가 있다.
흔히 고급 사용자 기능이랄까..

또한 이스티오, 엔보이 두 소프트웨어에서 엔보이 필터에 대한 버전 호환성을 고려해주지 않으므로 도입을 한다면 이 점까지 고려해야 한다.
혹시 라우팅 필터 관련한 설정만 넣으려는 거라면 Istio WasmPlugin이 나름의 대안이 될 수 있으니 참고하자.

특징

기능은 위에서 다 말했고, 몇 가지 특징을 보자.

이스티오 루트 네임스페이스(보통 istio-system)의 설정이 먼저 적용되고, 이후에 각 네임스페이스별 설정이 적용된다.
같은 네임스페이스 간에는 먼저 생성 시점 순으로 설정이 적용된다.
사이드카와 게이트웨이 전체에 걸친 엔보이에 설정을 가하려면 루트 네임스페이스에서 셀렉터 없이 설정한다.

또한 엔보이 필터의 적용 순서는 가장 마지막이다.
이스티오 버츄얼서비스, 이스티오 데스티네이션룰 등의 리소스가 있는 상황이라면 이 설정들이 전부 먼저 적용된 이후에 마지막으로 엔보이 필터의 설정이 적용된다.
여러 엔보이 필터가 있다면 생성 시간을 기준으로 적용된다.

양식 작성법

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: custom-protocol
  namespace: istio-config # 이스티오 세팅 시 설정된 meshConfig에 있다.
spec:
  # 적용할 엔보이 라벨 셀렉팅
  workloadSelector:
    labels:
      app: mysvc
  # 적용할 리소스 유형과 이름
  # Waypoint 프록시는 무조건 이걸로 타겟팅해야 한다고 한다.
  targetRefs:
  - name: waypoint
    kind: Gateway
    group: gateway.networking.k8s.io
  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

기본적인 설정은 전부 configPatches에서 진행된다.
workloadSelector와 targetRefs는 대상이 될 엔보이를 선별하는 필드이고, 여기에 추가적으로 priority 필드로 적용 순서를 명시하는 방법이 있긴 하다.
priority는 위에서 언급한 모든 순서 앞단에서 명시적으로 설정되는 순위라 보면 되겠다.
아무튼 핵심이 되는 configPatches를 중점적으로 보면 된다.

applyTo

엔보이 설정 어디에 적용돼야 하는지 나타내는 필드이다.
가령 여기에 HTTP_FILTER를 넣으면 envoy.filters.network.http_connection_manager를 설정 대상으로 잡는다.

사용할 수 있는 필드는 이렇게 된다.
보다시피 엔보이의 설정 구조에 대한 이해가 필수적이다..

이름을 보면 짐작할 수 있겠지만, 체인 리스트에 적용하고 싶은 건지, 아니면 특정 체인에 적용하고자 하는 건지 지정해야 한다.
아니면 라우트 설정에 대해 적용할 수도 있고..

match

    match:
      context: GATEWAY
      routeConfiguration:
        vhost:
          domainName: 'foo.com'

조작을 가하기 전 매칭할 세부 설정을 지정하는 필드이다.
context 필드를 통해 정확하게 어떤 범위에 적용되는 건지 명시한다.

그리고 다음의 필드들을 통해 정확하게 위치를 특정한다.
applyTo에 명시한 영역에 따라, context 필드에 따라 사용할 수 없는 필드도 당연히 있고, 이는 검증 에러를 띄울 것이다.

엔보이 설정이 워낙 다양하다보니 매칭 조건도 너무 세분화돼있다..
일일히 기억하고 외우기 보단 이런 게 있구나 하고 알아두는 게 좋을 듯.

patch

    patch:
      operation: ADD
	  filterClass: STATS
      value:
        rate_limits:
          actions:
            - request_headers: 
                header_name: "authorization"
                descriptor_key: "jwt"
            - request_headers:
                header_name: ":path"
                descriptor_key: "path"

매칭된 부분에 어떤 조작을 가할지 정하는 필드이다.
vaule 필드에 실제 엔보이에 들어가게될 설정을 그대로 적어주면 된다.

operation은 다음의 필드가 가능하다.

ADD operatation에다가 filterClass필드를 이용할 수도 있다.
기본으로 부여되는 몇 가지 필터들 몇 가지에 대해 적용할 때 사용하는 방식이고, value에 적힌 값이 추가되는 식으로 동작한다.

관련 문서

EXPLAIN - 파생 문서

이름1related생성 일자
이스티오에서 엔보이 기능 확장하기이스티오 스케일링2025-06-01 14:06

기타 문서

Z0-연관 knowledge, Z1-트러블슈팅 Z2-디자인,설계, Z3-임시, Z5-프로젝트,아카이브, Z8,9-미분류,미완
이름2코드타입생성 일자
4W - 이스티오 메트릭 커스텀, 프로메테우스와 그라파나Z8published2025-05-03 22:16
7W - 엔보이 필터를 통한 기능 확장Z8published2025-06-09 02:30

참고