NGINX Ingress 어노테이션 → Gateway API 마이그레이션

NGINX Ingress 어노테이션 → Gateway API 마이그레이션 (NGINX Ingress Annotations to Gateway API Migration)

이 페이지는 Cilium 환경에서 Gateway API로 이동할 때 NGINX Ingress 어노테이션을 위한 실용적인 마이그레이션 가이드를 제공해요. 흔한 어노테이션 패턴과 그에 가장 가까운 Gateway API 등가물 또는 대안에 초점을 맞춰요.

출처: NGINX Ingress Annotations to Gateway API Migration

본문

이 페이지는 Cilium 환경에서 Gateway API로 이동할 때 NGINX Ingress 어노테이션을 위한 실용적인 마이그레이션 가이드를 제공해요.

이 가이드는 흔한 어노테이션 패턴과 그에 가장 가까운 Gateway API 등가물이나 대안에 초점을 맞춰요.

마이그레이션 분류 모델 (Migration Triage Model)

어노테이션을 마이그레이션할 때는 이 순서를 사용해주세요:

  • 직접 매핑 (Direct mapping): 어노테이션을 네이티브 Gateway API 필드와 필터로 교체해요.
  • 확장 의존 (Extension-dependent): 환경이 필요한 실험적 또는 구현별 확장을 지원하는 경우에만 마이그레이션해요.
  • 등가물 없음 / 계획 없음 (No equivalent / not planned): 1:1 번역을 찾는 대신 동작(정책, 앱 또는 플랫폼 설정)을 재설계해요.

참고

매핑이 GEP나 실험적 API를 참조할 때는 설치된 Gateway API 버전과 Cilium 릴리스 양쪽에서 기능 지원을 확인해주세요. Not yet supported(아직 미지원)으로 표시된 항목은 오늘날 Cilium 구현이 없으며 향후 릴리스에서 추가될 수 있어요.

기존 NGINX 어노테이션 인벤토리화 (Inventory Existing NGINX Annotations)

변환하기 전에 현재 사용 중인 어노테이션을 추출해볼게요:

kubectl get ingress -A -o json \
  | jq -r '.items[]
  | [.metadata.namespace, .metadata.name,
     ((.metadata.annotations // {}) | to_entries[]
      | select(.key | startswith("nginx.ingress.kubernetes.io/"))
      | "\(.key)=\(.value)")] | @tsv'

빈도와 프로덕션 중요도(auth, redirect, timeout, TLS, 소스 제한 어노테이션 우선)로 우선순위를 정해주세요.

흔한 직접 매핑 (Common Direct Mappings)

NGINX 어노테이션 Gateway API 등가물 외부 참조 Cilium 지원 비고
canary-weight HTTPRoute.rules.backendRefs[].weight Traffic Splitting Guide Yes 가중치 트래픽 분할
canary-by-header HTTPRoute.rules.matches.headers Traffic Splitting Guide Yes 카나리를 위해 가중치 backendRefs와 결합
use-regex HTTPRouteMatch.path.type: RegularExpression HTTP Routing Guide Yes Cilium에서 지원되지만, Gateway API에서 정규식 일치는 여전히 구현별이에요
rewrite-target HTTPRoute.filters.type: URLRewrite Redirects and Rewrites Guide Yes 규칙별 rewrite 필터 사용
force-ssl-redirect HTTPRoute.filters.type: RequestRedirect Redirects and Rewrites Guide Yes 라우트 레벨에서 HTTP를 HTTPS로 리다이렉트
permanent-redirect HTTPRoute.filters.type: RequestRedirect Redirects and Rewrites Guide Yes 영구 리다이렉트 동작 설정
proxy-read-timeout HTTPRoute.rules.timeouts.backendRequest HTTP Timeouts Guide Yes 업스트림 응답 타이밍에 가장 가까운 매칭; 종단 간 request 타임아웃 의미론과 주의 깊게 비교
proxy-next-upstream-tries HTTPRoute.rules.retry.attempts GEP-1731 Yes Gateway API에서 실험적(GEP-1731). 재시도 횟수만 매핑하고 전체 proxy-next-upstream* 동작 집합은 아님
kubernetes.io/ingress.class Gateway.spec.gatewayClassName Gateway API Overview Yes 컨트롤러 선택 모델 교체. kubernetes.io/ 접두사(nginx가 아님)를 사용하므로 위 NGINX 범위 인벤토리에는 나타나지 않음
server-alias HTTPRoute.spec.hostnames Gateway API Overview Yes 대체 호스트 이름을 명시적으로 마이그레이션
backend-protocol Service.spec.ports[].appProtocol GEP-1911 Yes (gatewayAPI.enableAppProtocol 활성화) 백엔드 프로토콜 힌트용
enable-cors HTTPRoute.filters.type: CORS GEP-1767 Not yet supported Gateway API에서 실험적(GEP-1767)
proxy-ssl-secret BackendTLSPolicy.spec.validation.caCertificateRefs BackendTLSPolicy Yes 백엔드 TLS 신뢰 자료
proxy-ssl-verify BackendTLSPolicy.spec.validation BackendTLSPolicy Yes CA 및 검증 동작
secure-backends BackendTLSPolicy BackendTLSPolicy Yes 백엔드 TLS에 정책 부착 사용

복잡한 매핑과 확장 의존 사례 (Complex Mappings and Extension-Dependent Cases)

다음 어노테이션은 오늘날 직접적인 Gateway API 등가물이 없어요. 마이그레이션은 구현별 확장이나 업스트림 GEP가 Gateway API 표준으로 승격되는 것에 달려 있어요. 달리 표시되지 않는 한, Cilium은 이러한 매핑을 아직 지원하지 않아요.

NGINX 어노테이션 제안된 접근 외부 참조 Cilium 지원 복잡도
upstream-hash-by 구현별 트래픽 정책 확장 - Not yet supported High
keep-alive, keepalive-*, upstream-keepalive-* 구현별 데이터 플레인 튜닝 정책 - Not yet supported High
auth-type, auth-url ExternalAuth-스타일 HTTPRoute 필터 (실험적) GEP-1494 Not yet supported High
auth-tls-secret, auth-tls-verify-client 프론트엔드/클라이언트 인증서 검증 확장 GEP-91 Not yet supported High
기타 proxy-next-upstream* 어노테이션 재시도 및 타임아웃 필드 (일부 실험적) GEP-1731, GEP-1742 Not yet supported High
tcp-services-configmap TCPRoute 리소스 (실험적 채널) TCPRoute Not yet supported High
use-forwarded-headers 구현별 클라이언트 트래픽 정책 - Not yet supported High
whitelist-source-range Cilium 네트워크 정책 및/또는 구현별 라우트 보안 필터 - Not yet supported High

등가물 없음 또는 계획 없음 (No Equivalent or Not Planned)

다음은 1:1 Gateway API 마이그레이션 대상이 없는 흔한 예시들이에요:

  • configuration-snippet, server-snippet, server-snippets (won't add)
  • sendfile (won't add)
  • proxy-store (직접 등가물 없음)
  • proxy-buffering 및 관련 프록시 버퍼 튜닝 어노테이션
  • worker-processes (N/A)

이런 경우에는 다음 중 하나를 선호해주세요:

  • 동작을 애플리케이션/런타임 구성으로 옮기세요.
  • 동작을 전용 플랫폼 정책 객체(가능하다면)로 옮기세요.
  • Gateway API + Envoy에서는 더 이상 관련이 없는 레거시 튜닝을 버리세요.

검증 (Validation)

마이그레이션한 모든 어노테이션에 대해 다음을 검증하세요:

  • Route/Gateway 조건 상태 (Accepted, Programmed, ResolvedRefs)
  • 종단 간 동작 일치성 (리다이렉트, 헤더, auth, 재시도, TLS)
  • 롤아웃 중 SLO 영향 (오류율, 지연, 재시도 증폭)

관련 콘텐츠 (Related Content)

  • Migrating from Ingress to Gateway
  • HTTP Migration Example
  • TLS Migration
  • Gateway API Support

더 알아보기 (Learn more)