Kubernetes Gateway API: NGINX를 활용한 실습 가이드 (2025 최신 업데이트)
이 가이드는 Kubernetes Gateway API를 소개합니다. 이는 Kubernetes에서 인그레스(Ingress) 및 트래픽 라우팅을 관리하는 현대적이고 확장 가능한 접근 방식입니다. 이번 데모에서는 NGINX Gateway Controller를 사용하지만, 이 문서에서 설명하는 개념과 API는 Gateway API를 지원하는 모든 컨트롤러에서 동일하게 적용됩니다.
📚 공식 문서: https://gateway-api.sigs.k8s.io
1. NGINX를 이용한 Gateway API 설치
Gateway API는 Custom Resource(사용자 정의 리소스)를 정의합니다. 하지만 이를 실제로 동작시키기 위해서는 컨트롤러가 필요합니다. 여기서는 NGINX Gateway Controller를 사용하며, 이 컨트롤러는 Gateway API의 모든 표준 리소스를 지원합니다.
다음 명령어를 실행하여 설치합니다.
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.2" | kubectl apply -f -
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.2" | kubectl apply -f -
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway설명:
- 위 명령어는 NGINX Gateway Controller와 Gateway API를 위한 Custom Resource Definitions(CRD)을 설치합니다.
🔗 NGINX Gateway Fabric 참조
2. GatewayClass 정의
GatewayClass는 특정 컨트롤러가 구현하는 Gateway의 집합을 정의합니다. 쉽게 말해, 어떤 컨트롤러가 이 Gateway를 관리할지 Kubernetes에게 알려주는 설계도입니다.
목적
- Gateway 구성을 컨트롤러 구현체로부터 분리합니다. 즉, 사용자는 어떤 컨트롤러가 동작하는지 몰라도 됩니다.
- 하나의 클러스터에 여러 Gateway 구현체(NGINX, Istio 등)를 동시에 운영할 수 있습니다.
예시
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: nginx
spec:
controllerName: nginx.org/gateway-controller설명:
controllerName: 해당 GatewayClass를 관리하는 컨트롤러 이름입니다. 여기서는nginx.org/gateway-controller로 NGINX를 사용합니다.
🔗 GatewayClass 문서 참조
3. HTTP Gateway 및 Listener 설정
Gateway는 외부 트래픽이 클러스터로 진입하는 방식을 정의하는 Kubernetes 리소스입니다. 어떤 프로토콜, 어떤 포트, 어떤 규칙으로 트래픽을 처리할지 명시합니다.
예시
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: nginx-gateway
namespace: default
spec:
gatewayClassName: nginx
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All설명:
-
gatewayClassName: 사용할 GatewayClass 이름입니다. -
listeners: 이 Gateway가 트래픽을 어떤 방식으로 수신할지를 정의합니다.protocol: HTTP 프로토콜 사용port: 80번 포트에서 수신allowedRoutes: 모든 네임스페이스의 Route 리소스를 허용합니다.
4. HTTP 라우팅
HTTPRoute는 HTTP 트래픽을 어떤 서비스로 전달할지를 정의합니다. Gateway와 연결되어 작동하며, 경로나 헤더 등의 조건에 따라 트래픽을 분배합니다.
예시
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: basic-route
namespace: default
spec:
parentRefs:
- name: nginx-gateway
namespace: nginx-gateway
# 만약 다른 namespace에 참조하는 gateway가 존재한다면 명시 해줘야함
rules:
- matches:
- path:
type: PathPrefix
value: /app
backendRefs:
- name: my-app
port: 80설명:
-
parentRefs: 어떤 Gateway와 연결할지 지정합니다. -
rules: 트래픽 매칭 및 전달 규칙matches:/app으로 시작하는 경로를 매칭backendRefs: 해당 트래픽을my-app서비스의 80번 포트로 전달
🔗 HTTP Routing 가이드
5. HTTP 리다이렉트 및 리라이트
HTTP → HTTPS 리다이렉트 예시
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: https-redirect
namespace: default
spec:
parentRefs:
- name: nginx-gateway
rules:
- filters:
- type: RequestRedirect
requestRedirect:
scheme: https설명:
- HTTP 요청을 HTTPS로 강제 리다이렉트합니다.
🔗 HTTP Redirects 가이드
경로 리라이트 예시
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: rewrite-path
namespace: default
spec:
parentRefs:
- name: nginx-gateway
rules:
- matches:
- path:
type: PathPrefix
value: /old
filters:
- type: URLRewrite
urlRewrite:
path:
replacePrefixMatch: /new
backendRefs:
- name: my-app
port: 80설명:
/old로 시작하는 요청 경로를/new로 변경한 뒤my-app서비스로 전달합니다.
🔗 HTTP Rewrite 가이드
6. HTTP 헤더 수정
요청 또는 응답 헤더를 추가, 수정, 삭제할 수 있습니다.
예시
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: header-mod
namespace: default
spec:
parentRefs:
- name: nginx-gateway
rules:
- filters:
- type: RequestHeaderModifier
requestHeaderModifier:
add:
x-env: staging
backendRefs:
- name: my-app
port: 80설명:
- 요청 헤더에
x-env: staging값을 추가합니다. - 이런 방식으로 환경 변수 전달이나 메타데이터 삽입이 가능합니다.
🔗 HTTP Header 가이드
7. HTTP 트래픽 분할 (Traffic Splitting)
버전별 트래픽 분배나 카나리 배포에 활용됩니다.
예시
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: traffic-split
namespace: default
spec:
parentRefs:
- name: nginx-gateway
rules:
- backendRefs:
- name: v1-service
port: 80
weight: 80
- name: v2-service
port: 80
weight: 20설명:
- 트래픽의 80%는
v1-service, 20%는v2-service로 전달됩니다.
🔗 HTTP Traffic Splitting 가이드
8. HTTP 요청 미러링 (Request Mirroring)
요청을 주 서비스로 전달하면서 동시에 복사본을 다른 서비스로 보내 테스트나 모니터링 용도로 사용할 수 있습니다.
예시
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: request-mirror
namespace: default
spec:
parentRefs:
- name: nginx-gateway
rules:
- filters:
- type: RequestMirror
requestMirror:
backendRef:
name: mirror-service
port: 80
backendRefs:
- name: my-app
port: 80설명:
- 원래 요청은
my-app으로 전달되며, - 동시에 복사본은
mirror-service로 보내집니다.
🔗 HTTP Traffic Request 가이드
9. TLS 설정
TLS는 클라이언트와 서버 간의 트래픽을 암호화합니다. Gateway에서 TLS를 종료(terminate)하여 클러스터 내부로는 암호화되지 않은 트래픽으로 전달할 수 있습니다.
예시: TLS 종료
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: nginx-gateway-tls
namespace: default
spec:
gatewayClassName: nginx
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: tls-secret
allowedRoutes:
namespaces:
from: All설명:
- HTTPS 트래픽을 443 포트에서 수신
tls-secret이라는 Kubernetes Secret에서 인증서와 키를 참조- Gateway 레벨에서 암호화가 종료되고, 이후 백엔드 서비스로는 평문 트래픽 전달
🔗 TLS Configuration 가이드
10. TCP, UDP 및 기타 프로토콜 지원
Gateway API는 HTTP뿐만 아니라 TCP, UDP, gRPC 등의 다양한 프로토콜을 지원합니다.
TCP 예시 (MySQL)
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: tcp-gateway
namespace: default
spec:
gatewayClassName: nginx
listeners:
- name: tcp
protocol: TCP
port: 3306
allowedRoutes:
namespaces:
from: All설명:
- 3306 포트에서 TCP 트래픽을 수신합니다.
- 주로 데이터베이스(MySQL 등)에 사용됩니다.
UDP 예시 (DNS)
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: udp-gateway
namespace: default
spec:
gatewayClassName: nginx
listeners:
- name: udp
protocol: UDP
port: 53
allowedRoutes:
namespaces:
from: All설명:
- 53번 포트에서 UDP 트래픽을 수신합니다.
- 주로 DNS 서비스에 활용됩니다.
gRPC 예시
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: grpc-route
namespace: default
spec:
parentRefs:
- name: nginx-gateway
rules:
- matches:
- method:
service: my.grpc.Service
method: GetData
backendRefs:
- name: grpc-service
port: 50051설명:
my.grpc.Service의GetData메서드를 호출하는 gRPC 요청을grpc-service의 50051 포트로 전달합니다.
결론
Gateway API는 구조적이고 선언적인 방식으로 라우팅을 구성할 수 있게 해줍니다. HTTP 헤더 수정, 트래픽 분배, TLS, TCP, UDP, gRPC 등 다양한 프로토콜과 기능을 지원합니다. HTTP 기반의 기본적인 설정에서 시작해 TLS와 TCP 같은 고급 기능으로 확장할 수 있으며, Kubernetes 클러스터의 인그레스 전략을 더욱 안전하고 확장 가능하게 만들어 줍니다.
