Lab - Gateway API

Kubernetes Gateway API 실전 가이드 (2025년 업데이트)

이 가이드는 Kubernetes에서 인그레스(Ingress) 및 트래픽 라우팅을 관리하는 현대적이고 확장 가능한 방식인 Gateway API를 소개합니다. 본 가이드에서는 NGINX Gateway Controller를 예시로 사용하지만, Gateway API의 개념과 리소스는 특정 구현체에 종속되지 않으므로 다른 컨트롤러(Istio, Kong 등)에도 동일하게 적용됩니다.

1. NGINX를 이용한 Gateway API 설치

Gateway API는 커스텀 리소스(CRD)를 정의하지만, 이를 실제로 동작하게 할 컨트롤러가 필요합니다.

설치 명령어:

Bash

# 표준 CRD 설치
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.2" | kubectl apply -f -

# 실험적(Experimental) CRD 설치
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.2" | kubectl apply -f -

# Helm을 이용한 NGINX Gateway Fabric 설치
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway

설명: 이 과정은 NGINX Gateway 컨트롤러와 함께 필요한 API 정의(CRD)를 클러스터에 배포합니다.

2. GatewayClass 정의

GatewayClass는 특정 컨트롤러에 의해 구현될 Gateway 세트의 청사진(Blueprint) 역할을 합니다.

주요 목적: * 인프라 설정과 실제 게이트웨이 구성을 분리합니다.
- 한 클러스터 내에서 여러 개의 게이트웨이 구현체(예: NGINX와 Istio 동시 사용)를 지원합니다.
예시:

YAML

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx
spec:
  controllerName: nginx.org/gateway-controller

3. HTTP Gateway 및 리스너 설정

Gateway 리소스는 트래픽이 클러스터로 들어오는 방식을 정의합니다. 프로토콜, 포트, 라우팅 규칙 등을 지정합니다.

예시: 80번 포트에서 HTTP 트래픽을 수신하는 설정

YAML

spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All

핵심 설정: allowedRoutes.namespaces.from: All은 모든 네임스페이스에 정의된 라우트가 이 게이트웨이를 사용할 수 있도록 허용합니다.

4. HTTP 라우팅 (HTTPRoute)

HTTPRoute는 HTTP 트래픽을 어떤 서비스로 보낼지 결정하는 규칙을 정의합니다.

예시: /app 경로로 들어오는 트래픽을 my-app 서비스로 전달

YAML

spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - matches:
    - path: { type: PathPrefix, value: /app }
    backendRefs:
    - name: my-app
      port: 80

5. HTTP 리다이렉트 및 리라이트 (Redirects & Rewrites)

HTTP → HTTPS 리다이렉트

보안을 위해 모든 HTTP 트래픽을 HTTPS로 강제 전환합니다.

필터 사용: type: RequestRedirect를 통해 스킴(scheme)을 https로 변경합니다.

경로 리라이트 (Path Rewrite)

백엔드 서비스로 전달하기 전에 요청 경로를 수정합니다.

예시: 사용자가 /old로 접속하면 서버 내부적으로는 /new로 경로를 바꿔서 전달합니다. (replacePrefixMatch: /new)

6. HTTP 헤더 수정

요청이나 응답에 커스텀 헤더를 추가, 설정 또는 제거할 수 있습니다.

활용: x-env: staging 같은 헤더를 추가하여 환경 정보를 백엔드에 전달할 때 유용합니다.

7. 트래픽 분할 (Traffic Splitting)

카나리 배포(Canary Deployment)나 A/B 테스트를 위해 트래픽을 여러 서비스에 가중치(Weight) 기반으로 배포합니다.

예시:
- v1-service: weight 80 (80% 트래픽)
- v2-service: weight 20 (20% 트래픽)

8. 요청 미러링 (Request Mirroring)

운영 서비스에 영향을 주지 않고, 요청의 복사본을 다른 서비스(테스트용 등)로 보냅니다.

용도: 새로운 버전의 성능 분석이나 트래픽 패턴 테스트 시 유용합니다.

9. TLS 설정 (보안)

게이트웨이 레벨에서 TLS 인증서를 관리하여 트래픽을 암호화/복호화합니다.

TLS Termination: 게이트웨이가 클라이언트와의 암호화 통신을 끝내고(복호화), 내부 서비스에는 평문으로 전달하는 방식입니다. Kubernetes Secret에 저장된 인증서를 참조합니다.

10. TCP, UDP 및 기타 프로토콜

Gateway API는 HTTP뿐만 아니라 다양한 프로토콜을 지원합니다.

TCP: 데이터베이스(MySQL 등) 연결에 사용 (예: 3306 포트).
UDP: DNS 서버나 스트리밍 서비스에 사용 (예: 53 포트).
gRPC: 고성능 마이크로서비스 통신을 위해 HTTPRoute를 통해 메서드 단위 매칭을 지원합니다.

결론

Gateway API는 헤더 수정, 트래픽 분할, 다양한 프로토콜 지원 등 표준화되고 표현력이 풍부한 라우팅을 제공합니다. 기본적인 HTTP 설정부터 시작해 TLS, TCP 등으로 확장해 나가면 더욱 안전하고 확장성 있는 Kubernetes 인그레스 전략을 구축할 수 있습니다.

쿠버네티스 환경에서 API Gateway는 외부의 요청을 받아 내부 클러스터의 적절한 서비스로 전달하고 관리하는 단일 진입점 역할을 합니다.

과거에는 Ingress 리소스를 주로 사용했지만, 현재는 더 강력하고 표준화된 Kubernetes Gateway API가 그 역할을 대체하며 대세로 자리 잡고 있습니다.

1. 왜 쿠버네티스에서 API Gateway가 필요한가?

클러스터 내부에는 수많은 마이크로서비스(Pod)가 존재하며, 이들은 수시로 생성되고 사라집니다. 클라이언트가 이 모든 변화를 추적할 수 없으므로, 중간에서 다음과 같은 복잡한 일을 처리해 줄 존재가 필요합니다.

L7 라우팅: URL 경로(/api/v1)나 호스트명(shop.example.com)에 따라 트래픽 분산
보안: SSL/TLS 인증서 터미네이션, 인증(AuthN) 및 인가(AuthZ) 처리
트래픽 제어: 속도 제한(Rate Limiting), 카나리 배포를 위한 트래픽 분할(Traffic Splitting)
관찰 가능성: 모든 요청에 대한 로깅 및 모니터링 데이터 수집

2. Ingress vs Gateway API

쿠버네티스 초기에는 Ingress를 사용했지만, 기능이 제한적이라 설정이 파편화되는 문제가 있었습니다. 이를 해결하기 위해 등장한 것이 Gateway API입니다.

비교 항목	Ingress (구형 표준)	Gateway API (신규 표준)
유연성	제한적 (Annotation에 의존)	매우 높음 (표준 필터 지원)
역할 분리	하나의 리소스에 모든 설정 집중	인프라 관리자 / 서비스 개발자 역할 분리
트래픽 제어	기본적으로 지원하지 않음	가중치 기반 트래픽 분할 등 기본 지원
지원 프로토콜	HTTP, HTTPS 중심	HTTP, gRPC, TCP, UDP 등 확장 가능

3. Gateway API의 구조 (역할 분담)

Gateway API는 설정을 세 가지 계층으로 나누어 관리합니다. 이를 통해 인프라 팀과 개발 팀이 서로의 영역을 침범하지 않고 작업할 수 있습니다.

GatewayClass: 클러스터 운영자가 정의하며, 어떤 컨트롤러(NGINX, Istio, Kong 등)를 사용할지 결정합니다.
Gateway: 인프라 관리자가 정의하며, 실제 IP가 할당되고 어떤 포트(80, 443)를 열지 설정합니다.
HTTPRoute: 서비스 개발자가 정의하며, 들어온 요청을 어떤 서비스로 보낼지 세부 라우팅 규칙을 작성합니다.

4. 대표적인 쿠버네티스용 API Gateway 솔루션

쿠버네티스 API Gateway는 표준 규격일 뿐, 이를 실제로 실행할 엔진(컨트롤러)이 필요합니다.

NGINX Gateway Fabric: NGINX 기반의 공식 Gateway API 구현체입니다.
Istio: 서비스 메시 솔루션이지만, 매우 강력한 Gateway 기능을 제공합니다.
Kong Mesh / Gateway: API 관리 기능이 매우 풍부하며 플러그인이 많습니다.
Cilium: eBPF 기술을 사용하여 매우 높은 성능의 네트워킹과 게이트웨이 기능을 제공합니다.
Envoy Gateway: Envoy Proxy를 기반으로 하는 클라우드 네이티브 게이트웨이 표준 프로젝트입니다.

요약

쿠버네티스에서 API Gateway를 구축한다면, 이제는 Ingress 대신 Gateway API를 고려해야 합니다. 이를 통해 더 정교한 트래픽 관리(카나리 배포, 헤더 수정 등)를 표준화된 방식으로 수행할 수 있습니다.

Which API resource is used to define a Gateway in Kubernetes?

-> Gateway

What is the purpose of the allowedRoutes field in a Gateway?

왜 allowedRoutes가 필요한가요?

기존 Ingress 시스템에서는 인프라 전체 설정과 서비스 라우팅 설정이 섞여 있어 관리가 어려웠습니다. Gateway API는 이를 분리하면서 다음과 같은 시나리오를 가능하게 합니다.

보안 및 격리: 인프라 관리자가 "이 공용 게이트웨이는 marketing 네임스페이스의 서비스들만 연결할 수 있다"라고 제한할 수 있습니다.
권한 분리: 개발자가 실수로 운영 환경의 게이트웨이에 자신의 라우트를 연결하여 트래픽을 가로채는 사고를 방지합니다.

allowedRoutes는 인프라 관리자가 인프라 자원(Gateway)과 애플리케이션 설정(Route) 사이의 경계를 명확히 하고, 누가 어떤 게이트웨이를 사용할 수 있는지 결정하기 위해 사용되는 필드입니다.

Which of the following protocols is NOT supported by the Kubernetes Gateway API?

Kubernetes 게이트웨이 API는 HTTP, HTTPS, TCP, UDP 및 TLS 프로토콜을 지원합니다.
그러나 ICMP는 애플리케이션 트래픽에 사용되는 전송 계층 프로토콜이 아니기 때문에 지원되지 않습니다.

How does a GatewayClass differ from a Gateway?

게이트웨이 클래스는 IngressClass와 유사하며 게이트웨이의 컨트롤러별 동작을 정의합니다.
게이트웨이는 게이트웨이 클래스의 기본 구현을 결정하기 위해 참조하는 인스턴스입니다.

간단히 말해서:

게이트웨이클래스: 템플릿 또는 유형.
게이트웨이: 템플릿을 사용하는 배포된 인스턴스.

What is the primary advantage of using Gateway API over Ingress?

게이트웨이 API는 Ingress보다 더 고급 라우팅 기능을 제공하며, 여기에는 다음이 포함됩니다:

다중 프로토콜 지원(HTTP, TCP, UDP 등)
경로 및 필터를 통한 더 나은 확장성
AllowedRoutes를 사용한 보다 세분화된 접근 제어
주로 HTTP 기반인 Ingress와 달리, 게이트웨이 API는 여러 프로토콜에 걸쳐 유연성을 제공하도록 설계되었습니다.

Install the Gateway API resources
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.5.1" | kubectl apply -f -

Deploy the NGINX Gateway Fabric CRDs
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/crds.yaml

Deploy NGINX Gateway Fabric
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.1/deploy/nodeport/deploy.yaml

Verify the Deployment
kubectl get pods -n nginx-gateway

View the nginx-gateway service
kubectl get svc -n nginx-gateway nginx-gateway -o yaml

Update the nginx-gateway service to expose ports 30080 for HTTP and 30081 for HTTPS
kubectl patch svc nginx-gateway -n nginx-gateway --type='json' -p='[
{"op": "replace", "path": "/spec/ports/0/nodePort", "value": 30080},
{"op": "replace", "path": "/spec/ports/1/nodePort", "value": 30081}
]'

Create a Kubernetes Gateway resource with the following specifications:

Name: nginx-gateway
Namespace: nginx-gateway
Gateway Class Name: nginx
Listeners:
Protocol: HTTP
Port: 80
Name: http
Allowed Routes: All namespaces

A new pod named frontend-app and a service called frontend-svc have been deployed in the default namespace.
Expose the service on the / path by creating an HTTPRoute named frontend-route.

vi frontend-route.yaml

'k8s > CKA' 카테고리의 다른 글

Deplyment with kubeadm (2)	2026.04.26
Choosing kubernetes infrastructure, Configure hgih availability (0)	2026.04.24
Lab - CKA Ingress (0)	2026.04.22
Lab - Explore DNS , DNS in kubernetes (2)	2026.04.21
Lab - Service Networking (0)	2026.04.21

yutju 님의 블로그

Lab - Gateway API

Kubernetes Gateway API 실전 가이드 (2025년 업데이트)

1. NGINX를 이용한 Gateway API 설치

2. GatewayClass 정의

3. HTTP Gateway 및 리스너 설정

4. HTTP 라우팅 (HTTPRoute)

5. HTTP 리다이렉트 및 리라이트 (Redirects & Rewrites)

HTTP → HTTPS 리다이렉트

경로 리라이트 (Path Rewrite)

6. HTTP 헤더 수정

7. 트래픽 분할 (Traffic Splitting)

8. 요청 미러링 (Request Mirroring)

9. TLS 설정 (보안)

10. TCP, UDP 및 기타 프로토콜

결론

1. 왜 쿠버네티스에서 API Gateway가 필요한가?

2. Ingress vs Gateway API

3. Gateway API의 구조 (역할 분담)

4. 대표적인 쿠버네티스용 API Gateway 솔루션

요약

왜 allowedRoutes가 필요한가요?

'k8s > CKA' 카테고리의 다른 글

티스토리툴바

Lab - Gateway API

Kubernetes Gateway API 실전 가이드 (2025년 업데이트)

1. NGINX를 이용한 Gateway API 설치

2. GatewayClass 정의

3. HTTP Gateway 및 리스너 설정

4. HTTP 라우팅 (HTTPRoute)

5. HTTP 리다이렉트 및 리라이트 (Redirects & Rewrites)

HTTP → HTTPS 리다이렉트

경로 리라이트 (Path Rewrite)

6. HTTP 헤더 수정

7. 트래픽 분할 (Traffic Splitting)

8. 요청 미러링 (Request Mirroring)

9. TLS 설정 (보안)

10. TCP, UDP 및 기타 프로토콜

결론

1. 왜 쿠버네티스에서 API Gateway가 필요한가?

2. Ingress vs Gateway API

3. Gateway API의 구조 (역할 분담)

4. 대표적인 쿠버네티스용 API Gateway 솔루션

요약

왜 allowedRoutes가 필요한가요?

'k8s > CKA' 카테고리의 다른 글

관련글

티스토리툴바