[사내 위키] Kubernetes Gateway API 개요 및 가이드

1. 개요 (Overview)

Gateway API는 기존의 Ingress 리소스가 가진 한계를 극복하고, 클러스터 외부 트래픽을 내부 서비스로 라우팅하기 위해 도입된 차세대 업계 표준 오픈소스 API 프로그래밍 인터페이스입니다. 사내 인프라 및 클라우드 환경에서 안정적이고 유연한 트래픽 제어를 위해 이 가이드를 준수해 주시기 바랍니다.

2. Ingress API vs Gateway API 비교

기존 인gress 대비 Gateway API의 핵심 차이점은 다음과 같습니다.

항목	Ingress API	Gateway API
인프라 결합도	인프라 설정과 라우팅 설정이 하나의 리소스에 결합되어 복잡함.	인프라 설정(Gateway)과 트래픽 규칙(Route)이 명확히 분리됨.
지원 프로토콜	L7 (HTTP/HTTPS) 중심.	L4(TCP, UDP)부터 L7(HTTP, HTTPS, gRPC)까지 광범위하게 지원.
멀티테넌시 관리	하나의 파일에 여러 규칙이 섞여 관리 역할 분담이 어려움.	관리자(Gateway 생성)와 개발자(Route 생성)의 역할 및 권한 분리 가능.
교차 네임스페이스	단일 네임스페이스 내부 진입 위주.	단일 공용 Gateway 인프라를 여러 네임스페이스의 Route가 공유 가능.

3. 핵심 리소스 모델 (Core Resources)

Gateway API는 관리 역할에 따라 크게 3가지 계층의 리소스로 나뉩니다.

GatewayClass (인프라 제공자 영역)
- 인프라 수준의 Gateway 템플릿과 컨트롤러를 정의합니다. (예: 클라우드 로드 밸런서, Istio 등)
Gateway (클러스터 관리자 영역)
- 트래픽이 진입하는 실제 인프라 지점(포트, 프로토콜, 호스트네임 등)을 정의하는 리스너(Listener) 역할을 합니다.
Route Objects (애플리케이션 개발자 영역)
- Gateway의 리스너와 연결되어, 특정 조건에 맞는 트래픽을 어떤 실제 백엔드 서비스로 보낼지 규칙을 작성합니다.
- 서비스 프로토콜에 따라 HTTPRoute, TLSRoute, GRPCRoute, TCPRoute, UDPRoute를 선택하여 생성합니다.

4. 실전 가이드 및 배포 매니페스트 예시

① Gateway 설정 (HTTP 리스너)

사내 공용 도메인(*.example.com)의 80 포트 트래픽을 수용하는 Gateway 인프라 설정 예시입니다.

YAML

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shared-gateway
  namespace: infra-system
spec:
  gatewayClassName: istio # 사내 구축된 GatewayClass 입력
  listeners:
  - name: http-listener
    port: 80
    protocol: HTTP
    hostname: '*.example.com'

② 애플리케이션 연결 (HTTPRoute)

위에서 생성한 shared-gateway에 실제 마이크로서비스를 연결하고 트래픽을 분할(카나리 배포)하는 규칙 예시입니다.

YAML

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-service-route
  namespace: dev-team
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: shared-gateway
    namespace: infra-system # 공용 인프라 네임스페이스 지정
  hostnames:
  - app.example.com
  rules:
  - backendRefs:
    - name: app-service-stable
      port: 80
      weight: 9 # 90% 트래픽 할당
    - name: app-service-canary
      port: 80
      weight: 1 # 10% 트래픽 할당 (카나리 배포)

5. 트래픽 고급 제어 기능 (Filters)

HTTPRoute 리소스 내부에 filters 항목을 추가하여 Proxy 레벨의 강력한 제어가 가능합니다.

헤더 제어 (Request/Response Header Modifier): 요청/응답 패킷에 사내 인증 토큰이나 식별용 커스텀 헤더를 동적으로 추가, 변경, 삭제할 수 있습니다.
URL 리라이트 (URLRewrite): 클라이언트가 요청한 경로(예: /foo)를 실제 백엔드 애플리케이션 구조(예: /new/path)에 맞게 변경하여 전달합니다.
트래픽 미러링 (RequestMirror): 프로덕션 환경으로 들어오는 실제 요청 트래픽을 그대로 복사하여 개발/테스트 중인 서비스 백엔드로 전달(섀도잉)합니다. 이때 복사된 트래픽에 대한 응답은 클라이언트에 영향을 주지 않고 안전하게 폐기됩니다.

6. 보안 및 교차 네임스페이스 접근 제한 (ReferenceGrant)

개발자가 다른 네임스페이스에 있는 서비스나 보안 자원(예: TLS 인증서 Secret)을 임의로 연결하여 보안 사고가 발생하는 것을 방지하기 위해, Gateway API는 ReferenceGrant 리소스를 강제합니다.

💡 중요: 타 네임스페이스의 자원을 참조해야 하는 경우, 자원을 보유한 타 네임스페이스 관리자가 명시적으로 ReferenceGrant 허용 규칙을 배포해주어야만 라우팅 정상 바인딩(ResolvedRefs: True)이 완료됩니다.

[작성 및 수정 가이드라인] 본 문서는 사내 쿠버네티스 표준 인프라 가이드를 따릅니다. 클러스터 환경 내부 변경 사항이나 고도화 기능(예: gRPC 라우팅 활성화 등)이 생길 경우 인프라 파트에 문의 후 본 위키를 업데이트해 주세요.

마지막도전_잡창고