Kubernetes Gateway API 정리 - Ingress를 대체하는 차세대 표준

쿠버네티스에서 Ingress를 대체할 표준으로 자리잡고 있는 Gateway API의 개념, Ingress와의 차이점, 핵심 리소스, 실제 적용 예시, 그리고 동작 원리를 정리합니다.

Gateway API란?

Gateway API는 쿠버네티스 SIG-Network가 주도해 만든 차세대 트래픽 라우팅 표준으로, 기존 Ingress 리소스가 가진 한계(벤더별 annotation 남용, 역할 분리 불가, L4/L7 라우팅 표현력 부족)를 해결하기 위해 설계되었습니다. Kubernetes 1.29부터 CRD 기반으로 GA(정식 릴리스)되었으며, NGINX, Istio, Cilium, AWS Load Balancer Controller, Contour, Envoy Gateway 등 주요 벤더들이 대부분 구현체를 제공하고 있습니다.

Gateway API는 어떻게 동작할까?

Gateway API는 역할 분리(role-oriented) 모델과 쿠버네티스의 표준 컨트롤러 패턴(선언 → watch → reconcile)을 결합해서 동작합니다. 리소스 계층 구조부터 실제 요청이 처리되는 과정까지 순서대로 정리합니다.

GatewayClass  (클러스터 전역, 인프라 관리자)
     ↓ 참조
   Gateway     (네임스페이스, 인프라 관리자 - 실제 리스너/LB)
     ↓ 참조 (parentRefs)
  HTTPRoute    (네임스페이스, 개발팀 - 라우팅 규칙)
     ↓ 참조 (backendRefs)
   Service

각 리소스는 독립적으로 생성되고 서로를 참조하는 방식으로 연결됩니다. Ingress처럼 하나의 리소스에 모든 설정을 담는 대신, "누가 무엇을 관리하는지"에 따라 리소스가 나뉘어 있는 것이 핵심입니다.

실제 동작 순서

단계	내용
1. 컨트롤러 설치	Nginx Gateway Fabric, Istio, Envoy Gateway 등 구현체를 클러스터에 배포하면 해당 컨트롤러가 GatewayClass를 watch 시작
2. GatewayClass 생성	controllerName으로 어떤 컨트롤러가 처리할지 지정. 컨트롤러는 자기 이름과 일치하는 GatewayClass만 처리
3. Gateway 생성	gatewayClassName을 참조하는 Gateway를 만들면 컨트롤러가 감지해 실제 인프라(클라우드 LB 등)를 프로비저닝
4. HTTPRoute 생성	개발팀이 parentRefs로 Gateway를 가리키는 HTTPRoute를 자기 네임스페이스에 생성. Gateway의 allowedRoutes가 허용해야 연결됨(양방향 동의)
5. 컨트롤러 reconcile	Gateway와 연결된 모든 HTTPRoute를 조합해 실제 프록시(Envoy, Nginx 등) 설정을 생성/적용
6. 요청 처리	클라이언트 요청이 프로비저닝된 LB/프록시로 들어오면 HTTPRoute 규칙(hostname, path, header 등)에 따라 매칭되는 Service로 전달

• 참고: Gateway의 allowedRoutes.namespaces가 허용하지 않으면 다른 네임스페이스의 HTTPRoute는 무시됩니다(양방향 동의, cross-namespace binding). Ingress에는 이런 네임스페이스 간 격리 장치가 없었습니다.
• 참고: 각 리소스(Gateway, HTTPRoute)는 status.conditions에 컨트롤러의 처리 결과(Accepted, ResolvedRefs, Programmed 등)를 기록하므로, kubectl get httproute -o yaml로 실제 반영 여부를 바로 확인할 수 있습니다.
• 참고: GatewayClass마다 다른 컨트롤러를 연결할 수 있어, 같은 클러스터 안에 Nginx Gateway와 Istio Gateway가 동시에 공존하는 구성도 가능합니다.

요약하면 "리소스 선언 → 컨트롤러가 watch/reconcile → 실제 프록시 설정에 반영 → 요청이 그 프록시를 거쳐 라우팅"이라는 표준 쿠버네티스 컨트롤러 패턴을 그대로 따르되, 인프라 팀과 애플리케이션 팀의 책임을 리소스 단위로 명확히 나눈 것이 Gateway API의 핵심입니다.

Ingress vs Gateway API

구분	Ingress	Gateway API
리소스 구조	단일 Ingress 리소스	GatewayClass / Gateway / HTTPRoute 등으로 역할 분리
역할(Persona) 분리	불가능 (전부 한 리소스에서 관리)	인프라 관리자(Gateway) / 개발팀(HTTPRoute) 역할 분리 가능
프로토콜 지원	사실상 HTTP/HTTPS 중심	HTTPRoute, TCPRoute, TLSRoute, GRPCRoute 등 다양
고급 라우팅	벤더별 annotation에 의존	표준 스펙으로 트래픽 분할, 헤더 기반 라우팅 등 지원
상태(Status)	제한적	각 리소스마다 상세한 Conditions 상태 제공

핵심 리소스 3가지

• GatewayClass: 어떤 컨트롤러(Nginx, Istio, Envoy 등)가 Gateway를 처리할지 정의하는 클러스터 단위 리소스 (인프라 관리자가 생성)
• Gateway: 실제 리스너(포트, 프로토콜, TLS 등)를 정의하고 로드밸런서를 프로비저닝하는 리소스 (인프라 관리자가 생성)
• HTTPRoute: 특정 Gateway에 연결되어 실제 트래픽을 어떤 Service로 보낼지 정의하는 리소스 (개발팀/네임스페이스 단위로 생성 가능)

기본 사용 예시

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: infra
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-route
  namespace: myapp
spec:
  parentRefs:
  - name: my-gateway
    namespace: infra
  hostnames:
  - "myapp.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: my-app-svc
      port: 80

카나리 배포(트래픽 분할) 예시

HTTPRoute의 backendRefs에 weight를 지정하면 Ingress에서 annotation으로 처리하던 카나리 배포를 표준 스펙만으로 구현할 수 있습니다.

  rules:
  - backendRefs:
    - name: my-app-v1
      port: 80
      weight: 90
    - name: my-app-v2
      port: 80
      weight: 10

• 참고: Gateway API는 Ingress를 완전히 대체하는 것을 목표로 하지만, 기존 Ingress 리소스도 당분간 계속 지원되므로 점진적으로 마이그레이션하는 것이 일반적입니다.
• 참고: OpenShift 4.16+ 에서도 OpenShift Service Mesh(Istio) 및 일부 라우터 구현체를 통해 Gateway API를 기술 프리뷰~GA 단계로 지원하기 시작했습니다.
• 주의: GatewayClass/Gateway는 클러스터/인프라 관리자가, HTTPRoute는 애플리케이션 개발팀이 각자의 네임스페이스에서 관리하는 역할 분리 모델이 전제이므로, 팀 구조에 맞는 RBAC 설계가 함께 필요합니다.
• 참고: 공식 문서 - gateway-api.sigs.k8s.io