Kubernetes Gateway API는 클러스터의 L4·L7 트래픽 경로를 표현하는 Kubernetes API 집합이다. 플랫폼 운영자가 공용 진입점을 관리하고 애플리케이션 담당자가 자신의 라우팅을 선언하도록 역할을 나누는 데 초점을 둔다. 공식 소개에서 Ingress·로드밸런싱·서비스 메시를 아우르는 모델을 설명한다.
API와 구현체의 차이
GatewayClass는 어떤 컨트롤러 구현을 사용할지, Gateway는 리스너와 진입점의 의도를, HTTPRoute 같은 Route는 요청을 어디로 보낼지 표현한다. 이 API의 CRD만 설치해서는 실제 프록시나 로드밸런서가 생기지 않는다. 자원을 해석하고 데이터 플레인을 구성하는 호환 컨트롤러가 필요하다.
Route는 부모 Gateway와 연결되고 호스트·경로·헤더 조건 및 백엔드를 정의할 수 있다. 운영자는 어떤 네임스페이스의 Route를 허용할지 제한할 수 있다. 서로 다른 네임스페이스의 자원 참조는 추가 허용 조건을 요구할 수 있으므로 이름만 맞추면 모두 연결된다고 가정하지 않는다. HTTP 라우팅 안내가 구체적인 매칭 모델을 다룬다.
장점과 한계
역할 분리와 표준 자원 구조 덕분에 공유 진입점에서 여러 팀의 경로를 관리하기 좋다. 구현체별 전용 설정을 줄이고 경로·가중치 같은 의도를 API로 검토할 수 있다. 다만 모든 컨트롤러가 모든 확장 기능을 동일하게 지원하는 것은 아니므로 적합성·지원 기능과 API 버전을 확인해야 한다.
API를 도입해도 DNS, 외부 주소, TLS 인증서, 백엔드 준비 상태가 자동으로 해결되지는 않는다. 규칙이 겹치거나 Route 연결이 거부된 경우 상태 조건을 읽어야 한다. YAML 저장 성공과 실제 요청 경로의 준비 완료는 서로 다른 단계다.
도서 검색 경로 예시
library-lab 네임스페이스에 web-gateway라는 정상 Gateway와 catalog:8080 Service가 준비되어 있다고 가정한다. 아래는 가상 도메인의 /catalog 요청을 연결하는 HTTPRoute 예시다. DNS와 Gateway 리스너의 호스트 허용은 별도 조건이다.
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: catalog-route
namespace: library-lab
spec:
parentRefs:
- name: web-gateway
hostnames:
- books.example.test
rules:
- matches:
- path:
type: PathPrefix
value: /catalog
backendRefs:
- name: catalog
port: 8080이 예시에는 경로 재작성 필터가 없으므로 백엔드는 /catalog 접두사가 포함된 경로를 받는다고 설계해야 한다. Route의 부모 상태에서 Accepted와 참조 해결 조건을 확인하고, Gateway의 준비 상태와 실제 응답을 따로 확인한다. 요청 Host가 다르면 이 규칙과 일치하지 않을 수 있다.
자주 생기는 오해
Gateway API라는 이름을 특정 API 게이트웨이 제품과 동일시하거나 CRD만으로 트래픽 처리가 시작된다고 생각하기 쉽다. 문제를 조사할 때는 API 정의, 컨트롤러, 실제 프록시, 외부 DNS를 분리하고 어디까지 준비되었는지 확인한다.