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 압축기 필터는 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) 전반에 유효성 검사가 점진적으로 출시됩니다. 컨트롤 플레인 유효성 검사는 배포가 발생한 시점을 기준으로 적용됩니다.

배포 유형	유효성 검사 동작
기존 배포 (유효성 검사가 사용 설정되기 전에 배포됨)	컨트롤 플레인은 found usage of unsupported fields: [...]를 읽는 EnvoyFilter 커스텀 리소스 (CR)에 경고 상태를 설정합니다. 이 구성은 이전 버전과의 호환성을 위해 계속 적용되지만 계속 지원을 받으려면 지원되는 필드로 마이그레이션해야 합니다.
지원되는 배포 (유효성 검사가 사용 설정된 후 배포됨)	컨트롤 플레인은 지원되지 않는 필드의 사용을 엄격하게 차단합니다. 구성을 적용하면 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

EnvoyFilter가 envoy.filters.http.compressor를 패치하는 출력을 검사합니다.

구성 형식

다음 섹션에서는 EnvoyFilter 리소스 내에서 압축기 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 구성을 업데이트하는 것이 좋습니다. 마이그레이션 중에 다음 일반적인 단계를 고려하세요.

• 식별: 지원 중단된 구성 식별에 설명된 대로 지원 중단된 필드가 있는 압축기 필터를 사용하여 모든 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 프록시 로그에서 자세한 오류 메시지(kubectl logs -l app=your-app -c istio-proxy -n your-namespace)를 검사합니다.
• 필요한 경우 이전 EnvoyFilter 구성으로 롤백합니다.
• 추가 지원이 필요하면 지원팀에 문의하세요. Google Cloud