Kubernetes Gateway API 완전 마이그레이션 가이드 — Ingress-Nginx 은퇴 대응

핵심 요약

Gateway API는 Ingress의 후속 표준이다. 역할 분리·벤더 중립·L4/L7 통합이 핵심이다. Ingress-Nginx는 K8s 1.36에서 공식 은퇴 예정.

• GatewayClass: 구현체 지정 (인프라팀)
• Gateway: 리스너 설정 (인프라팀)
• HTTPRoute / TCPRoute: 라우팅 규칙 (개발팀)

Ingress vs Gateway API 대응표

실전 마이그레이션 3단계

Step 1. 병렬 배포

# Gateway 컨트롤러 설치 (예: envoy-gateway)
helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --namespace envoy-gateway-system --create-namespace

Step 2. HTTPRoute 작성

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
spec:
  parentRefs:
    - name: public-gateway
  hostnames: ["app.example.com"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-svc
          port: 80

Step 3. DNS 가중치 이관

AWS Route53 weighted record나 Cloudflare로 1% → 10% → 50% → 100% 점진 이관. 30일 안정 확인 후 Ingress 리소스 삭제.

자주 쓰는 어노테이션 매핑

• nginx.ingress.kubernetes.io/rewrite-target → URLRewrite filter
• cert-manager.io/cluster-issuer → Gateway tls + Certificate 리소스 유지
• ssl-redirect → HTTPS listener로 명시 리다이렉트 HTTPRoute
• rate-limit → 컨트롤러별 policy (envoy-gateway RateLimitFilter 등)

TLS 구성

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
spec:
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: app-tls

주의사항

• CRD 버전 v1 stable 확인. v1beta1 혼용 금지.
• 컨트롤러별 구현 차이 존재 (Envoy Gateway·Istio·Cilium). 선택 전 policy 지원 범위 비교 필수.
• 외부 DNS 자동화 도구(external-dns)는 v0.14+ 필요.

자주 묻는 질문

모든 Ingress 기능이 Gateway API에 있나?

핵심은 모두 지원. 세부 policy(rate limit, auth)는 구현체별 확장으로 제공되며 GEP(Gateway Enhancement Proposal)로 표준화 진행 중.

Ingress를 그대로 두면?

동작은 하지만 보안 패치 중단. 신규 CVE 대응이 안 되므로 프로덕션은 전환 필수.