TIL

Gateway API

공식 문서 - Gateway API
HTTP/HTTPS 트래픽 라우팅을 위한 역할 분리 기반의 차세대 네트워킹 API
Ingress의 표현력 한계와 어노테이션 남용 문제를 해결하기 위해 설계 — Ingress의 공식 후속
CRD(Custom Resource Definition) 형태로 제공되는 애드온 — 설치 후 사용 가능
GKE를 포함한 주요 클라우드·컨트롤러가 구현체를 제공

Ingress와의 차이

Ingress의 한계
- 역할 구분 없이 하나의 리소스에 인프라·라우팅 설정이 혼합
- header 기반 매칭·트래픽 가중치 같은 고급 라우팅은 표준 스펙에 없어 컨트롤러별 어노테이션에 의존
- 어노테이션이 달라지면 컨트롤러 교체 시 이식성이 없음
Gateway API가 해결하는 것
- 역할별로 리소스를 분리 — 각 팀이 자기 책임 범위만 관리
- 표준 스펙으로 고급 라우팅 표현 가능 — 어노테이션 없이도 header 매칭·가중치·gRPC 라우팅
- 여러 구현체에서 같은 리소스 정의를 사용 — 이식성

설계 원칙

Role-oriented (역할 지향)
- 리소스 모델이 조직 내 역할을 반영해 계층적으로 분리됨
- 세 역할
  - Infrastructure Provider — 여러 클러스터를 운영하는 클라우드·인프라 팀. GatewayClass를 정의
  - Cluster Operator — 클러스터를 관리하는 플랫폼 팀. Gateway를 정의, 정책·네트워크 접근 제어 담당
  - Application Developer — 서비스를 배포하는 개발팀. HTTPRoute / GRPCRoute를 정의
Portable (이식성)
- CRD로 정의된 표준 스펙 — 여러 구현체가 같은 리소스를 그대로 해석
- 컨트롤러를 바꿔도 Route 정의를 수정할 필요가 없음
Expressive (표현력)
- header 기반 매칭, 트래픽 가중치(weighted routing), path 재작성 등을 표준 필드로 표현
- Ingress에서 어노테이션으로만 가능했던 것이 스펙 안으로 들어옴
Extensible (확장성)
- API 각 계층에 커스텀 리소스를 연결 가능 — 구현체별 확장을 표준 구조 안에서 수용

리소스 모델

4개의 핵심 리소스가 역할 계층에 맞춰 협력
- GatewayClass — 어떤 컨트롤러가 처리할지 (Infrastructure Provider 영역)
- Gateway — 어떤 포트·프로토콜로 트래픽을 받을지 (Cluster Operator 영역)
- HTTPRoute — HTTP 요청을 어떤 Service로 보낼지 (Application Developer 영역)
- GRPCRoute — gRPC 요청 라우팅 (Application Developer 영역)
계층 관계 — GatewayClass ← Gateway ← HTTPRoute / GRPCRoute
- HTTPRoute가 Gateway를 parentRefs로 참조, Gateway가 GatewayClass를 gatewayClassName으로 참조

GatewayClass

특정 컨트롤러 구현체를 식별하는 클러스터 스코프 리소스 — Ingress의 IngressClass에 대응

Infrastructure Provider(클라우드·인프라팀)가 만들고 관리

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-class
spec:
  controllerName: example.com/gateway-controller   # 이 클래스를 처리할 컨트롤러 식별자

spec.controllerName을 watch하고 있는 컨트롤러가 이 클래스의 Gateway를 처리
GKE에서는 Google이 제공하는 GatewayClass(gke-l7-global-external-managed 등)가 미리 등록됨

Gateway

트래픽을 받아들이는 인프라 인스턴스 — 어떤 포트·프로토콜·호스트로 외부 트래픽을 수신할지 정의

Cluster Operator가 만들고 관리 — 네트워크 진입점을 플랫폼 팀이 중앙에서 제어

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: example-namespace
spec:
  gatewayClassName: example-class       # 어느 GatewayClass(컨트롤러)를 사용할지
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: "www.example.com"
      allowedRoutes:
        namespaces:
          from: Same                    # 기본: 같은 네임스페이스의 Route만 허용

spec.listeners — 수신 포트·프로토콜·호스트 조합. 여러 개 정의 가능 (HTTP 80, HTTPS 443 등)
allowedRoutes — 어느 네임스페이스의 Route가 이 Gateway에 붙을 수 있는지 제어
- from: Same (기본) — 같은 네임스페이스만
- from: All — 모든 네임스페이스
- from: Selector — 라벨로 선택한 네임스페이스
addresses를 지정하지 않으면 컨트롤러가 IP·호스트명을 자동 할당

HTTPRoute

HTTP 요청을 어떤 Service로 보낼지 정의하는 라우팅 규칙

Application Developer가 만들고 관리 — 개발팀이 자기 서비스의 라우팅만 직접 선언

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-httproute
spec:
  parentRefs:
    - name: example-gateway             # 어느 Gateway에 붙을지
  hostnames:
    - "www.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /login
      backendRefs:
        - name: example-svc
          port: 8080

parentRefs — 이 Route가 연결될 Gateway (네임스페이스 간 참조도 가능)
hostnames — 매칭할 호스트 이름 목록
rules — 매칭 조건(matches)과 백엔드(backendRefs)의 쌍. 여러 rule 정의 가능
matches에서 path 외에도 header·method·query parameter 매칭을 표준 스펙으로 지원
backendRefs에서 가중치(weight)로 트래픽 분배 비율을 지정 가능 — 카나리 배포에 활용

GRPCRoute

gRPC 요청의 라우팅 규칙 — HTTPRoute와 구조가 유사하지만 gRPC 서비스·메서드 매칭 지원
Gateway가 HTTP/2를 기본으로 처리해야 함 — HTTP/1 업그레이드 없이 gRPC 트래픽 보장

서비스 이름만으로 라우팅

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: example-grpcroute
spec:
  parentRefs:
    - name: example-gateway
  hostnames:
    - "svc.example.com"
  rules:
    - backendRefs:
        - name: example-svc
          port: 50051

특정 gRPC 메서드로 라우팅 ```yaml rules:
- matches:
  - method: service: com.example # gRPC 패키지·서비스 method: Login # 특정 메서드만 매칭 backendRefs:
  - name: foo-svc port: 50051 ```
service와 method 둘 다 지정하면 특정 메서드로, service만 지정하면 그 패키지의 모든 메서드로 라우팅

HTTPRoute 심화

기본 path 매칭만으로 부족한 라우팅 — 헤더·메서드별 분기, 응답 변형, 카나리 배포 등을 표준 필드로 표현
모두 HTTPRoute.spec.rules 안에서 matches / filters / backendRefs.weight로 처리

매칭 규칙 (matches)

한 rule 안의 matches는 OR — 여러 match 중 하나라도 맞으면 rule 적용
한 match 안의 필드는 AND — path / headers / queryParams / method 모두 만족해야 함
path 외 매칭 가능 필드
- headers — 특정 헤더 값으로 분기 (Exact / RegularExpression)
- queryParams — query 파라미터 값으로 분기
- method — GET / POST 등 HTTP 메서드 ```yaml matches:
  - path: type: PathPrefix value: /api headers:
    - name: x-canary value: “true” # 헤더가 true일 때만 이 rule 적용 method: GET ```
매칭 우선순위는 스펙으로 정의 — Exact가 PathPrefix보다, path 길이가 길수록, 매칭 조건(header·query) 수가 많을수록 우선

필터 (filters)

요청·응답을 변형하는 단계 — 매칭 후 백엔드 전달 전(또는 응답 시) 적용
한 rule에 여러 필터 가능, 정의 순서대로 실행

필터	역할
`RequestHeaderModifier`	요청 헤더 set / add / remove
`ResponseHeaderModifier`	응답 헤더 set / add / remove
`RequestRedirect`	HTTP 리다이렉트 응답 (백엔드 호출 안 함)
`URLRewrite`	path · hostname 재작성 후 백엔드 전달
`RequestMirror`	동일 요청을 다른 백엔드에 복제 (응답은 무시)

모두 같은 위치(rules.filters)에 type 필드로 구분해서 정의 ```yaml filters:
- type: RequestHeaderModifier # 요청 헤더 추가·제거 requestHeaderModifier: set: - name: x-source value: gateway remove: - cookie
- type: URLRewrite # 백엔드로 보낼 path 변경 urlRewrite: path: type: ReplacePrefixMatch replacePrefixMatch: / # /api/foo → /foo
- type: RequestMirror # 운영 트래픽 그림자 복제 requestMirror: backendRef: name: example-svc-canary port: 8080 ```
RequestRedirect — 백엔드 호출 없이 즉시 3xx 응답. http→https 강제, 도메인 변경 시 활용
RequestMirror — 미러 응답은 클라이언트에 돌아가지 않음 → 트래픽 영향 없이 신버전 검증 가능

Traffic Splitting

한 rule의 backendRefs에 여러 Service를 두고 weight로 트래픽 비율 분배
카나리·블루그린 배포 — weight 값을 점진적으로 조정해 신버전 비중 확대 ```yaml rules:
- backendRefs:
  - name: example-svc-v1 port: 8080 weight: 90 # 기존 버전 90%
  - name: example-svc-v2 port: 8080 weight: 10 # 신버전 10% ```
weight는 정수, 합이 100일 필요 없음 — 전체 합 대비 비율로 환산 (예: 90:10 = 9:1)
weight: 0이면 해당 백엔드로 보내지 않음 — 트래픽 차단용
한계
- 무작위 분배 — 동일 사용자가 요청마다 다른 버전에 갈 수 있음 (sticky 보장 X)
- sticky가 필요하면 별도 matches(예: header x-user-bucket)로 사용자별 분리 필요

Request Flow

HTTP 요청이 Gateway·HTTPRoute를 통해 Service에 도달하기까지의 흐름
컨트롤러가 Gateway를 reverse proxy로 구현했다고 가정한 표준 시나리오
단계
1. 클라이언트가 요청 준비 — 예: http://www.example.com로 HTTP 요청을 만들 준비
2. DNS 조회 — 클라이언트의 DNS 리졸버가 도메인을 Gateway에 할당된 IP 주소들로 매핑
3. Gateway 수신 — 클라이언트가 Gateway IP로 패킷을 보내면, reverse proxy(Gateway 구현체)가 받아 Host 헤더로 매칭되는 Gateway·HTTPRoute 설정을 찾음
4. HTTPRoute 매칭 — HTTPRoute의 matches 규칙(path, header, method 등)으로 어느 rule을 적용할지 결정
5. Filter 적용 (선택) — HTTPRoute의 filter 규칙에 따라 헤더 추가·삭제, path 재작성 등 요청 변형
6. 백엔드 전달 — 매칭된 backendRefs의 Service(또는 EndpointSlice) Pod로 요청 forward
핵심 포인트
- DNS는 Gateway IP를 가리킴, 개별 Service IP가 아님 — 클라이언트는 단일 진입점만 알면 됨
- 매칭·필터·라우팅은 모두 Gateway 구현체(컨트롤러가 프로그래밍한 LB·프록시) 가 처리
- parentRefs로 묶인 HTTPRoute가 여러 개여도 Gateway가 한곳에서 일괄 처리
Ingress와의 차이
- Ingress에선 컨트롤러가 알아서 LB 구성을 만들고 라우팅 — 단일 리소스에 모든 게 들어 있음
- Gateway API는 Gateway(인프라 정의)와 Route(라우팅 규칙)가 분리되어 있어 요청 흐름의 책임 경계가 명확

Conformance

Gateway API는 기능 범위가 넓고 구현체가 다양해서 준수 수준(conformance) 을 명시적으로 정의
같은 리소스를 만들어도 컨트롤러마다 지원하는 기능이 달라질 수 있기 때문
Gateway API SIG가 제공하는 것
- Release Channel — 기능의 안정성에 따라 Standard(GA·정식)와 Experimental(실험) 채널로 분리
- Support Level — 각 필드·기능마다 Core(필수), Extended(선택 지원), Implementation-specific(구현체 자유)로 분류
- Conformance Test Suite — 구현체가 자기 준수 수준을 검증할 수 있는 표준 테스트
컨트롤러를 선택할 때 — 그 컨트롤러가 어느 채널을 지원하고, 필요한 기능이 Core/Extended 중 어디에 있는지 확인
구현체별 conformance report는 Gateway API 사이트(gateway-api.sigs.k8s.io)에 공개됨

Migrating from Ingress

Gateway API는 Ingress의 공식 후속 — 그러나 Gateway API에는 Ingress kind가 포함되지 않음
즉 자동으로 Ingress가 Gateway로 변환되지 않으며, 기존 Ingress 리소스를 직접 Gateway API 리소스로 재작성해야 함
일회성 마이그레이션이 필요한 이유
- 두 API가 다른 CRD·apiVersion을 사용
- 어노테이션 기반 설정을 표준 스펙(filter·match)으로 옮겨야 함
- 컨트롤러도 Gateway API를 지원하는 구현체로 교체 필요
매핑 가이드
- Ingress.spec.rules.host → HTTPRoute.spec.hostnames
- Ingress.spec.rules.http.paths.path → HTTPRoute.spec.rules.matches.path
- Ingress.spec.tls → Gateway.spec.listeners 의 TLS 설정으로 이동 (인증서는 Gateway에서 종료)
- 어노테이션으로 처리하던 header 매칭·재작성·가중치 → HTTPRoute 표준 필드로 이동
자동 변환 도구 — ingress2gateway (Gateway API SIG가 제공) 사용 시 기존 Ingress 리소스를 HTTPRoute·Gateway YAML로 변환 가능
마이그레이션 전략
- 기존 Ingress를 일단 그대로 두고 Gateway API 리소스를 병행 배포 — 같은 도메인을 새 Gateway로 점진적으로 옮김
- DNS·LB 단에서 트래픽 비중을 조절하며 단계적으로 전환
- 모든 트래픽이 Gateway로 옮겨지면 기존 Ingress·Ingress Controller를 제거