Navigating the ingress-NGINX retirement

ingress-nginx 퇴역, 지금 당장 마이그레이션을 준비해야 하는 이유

Kubernetes 생태계에서 가장 널리 사용되어 온 ingress-nginx 컨트롤러가 2026년 3월을 기점으로 공식 퇴역(retirement) 상태에 진입했다. 이는 단순한 버전 업그레이드 이슈가 아니다. CVE 패치 중단, 기능 업데이트 종료, 커뮤니티 지원 공백이라는 세 가지 리스크가 동시에 발생한다는 점에서, 현재도 이 컨트롤러를 운영 중인 팀이라면 즉각적인 대응 전략이 필요하다.

여기서 흔히 발생하는 오해가 하나 있다. Kubernetes Ingress API 자체가 사라지는 것이 아니다. Ingress API 스펙은 여전히 지원되며 클러스터에서 계속 사용할 수 있다. 퇴역 대상은 SIG Network가 관리해 온 ingress-nginx 컨트롤러 구현체다. 따라서 현재 Ingress YAML을 그대로 유지하면서 컨트롤러만 교체하는 방식도 유효한 선택지다.

Path A: Contour로의 Lift-and-Shift 마이그레이션

가장 보수적인 접근법은 기존 Ingress 리소스를 유지한 채 컨트롤러만 교체하는 것이다. Envoy 기반의 Contour가 대표적인 대안으로, 기존 Ingress YAML 구조를 그대로 수용하기 때문에 라우팅 정의 변경을 최소화할 수 있다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-service
  annotations:
    kubernetes.io/ingress.class: contour  # nginx → contour로 변경
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-service
                port:
                  number: 8080

단, 이 경로에서 반드시 주의해야 할 지점이 있다. 기존에 nginx.ingress.kubernetes.io/* 형태로 설정해 둔 어노테이션들은 Contour에서 동작하지 않는다. Rate limiting, 커스텀 헤더, 타임아웃 설정 등 nginx 전용 어노테이션을 Contour의 동등한 어노테이션이나 CRD(HTTPProxy 등)로 수작업 변환해야 하므로, 어노테이션 의존도가 높은 서비스일수록 전환 공수가 예상보다 커질 수 있다.

Path B: Gateway API로의 아키텍처 현대화

이번 퇴역을 단순 교체가 아닌 아키텍처 개선의 기회로 삼는 접근법이다. Gateway API는 Kubernetes upstream이 공식적으로 Ingress의 후속으로 지정한 스펙으로, 역할 기반의 명확한 책임 분리를 핵심으로 한다.

# 인프라 팀이 관리하는 Gateway
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
spec:
  gatewayClassName: envoy
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
---
# 애플리케이션 팀이 관리하는 HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-service-route
spec:
  parentRefs:
    - name: prod-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: my-service
          port: 8080

Gateway(인프라 팀 소유)와 HTTPRoute(애플리케이션 팀 소유)를 분리함으로써, 기존 Ingress가 가졌던 단일 리소스에 모든 관심사가 혼재하는 구조적 한계를 해소한다. 특히 멀티팀 환경이나 플랫폼 엔지니어링 조직에서 권한 경계를 명확히 하는 데 실질적인 이점이 있다.

정리

ingress-nginx 컨트롤러는 2026년 3월부로 퇴역 상태이며, CVE 패치 및 지원이 완전 중단되므로 즉각적인 마이그레이션 계획 수립이 필요하다.
Contour 전환(Path A)은 Ingress YAML 재사용이 가능하지만, nginx 전용 어노테이션의 수동 마이그레이션이 필수적으로 수반된다.
Gateway API(Path B)는 인프라와 애플리케이션 라우팅의 역할을 명확히 분리하는 구조로, 장기적 운영 복잡도를 낮추는 방향의 선택이다.