팀에서 운영하던 쿠버네티스 클러스터의 Ingress NGINX 설정 파일을 열어봤다. 어노테이션이 47줄이었다. 리다이렉트, CORS, 렄이트 리밋, SSL 인증서 관리까지 전부 어노테이션에 우겨넣은 결과였다. 그 순간 깨달았다. 이건 설정이 아니라 고고학 유물이다.
2026년 3월, Kubernetes Ingress NGINX Controller의 공식 EOL이 시작되었다. 인터넷에 연결된 쿠버네티스 클러스터의 약 41~50%가 이 컨트롤러를 사용하고 있다는 점을 고려하면, 이건 조용한 변화가 아니다.
Ingress의 근본적인 문제
Ingress는 쿠버네티스 초창기에 만들어진 리소스다. 당시에는 "외부 트래픽을 클러스터 안의 서비스로 라우팅한다"는 단순한 요구사항이면 충분했다. 하지만 현실의 요구는 훨씬 복잡해졌고, Ingress 스펙은 이를 따라가지 못했다.
# Before: Ingress + 어노테이션 지옥
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-app
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
nginx.ingress.kubernetes.io/cors-allow-origin: "*"
nginx.ingress.kubernetes.io/rate-limit: "10"
# ... 40줄 더
spec:
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: my-app
port:
number: 80어노테이션은 벤더마다 다르고, 타입 검사가 없고, IDE 자동완성도 안 되고, 실수를 해도 apply할 때까지 알 수 없다.
Gateway API가 다른 점
Gateway API는 Ingress의 후계자로 설계되었다. 가장 큰 차이는 역할 기반 분리다.
# After: Gateway API - 타입 안전한 리소스 분리
# 1. 인프라 팀이 관리하는 Gateway
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: main-gateway
spec:
gatewayClassName: nginx
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
certificateRefs:
- name: wildcard-cert
---
# 2. 개발 팀이 관리하는 HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-app-route
spec:
parentRefs:
- name: main-gateway
hostnames:
- "api.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: my-app
port: 80인프라 팀은 Gateway를 관리하고, 개발 팀은 HTTPRoute를 관리한다. 각자의 책임 범위가 명확하고, YAML 스키마에 의해 타입 검사가 이루어진다.
마이그레이션 실전 원칙 4가지
원칙 1: 점진적으로 전환하라. Ingress와 Gateway API는 공조할 수 있다. 새로운 서비스부터 Gateway API로 시작하고, 기존 서비스는 안정적으로 전환하라.
원칙 2: GatewayClass 선택을 신중히 하라. Envoy 기반(Contour, Istio), Nginx 기반(nginx-gateway-fabric) 등 구현체마다 지원하는 기능이 다르다. 팀의 요구사항에 맞는 구현체를 선택하라.
원칙 3: 어노테이션 의존성을 먼저 정리하라. 기존 Ingress의 어노테이션 중 Gateway API의 네이티브 기능으로 돀체 가능한 것과, 커스텀 Policy로 처리해야 하는 것을 구분하라.
원칙 4: 모니터링을 강화하라. 전환 과정에서 트래픽 라우팅이 의도대로 동작하는지 확인할 수 있는 관측 가능성을 확보해야 한다. 카나리 배포를 활용해 점진적으로 트래픽을 이전하라.
변화는 이미 시작되었다
Gateway API는 단순한 대체재가 아니다. 쿠버네티스 커뮤니티가 10년간 쌓아온 경험과 교훈이 녹아있는 새로운 표준이다. EOL 일정이 확정된 지금, 마이그레이션은 선택이 아니라 시간의 문제다. 어노테이션의 늪에서 벗어나 타입 안전한 API로 전환할 때, 클러스터 운영의 복잡성은 눈에 띄게 줄어들 것이다.
댓글