Kubernetes Gateway API — Ingress 종언, 단계별 마이그레이션 가이드

핵심 요약

Kubernetes Gateway API가 GA(v1.0)된 지 1년 반, 2026년 들어 Ingress는 사실상 maintenance 모드다. 새 클러스터는 Gateway API로 시작하고, 기존은 점진 마이그레이션이 표준. 실제 옮긴 경험을 단계별로 정리한다.

1. Ingress의 한계

• 표현력 부족: HTTP 헤더·메서드 기반 라우팅이 annotation으로만 가능 (벤더별 다름)
• 역할 혼재: 클러스터 운영자·앱 개발자 권한 분리가 어려움
• L4 미지원: TCP·UDP는 다른 리소스 필요
• 벤더 종속: nginx·traefik·istio annotation 다 다름

2. Gateway API 핵심 리소스 3종

3. 최소 예시

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
spec:
  gatewayClassName: envoy
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      certificateRefs:
      - name: prod-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
spec:
  parentRefs: [{ name: prod-gateway }]
  hostnames: ['api.example.com']
  rules:
  - matches:
    - path: { type: PathPrefix, value: /v2 }
    backendRefs:
    - name: api-v2-svc
      port: 8080
      weight: 90
    - name: api-v2-canary
      port: 8080
      weight: 10

한 리소스에서 카나리 분할이 표준 문법. annotation 헷갈림 없음.

4. 헤더 기반 라우팅 (Ingress에서 가장 까다롭던 것)

rules:
- matches:
  - headers:
    - { name: 'x-version', value: 'beta' }
  backendRefs: [{ name: api-beta, port: 8080 }]
- matches:
  - {}  # default
  backendRefs: [{ name: api-stable, port: 8080 }]

5. 구현체 선택

서비스 메시 안 쓸 거면 Envoy Gateway가 무난. 메시 쓰면 Istio가 자연스러움.

6. 단계별 마이그레이션 — 실제 진행한 4단계

1단계: 새 Gateway 병렬 설치 (2주)

기존 Ingress는 그대로 두고 새 Gateway에 다른 도메인(예: v2-api.example.com)으로 동일 서비스 라우팅. DNS 분리로 카나리.

2단계: 트래픽 5% 이동 (1주)

외부 LB·CDN에서 트래픽 일부를 새 Gateway로. 메트릭(에러·지연) 동등성 확인.

3단계: 50% → 100% 점진 (2주)

매일 +10%씩. 회귀 발견 시 즉시 롤백 가능한 라우팅 비율로.

4단계: Ingress 리소스 제거 (1주)

모니터링 1주 유지 후 Ingress·관련 annotation·컨트롤러 제거.

7. 실측 — 50개 마이크로서비스 클러스터

8. 권한 분리 — 진짜 이득

Ingress에선 앱 팀이 annotation으로 클러스터 전역 동작을 바꿀 수 있었다. Gateway API는 RBAC가 명확:

• 플랫폼 팀: GatewayClass, Gateway 관리
• 앱 팀: HTTPRoute만 작성 (자기 네임스페이스)
• 인증서·TLS 정책은 플랫폼 팀이 한 곳에서 통제

9. 흔한 함정

• cert-manager 통합: Gateway API 어노테이션이 v0.15+에서 변경. 버전 확인.
• ExternalName 서비스: 모든 구현체 지원 안 함. Envoy는 GA, Istio는 베타.
• RequestRedirect 필수 vs 선택: 컨포먼스 테스트로 확인. 일부 구현체에서 동작 다름.
• backendRef across namespaces: ReferenceGrant 필수. 빠뜨리면 라우팅 안 됨.

참고

• gateway-api.sigs.k8s.io — conformance results
• envoyproxy.github.io/gateway/v1.0