게이트웨이 API

게이트웨이 API (Gateway API)

Gateway API는 동적 인프라 프로비저닝과 고급 트래픽 라우팅을 제공하는 API 종류의 패밀리예요.

확장 가능하고, 역할 지향적이며, 프로토콜을 인지하는 구성 메커니즘을 사용해 네트워크 서비스를 사용할 수 있게 해요. Gateway API는 동적 인프라 프로비저닝과 고급 트래픽 라우팅을 제공하는 API 종류를 포함하는 애드온(add-on)이에요.

설계 원칙

다음 원칙들이 Gateway API의 설계와 아키텍처를 형성했어요.

역할 지향(Role-oriented): Gateway API 종류는 Kubernetes 서비스 네트워킹을 관리하는 조직 역할에 따라 모델링됐어요.

  • 인프라 제공자(Infrastructure Provider): 여러 격리된 클러스터가 여러 테넌트를 서비스할 수 있게 하는 인프라를 관리해요. 예를 들어 클라우드 제공자가 있죠.
  • 클러스터 운영자(Cluster Operator): 클러스터를 관리하며, 주로 정책, 네트워크 접근, 애플리케이션 권한 등에 관심이 있어요.
  • 애플리케이션 개발자(Application Developer): 클러스터에서 실행되는 애플리케이션을 관리하며, 주로 애플리케이션 수준 구성과 Service 구성에 관심이 있어요.

이식 가능(Portable): Gateway API 스펙은 커스텀 리소스로 정의되며 많은 구현에서 지원돼요.

표현력(Expressive): Gateway API 종류는 헤더 기반 매칭, 트래픽 가중치, 그리고 커스텀 어노테이션을 사용해야만 Ingress에서 가능했던 것 같은 일반적인 트래픽 라우팅 사용 사례의 기능을 지원해요.

확장 가능(Extensible): Gateway는 API의 다양한 계층에서 커스텀 리소스가 연결될 수 있게 해요. 이를 통해 API 구조의 적절한 위치에서 세밀한 커스터마이징이 가능해져요.

리소스 모델

Gateway API에는 네 가지 안정적인 API 종류가 있어요.

  • GatewayClass: 공통 구성을 가진 게이트웨이 집합을 정의하며, 그 클래스를 구현하는 컨트롤러가 관리해요.
  • Gateway: 클라우드 로드 밸런서 같은 트래픽 처리 인프라의 인스턴스를 정의해요.
  • HTTPRoute: Gateway 리스너에서 백엔드 네트워크 엔드포인트 표현으로 트래픽을 매핑하는 HTTP 관련 규칙을 정의해요. 이 엔드포인트는 종종 Service로 표현돼요.
  • GRPCRoute: Gateway 리스너에서 백엔드 네트워크 엔드포인트 표현으로 트래픽을 매핑하는 gRPC 관련 규칙을 정의해요. 이 엔드포인트는 종종 Service로 표현돼요.

Gateway API는 조직의 역할 지향적 특성을 지원하기 위해 상호 의존적인 관계를 가진 다양한 API 종류로 구성돼요. Gateway 객체는 정확히 하나의 GatewayClass와 연결되며, GatewayClass는 이 클래스의 Gateway를 관리할 게이트웨이 컨트롤러를 설명해요. 그런 다음 HTTPRoute 같은 하나 이상의 라우트 종류가 Gateway에 연결돼요. Gateway는 listeners에 연결될 수 있는 라우트를 필터링할 수 있어서, 라우트와 양방향 신뢰 모델을 형성해요.

다음 그림은 세 가지 안정적인 Gateway API 종류의 관계를 보여줘요.

GatewayClass

Gateway는 종종 다른 구성을 가진 다른 컨트롤러에 의해 구현될 수 있어요. Gateway는 그 클래스를 구현하는 컨트롤러의 이름을 포함하는 GatewayClass를 참조해야 해요.

최소한의 GatewayClass 예시:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-class
spec:
  controllerName: example.com/gateway-controller

이 예시에서 Gateway API를 구현한 컨트롤러가 example.com/gateway-controller라는 컨트롤러 이름을 가진 GatewayClass를 관리하도록 구성돼 있어요. 이 클래스의 Gateway는 해당 구현의 컨트롤러가 관리해요.

GatewayClass의 전체 정의는 GatewayClass 참조에서 확인할 수 있어요.

Gateway

Gateway는 트래픽 처리 인프라의 인스턴스를 설명해요. Service 같은 백엔드에 대해 필터링, 부하 분산, 분할 등 트래픽을 처리하는 데 사용할 수 있는 네트워크 엔드포인트를 정의해요. 예를 들어 Gateway는 HTTP 트래픽을 받아들이도록 구성된 클라우드 로드 밸런서나 클러스터 내 프록시 서버를 나타낼 수 있어요.

일반적인 Gateway 리소스 예시:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: example-namespace
spec:
  gatewayClassName: example-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "www.example.com"
    allowedRoutes:
      namespaces:
        from: Same

이 예시에서 트래픽 처리 인프라의 인스턴스가 80 포트의 HTTP 트래픽을 받아들이도록 프로그래밍돼 있어요. addresses 필드가 지정되지 않았으므로, 구현의 컨트롤러가 Gateway에 주소 또는 호스트 이름을 할당해요. 이 주소는 라우트에 정의된 백엔드 네트워크 엔드포인트의 트래픽을 처리하는 네트워크 엔드포인트로 사용돼요.

Gateway의 전체 정의는 Gateway 참조에서 확인할 수 있어요. HTTPS/TLS 리스너 구성에 대한 지침은 Gateway API TLS 가이드를 참고하세요.

참고: 기본적으로 Gateway는 같은 네임스페이스의 라우트만 받아들여요. 교차 네임스페이스 라우트는 allowedRoutes를 구성해야 해요.

HTTPRoute

HTTPRoute 종류는 Gateway 리스너에서 백엔드 네트워크 엔드포인트로의 HTTP 요청 라우팅 동작을 지정해요. Service 백엔드의 경우, 구현은 백엔드 네트워크 엔드포인트를 Service IP나 Service의 지원 엔드포인트(EndpointSlice)로 표현할 수 있어요. HTTPRoute는 기본 Gateway 구현에 적용되는 구성을 나타내요. 예를 들어 새 HTTPRoute를 정의하면 클라우드 로드 밸런서나 클러스터 내 프록시 서버에 추가 트래픽 라우트가 구성될 수 있어요.

일반적인 HTTPRoute 예시:

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

이 예시에서 Host: 헤더가 www.example.com으로 설정되고 요청 경로가 /login으로 지정된 example-gateway Gateway의 HTTP 트래픽이 8080 포트의 example-svc Service로 라우팅돼요.

HTTPRoute의 전체 정의는 HTTPRoute 참조에서 확인할 수 있어요.

GRPCRoute

GRPCRoute 종류는 Gateway 리스너에서 백엔드 네트워크 엔드포인트로의 gRPC 요청 라우팅 동작을 지정해요. Service 백엔드의 경우, 구현은 백엔드 네트워크 엔드포인트를 Service IP나 Service의 지원 엔드포인트(EndpointSlice)로 표현할 수 있어요. GRPCRoute는 기본 Gateway 구현에 적용되는 구성을 나타내요. 예를 들어 새 GRPCRoute를 정의하면 클라우드 로드 밸런서나 클러스터 내 프록시 서버에 추가 트래픽 라우트가 구성될 수 있어요.

GRPCRoute를 지원하는 Gateway는 HTTP/1에서 초기 업그레이드 없이 HTTP/2를 지원해야 해요. 그래야 gRPC 트래픽이 제대로 흐르는 게 보장돼요.

일반적인 GRPCRoute 예시:

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

이 예시에서 호스트가 svc.example.com으로 설정된 example-gateway Gateway의 gRPC 트래픽이 같은 네임스페이스의 50051 포트 example-svc 서비스로 전달돼요.

GRPCRoute는 다음 예시처럼 특정 gRPC 서비스를 매칭할 수도 있어요.

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

이 경우 GRPCRoute는 svc.example.com에 대한 모든 트래픽을 매칭하고 라우팅 규칙을 적용해 트래픽을 올바른 백엔드로 전달해요. 매칭이 하나뿐이므로 svc.example.com에 대한 com.example.User.Login 메서드 요청만 전달돼요. 다른 메서드의 RPC는 이 Route에 매칭되지 않아요.

GRPCRoute의 전체 정의는 GRPCRoute 참조에서 확인할 수 있어요.

요청 흐름

Gateway와 HTTPRoute를 사용해 HTTP 트래픽을 Service로 라우팅하는 간단한 예시를 볼게요.

역방향 프록시로 구현된 Gateway의 요청 흐름은 다음과 같아요.

  1. 클라이언트가 http://www.example.com URL에 대한 HTTP 요청을 준비하기 시작해요.
  2. 클라이언트의 DNS 리졸버가 대상 이름을 쿼리하고 Gateway와 연결된 하나 이상의 IP 주소에 대한 매핑을 알아내요.
  3. 클라이언트가 Gateway IP 주소로 요청을 보내요. 역방향 프록시가 HTTP 요청을 받고 Host: 헤더를 사용해 Gateway와 연결된 HTTPRoute에서 파생된 구성을 매칭해요.
  4. 선택적으로 역방향 프록시는 HTTPRoute의 매칭 규칙에 따라 요청 헤더 및/또는 경로 매칭을 수행할 수 있어요.
  5. 선택적으로 역방향 프록시는 HTTPRoute의 필터 규칙에 따라 헤더를 추가하거나 제거하는 등 요청을 수정할 수 있어요.
  6. 마지막으로 역방향 프록시는 요청을 하나 이상의 백엔드로 전달해요.

적합성 (Conformance)

Gateway API는 광범위한 기능을 다루며 널리 구현돼 있어요. 이 조합은 API가 어디서 사용되든 일관된 경험을 제공하도록 명확한 적합성 정의와 테스트를 요구해요.

릴리스 채널, 지원 수준, 적합성 테스트 실행 같은 세부 사항은 적합성 문서를 참고하세요.

Ingress에서 마이그레이션

Gateway API는 Ingress API의 후속이에요. 다만 Ingress 종류를 포함하지 않아요. 그 결과 기존 Ingress 리소스를 Gateway API 리소스로 일회성 변환하는 것이 필요해요.

Ingress 리소스를 Gateway API 리소스로 마이그레이션하는 방법은 ingress 마이그레이션 가이드를 참고하세요.

더 알아보기

Gateway API 리소스가 Kubernetes에서 기본 구현되는 대신, 스펙은 커스텀 리소스로 정의되며 다양한 구현에서 지원돼요. Gateway API CRD를 설치하거나 선택한 구현의 설치 지침을 따르세요. 구현을 설치한 후 Getting Started 가이드를 사용해 Gateway API 작업을 빠르게 시작할 수 있어요.

참고: 선택한 구현의 문서를 검토해서 주의 사항을 이해하세요.

모든 Gateway API 종류의 추가 세부 사항은 API 스펙을 참고하세요.