[기술분석] Kubernetes Gateway API에서 트래픽을 세밀하게 제어하는 Policy 객체 파헤치기

 

 

[ kt cloud Container Service팀 박지선 님 ]

📋 요약

이 글에서는 Kubernetes Gateway API의 Policy 객체를 활용해 트래픽 동작을 제어하는 방식과 적용 범위를 다룹니다.

운영 환경에서 설정 혼선을 줄이고 안정적인 트래픽 관리를 위한 기준을 정리합니다.

#Kubernetes #GatewayAPI #Policy #ClientSettingsPolicy #BackendTLSPolicy

 

---

1. 개요

이전 편에서 Gateway API 사용해서 Gateway와 HTTPRoute로 기본 라우팅을 구성했다면, 이번 편에서는 Policy 객체로 트래픽을 세밀하게 제어하는 방법을 다룹니다.

 

타임아웃, 세션 유지, 백엔드 TLS 등 기존 Ingress에서 Annotation으로 억지로 처리하던 것들을 표준화된 API로 다루는 방법을 알아보겠습니다.

[기술 분석] kubernetes Ingress API의 중단. 그 뒤를 잇는 Gateway API 파헤치기

---

Policy 객체란?

Gateway API에서 Policy 객체는 Gateway, HTTPRoute, 또는 Service에 붙여서(attach) 트래픽 동작을 제어하는 확장 리소스를 말합니다.

기존 Ingress API에서는 아래 예시와 같이 트래픽 설정들이 전부 Annotation이었는데요,

# 기존 Ingress 방식 — 줄줄이 Annotation 지옥의 예시
annotations:
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
  nginx.ingress.kubernetes.io/affinity: "cookie"
  nginx.ingress.kubernetes.io/ssl-redirect: "true"

Gateway API에서는 이 모든 것이 독립적인 CRD로 분리되어 명시적으로 관리됩니다.

---

Policy 레벨

Gateway API의 Policy는 모든 GatewayClass에서 공통으로 사용 가능한 Policy와 그렇지 않은 Policy가 있습니다. 크게 Standard(표준), Experimental(실험적), Implementation-specific (구현체 전용) 이렇게 3가지 레벨로 분류됩니다.

• Standard : BackendTLSPolicy처럼 어떤 솔루션을 써도 똑같이 동작하는 정책.
• Experimental : 표준화가 진행 중인 정책.
• Implementation-specific : NGINX의 UpstreamSettingsPolicy처럼 특정 엔진의 고유 기능을 제어하기 위해 해당 벤더가 만든 정책.

뒤에 설명할 ClientSettingsPolicy 와 같은 policy는 NGINX Gateway Fabric에서 만든 전용 CRD(Custom Resource Definition)로, Istio와 같은 다른 솔루션 GatewayClass 에서는 다른 방식으로 사용합니다.

---

Policy Attachment 방식

정의된 Policy는 다른 객체에 attach 하여 사용하는데, attach에는 두 가지 방식이 있습니다.

Implementation-specific 레벨의 Policy를 사용 전, docs에서 어떤 방식으로 동작하는 Policy인지 파악이 필요합니다.

Direct Policy Attachment(직접 참조 정책)

정책이 지정한 단일 객체에만 적용되며, 상위/하위 리소스에 영향을 주지 않습니다. 1:1 적용 됩니다.

• standard BackendTLSPolicy / NGinx UpstreamSettingsPolicy → Service (1:1 적용)

Inherited Policy Attachment(상속형 정책)

정책이 계층 구조를 따라 하위로 상속되며, Gateway에 붙이면 하위 모든 HTTPRoute에 영향을 줍니다.

하위 객체에도 적용 되어져 있는 경우, 하위 객체의 정책이 상위보다 Override되어 우선 적용 됩니다.

• NGinx ClientSettingsPolicy → Gateway → (모든 HTTPRoute 상속)
  ↘ HTTPRoute (개별 override 가능)

---

구간 별 Policy 제어 범위

Policy 별로 트래픽을 제어하는 범위가 다릅니다. 따라서 구간 별 세세하게 설정을 다르게 커스텀 할 수 있습니다.

• NGinx ClientSettingsPolicy 의 경우, 가장 앞단에서 Client와 Gateway 객체 간 트래픽을 제어합니다.
• standard BackendTLSPolicy 의 경우, Gateway 와 실제 Service(Pod) 객체 간 트래픽을 제어합니다.

 

트래픽 흐름에서 Policy가 적용되는 구간을 그림으로 표현하면 이러합니다.

Nginx Gateway Class에서 제공하는 ClientSettingsPolicy와 Gateway API 표준인 BackendTLSPolicy를 좀더 자세히 살펴보겠습니다.

---

클라이언트 트래픽 제어: ClientSettingsPolicy

ClientSettingsPolicy 는 클라이언트(사용자 브라우저/앱)와 NGINX Gateway 사이의 연결 동작을 설정합니다. keepalive, client body max size등을 제어하며 Inherited Policy로 동작합니다.

 

주요 설정 항목

필드	설명
keepAlive.requests	keepalive 커넥션당 최대 요청 수
keepAlive.time	keepalive 커넥션 유지 시간
body.maxSize	client max body size 수

 

예시1) Gateway 전체에 적용

# ClientSettingsPolicy — Gateway 레벨 (모든 HTTPRoute에 상속)
apiVersion: gateway.nginx.org/v1alpha1
kind: ClientSettingsPolicy
metadata:
  name: global-client-settings
  namespace: sample
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: cafe
  keepAlive:
    requests: 1000
    time: 1h
    timeout:
      server: 60s
      header: 30s

 

 

예시2) 특정 HTTPRoute에만 override 적용

# ClientSettingsPolicy — HTTPRoute 레벨 (개별 서비스 override)
apiVersion: gateway.nginx.org/v1alpha1
kind: ClientSettingsPolicy
metadata:
  name: coffee-client-settings
  namespace: sample
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: coffee
  keepAlive:
    timeout:
      server: 10s   # Gateway 설정(60s)을 이 Route에서만 10s로 단축

# 적용 확인
kubectl -nsample get clientsettingspolicy
kubectl -nsample describe clientsettingspolicy global-client-settings

---

백엔드 TLS 설정: BackendTLSPolicy

이 Policy는 Gateway와 백엔드 Pod 사이의 TLS 연결을 설정하는 Direct Policy로, 지정한 Service에만 적용됩니다. mTLS 구성이나 내부 서비스 간 암호화가 필요한 환경에서 사용할 수 있습니다.

 

BackendTLSPolicy 생성

apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: coffee-backend-tls
  namespace: sample
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: coffee       # TLS를 적용할 백엔드 Service
      sectionName: "443"
  validation:
    hostname: coffee.sample.svc.cluster.local   # 백엔드 인증서의 SNI
    caCertificateRefs:
      - group: ""
        kind: ConfigMap
        name: backend-ca  # comfigMap으로 인증서 등록 후 설정

# 확인
kubectl -nsample get backendtlspolicy
kubectl -nsample describe backendtlspolicy coffee-backend-tls

주의: BackendTLSPolicy는 Service와 같은 namespace에 있어야 합니다.

---

객체에 직접 설정 항목

Policy 객체 외에도 HTTPRoute 자체에서 타임아웃과 재시도를 설정할 수도 있습니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: coffee
  namespace: sample
spec:
  parentRefs:
    - name: cafe
  hostnames:
    - "cafe.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      timeouts:
        request: 10s        # 클라이언트 요청 전체 타임아웃
        backendRequest: 5s  # 백엔드 응답 타임아웃
      retry:
        attempts: 3
        backoff: 500ms
        codes:
          - 502
          - 503
          - 504
      backendRefs:
        - name: coffee
          port: 80

• HTTPRoute의 timeouts는 백엔드 응답 타임아웃, ClientSettingsPolicy의 timeout은 클라이언트-NGINX 연결 타임아웃으로 역할이 다릅니다. 둘 다 설정하는 것이 일반적이다.

---

주의사항

• Policy가 적용되지 않아도 에러가 발생하지 않는 경우가 있으므로, 반드시 생성 후 status 확인을 해야 합니다.

kubectl -nsample describe clientsettingspolicy global-client-settings
# Status.Conditions.Type: Accepted 확인

• Policy 객체는 기본적으로 같은 namespace의 리소스에만 attach할 수 있습니다. 다른 namespace 간 적용은 별도 ReferenceGrant가 필요합니다.

---

마무리

Gateway API의 Policy 객체는 기존 Annotation 방식 대비 명확한 역할 분리와 재사용성을 제공합니다.

다만, Policy마다 트래픽 제어 구간, attach 방식, 표준Policy 여부 등이 상이하므로 docs 문서를 잘 확인 후 사용해야 합니다.

정책	적용 대상	attach 방식	주요 용도
ClientSettingsPolicy	Gateway / HTTPRoute	Inherited	클라이언트 연결 타임아웃, keepalive 설정 등
BackendTLSPolicy	Service	Direct	백엔드 TLS 암호화
HTTPRoute timeout/retry	HTTPRoute (내장)	-	백엔드 타임아웃, 재시도

 

---

❓ 자주 묻는 질문 (FAQ)

Q. Policy 객체란?

A. Gateway API에서 Policy 객체는 Gateway, HTTPRoute, 또는 Service에 붙여서(attach) 트래픽 동작을 제어하는 확장 리소스를 말합니다. 기존 Ingress API에서는 아래 예시와 같이 트래픽 설정들이 전부 Annotation이었는데요, Gateway API에서는 이 모든 것이 독립적인 CRD로 분리되어 명시적으로 관리됩니다.

---

📚 관련/출처

Policy Attachment - Kubernetes Gateway API 공식 ClientSettingsPolicy | NGINX Gateway Fabric 공식 문서 BackendTLSPolicy - Kubernetes Gateway API