Before You Migrate: Five Surprising Ingress-NGINX Behaviors You Need to Know

Context

Kubernetes는 2026년 3월에 Ingress-NGINX를 은퇴할 예정이며, 광범위한 사용에도 불구하고 Ingress-NGINX는 예상 밖의 기본 동작과 부수 효과들을 포함하고 있다. 개발자들이 이러한 동작을 인식하지 못한 채 Gateway API로 단순 변환하면 운영 중단이 발생할 수 있다.

Technical Solution

• 정규식 매칭의 접두사 기반·대소문자 무시 동작 이해: Ingress-NGINX의 /[A-Z]{3} 패턴은 /uuid 요청과 매칭되지만, Gateway API의 RegularExpression은 대소문자 구분 전체 매칭을 수행하므로 /[a-zA-Z]{3}.* 또는 (?i)/[a-z]{3}.* 패턴으로 변환 필요
• use-regex 어노테이션의 호스트 전역 적용 범위 인식: 단일 호스트의 모든 경로에 적용되는 특성으로 인해 Exact 경로 의도가 정규식으로 해석될 수 있으므로, Gateway API에서는 각 HTTPRoute 규칙을 명시적으로 정의
• 경로 정규화 동작의 유지: Ingress-NGINX는 //, /., /.. 등을 정규화하지만, Gateway API 구현체(Istio, Envoy Gateway, Kgateway)는 기본적으로 .과 .. 세그먼트를 정규화하므로 백엔드의 경로 정규화 의존성 확인
• Ingress2Gateway 도구 활용: Kubernetes SIG Network가 Ingress-NGINX 어노테이션을 Gateway API로 변환하는 자동화 도구 제공으로 설정 변환 검증
• Gateway API 1.5 기능 활용: ListenerSet을 통한 TLS 인증서 관리 개선 및 HTTPRoute CORS 필터를 통한 CORS 설정 가능

Key Takeaway

Ingress-NGINX에서 Gateway API로 마이그레이션할 때 표면적으로 올바른 설정 변환도 Ingress-NGINX의 암묵적 동작(정규식 대소문자 무시, 경로 정규화 등)을 고려하지 않으면 운영 중단을 초래하므로, 각 구현체의 의미론적 차이를 명시적으로 검증하고 동작을 보존해야 한다.