Kubernetes Gateway API 완벽 가이드 — Ingress 마이그레이션부터 트래픽 분할까지

인프라 제공자 (Infrastructure Provider)
  └─ GatewayClass: 어떤 컨트롤러가 Gateway를 구현할지 정의
       │
클러스터 운영자 (Cluster Operator)
  └─ Gateway: 리스너(포트, 프로토콜, TLS) 설정
       │
애플리케이션 개발자 (Application Developer)
  └─ HTTPRoute / GRPCRoute / TCPRoute: 라우팅 규칙 정의
       │
  └─ Service → Pod: 실제 트래픽 처리

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway-class
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  description: 'Envoy Gateway 기반 프로덕션 게이트웨이 클래스'

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: gateway-infra
  annotations:
    cert-manager.io/cluster-issuer: 'letsencrypt-prod'
spec:
  gatewayClassName: envoy-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: HTTPS
      port: 443
      hostname: '*.example.com'
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-tls-cert
            namespace: gateway-infra
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: 'enabled'

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: backend-app
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-infra
      sectionName: https
  hostnames:
    - 'api.example.com'
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v2/users
          headers:
            - name: X-API-Version
              value: '2'
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Forwarded-By
                value: 'gateway-api'
      backendRefs:
        - name: users-service-v2
          port: 8080
          weight: 100
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api-service-v1
          port: 8080
          weight: 90
        - name: api-service-v2
          port: 8080
          weight: 10

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-gateway-to-backend-secrets
  namespace: gateway-infra
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: gateway-infra
  to:
    - group: ''
      kind: Secret

# Gateway API 표준 CRD 설치 (v1.4.x)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml

# 실험적 기능 포함 설치 (TCPRoute, UDPRoute, BackendTLSPolicy 포함)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/experimental-install.yaml

# CRD 설치 확인
kubectl get crd | grep gateway.networking.k8s.io

# 출력 예시:
# gatewayclasses.gateway.networking.k8s.io
# gateways.gateway.networking.k8s.io
# httproutes.gateway.networking.k8s.io
# referencegrants.gateway.networking.k8s.io
# grpcroutes.gateway.networking.k8s.io

# Envoy Gateway 설치
helm install envoy-gateway oci://docker.io/envoyproxy/gateway-helm \
  --version v1.3.0 \
  -n envoy-gateway-system \
  --create-namespace

# 설치 확인
kubectl get pods -n envoy-gateway-system
kubectl get gatewayclass

# ingress2gateway 설치
go install github.com/kubernetes-sigs/ingress2gateway@latest

# 현재 클러스터의 Ingress 리소스를 변환
ingress2gateway print --providers ingress-nginx \
  --all-namespaces > gateway-resources.yaml

# 변환된 리소스 검토 (반드시 수동 확인 필수)
cat gateway-resources.yaml

# 변환된 리소스를 스테이징 환경에 먼저 적용
kubectl apply -f gateway-resources.yaml --dry-run=server
kubectl apply -f gateway-resources.yaml -n staging

# Gateway 상태 확인 - Programmed: True 확인 필수
kubectl get gateway production-gateway -n gateway-infra -o jsonpath='{.status.conditions}'

# HTTPRoute 상태 확인
kubectl get httproute -A

# DNS를 Gateway API 엔드포인트로 변경 전 테스트
GATEWAY_IP=$(kubectl get gateway production-gateway -n gateway-infra \
  -o jsonpath='{.status.addresses[0].value}')
curl -H "Host: api.example.com" https://$GATEWAY_IP/v1/health --resolve "api.example.com:443:$GATEWAY_IP"

# 정상 확인 후 DNS 변경 (CNAME 또는 A 레코드)
# 모든 서비스 전환 완료 후 기존 Ingress 리소스 삭제
kubectl delete ingress api-ingress -n backend-app

# Ingress 리소스 하나씩 삭제하며 검증
kubectl delete ingress api-ingress -n backend-app
# 즉시 서비스 접근 테스트
curl -I https://api.example.com/v1/health

# 모든 Ingress 삭제 확인 후 컨트롤러 제거
kubectl get ingress -A  # 남은 Ingress 없는지 확인
helm uninstall ingress-nginx -n ingress-nginx
kubectl delete namespace ingress-nginx

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tls-gateway
  namespace: gateway-infra
  annotations:
    cert-manager.io/cluster-issuer: 'letsencrypt-prod'
spec:
  gatewayClassName: envoy-gateway-class
  listeners:
    - name: https-wildcard
      protocol: HTTPS
      port: 443
      hostname: '*.example.com'
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-example-tls
      allowedRoutes:
        namespaces:
          from: All
    - name: https-specific
      protocol: HTTPS
      port: 443
      hostname: 'admin.internal.com'
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: admin-tls-cert
      allowedRoutes:
        namespaces:
          from: Same

apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: backend-tls
  namespace: backend-app
spec:
  targetRefs:
    - group: ''
      kind: Service
      name: secure-backend-service
  validation:
    caCertificateRefs:
      - name: backend-ca-cert
        group: ''
        kind: ConfigMap
    hostname: secure-backend.backend-app.svc.cluster.local

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: passthrough-gateway
  namespace: gateway-infra
spec:
  gatewayClassName: envoy-gateway-class
  listeners:
    - name: tls-passthrough
      protocol: TLS
      port: 443
      hostname: 'secure-app.example.com'
      tls:
        mode: Passthrough
      allowedRoutes:
        namespaces:
          from: All

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
  namespace: backend-app
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-infra
  hostnames:
    - 'app.example.com'
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        # 안정 버전: 90% 트래픽
        - name: app-stable
          port: 8080
          weight: 90
        # 카나리 버전: 10% 트래픽
        - name: app-canary
          port: 8080
          weight: 10

#!/bin/bash
# 카나리 트래픽 점진적 증가 스크립트

ROUTE_NAME="canary-route"
NAMESPACE="backend-app"
STAGES=(10 25 50 75 100)
WAIT_MINUTES=5

for canary_weight in "${STAGES[@]}"; do
  stable_weight=$((100 - canary_weight))

  echo "[$(date)] 카나리 트래픽 비율: ${canary_weight}%"

  kubectl patch httproute $ROUTE_NAME -n $NAMESPACE --type='json' \
    -p="[
      {\"op\": \"replace\", \"path\": \"/spec/rules/0/backendRefs/0/weight\", \"value\": $stable_weight},
      {\"op\": \"replace\", \"path\": \"/spec/rules/0/backendRefs/1/weight\", \"value\": $canary_weight}
    ]"

  echo "대기 ${WAIT_MINUTES}분... (에러율 모니터링)"
  sleep $((WAIT_MINUTES * 60))

  # 에러율 확인 (Prometheus 쿼리 예시)
  ERROR_RATE=$(kubectl exec -n monitoring prometheus-0 -- \
    promtool query instant \
    'rate(http_requests_total{service="app-canary",code=~"5.."}[5m]) / rate(http_requests_total{service="app-canary"}[5m]) * 100' \
    2>/dev/null | grep -oP '[0-9.]+' | head -1)

  if (( $(echo "$ERROR_RATE > 5" | bc -l 2>/dev/null) )); then
    echo "에러율 ${ERROR_RATE}% 초과! 롤백 실행"
    kubectl patch httproute $ROUTE_NAME -n $NAMESPACE --type='json' \
      -p='[
        {"op": "replace", "path": "/spec/rules/0/backendRefs/0/weight", "value": 100},
        {"op": "replace", "path": "/spec/rules/0/backendRefs/1/weight", "value": 0}
      ]'
    echo "롤백 완료. 카나리 배포 중단."
    exit 1
  fi
done

echo "카나리 배포 완료. 트래픽 100% 전환 성공."

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-based-route
  namespace: backend-app
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-infra
  hostnames:
    - 'app.example.com'
  rules:
    # 규칙 1: X-Canary 헤더가 있으면 v2로 라우팅
    - matches:
        - headers:
            - name: X-Canary
              value: 'true'
      backendRefs:
        - name: app-v2
          port: 8080
    # 규칙 2: 기본 트래픽은 v1으로 라우팅
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: app-v1
          port: 8080

# Gateway 상태 조건 확인
kubectl describe gateway production-gateway -n gateway-infra

# HTTPRoute 상태 확인
kubectl get httproute -A -o custom-columns=\
'NAME:.metadata.name,HOSTNAMES:.spec.hostnames[*],PARENT:.spec.parentRefs[0].name,ACCEPTED:.status.parents[0].conditions[?(@.type=="Accepted")].status'

# 컨트롤러 Pod 상태 확인
kubectl get pods -n envoy-gateway-system

# Gateway 이벤트 확인
kubectl describe gateway production-gateway -n gateway-infra | tail -20

# TLS Secret 존재 여부 확인
kubectl get secret wildcard-tls-cert -n gateway-infra

# GatewayClass 상태 확인
kubectl get gatewayclass envoy-gateway-class -o yaml

# HTTPRoute 상태의 ResolvedRefs 조건 확인
kubectl get httproute api-route -n backend-app -o yaml | grep -A5 "ResolvedRefs"

# 백엔드 Service 존재 여부 확인
kubectl get svc users-service-v2 -n backend-app

# Endpoints 확인 (건강한 Pod가 있는지)
kubectl get endpoints users-service-v2 -n backend-app

# Pod 상태 및 로그 확인
kubectl get pods -n backend-app -l app=users-service-v2
kubectl logs -n backend-app -l app=users-service-v2 --tail=50

# ReferenceGrant 목록 확인
kubectl get referencegrant -A

# 특정 네임스페이스의 ReferenceGrant 상세 확인
kubectl describe referencegrant -n gateway-infra

# Certificate 리소스 상태 확인
kubectl get certificate -n gateway-infra

# cert-manager 로그 확인
kubectl logs -n cert-manager deploy/cert-manager --tail=100

# Challenge 상태 확인 (ACME HTTP-01)
kubectl get challenge -A

# Order 상태 확인
kubectl get order -A

# 즉시 안정 버전으로 100% 트래픽 복원
kubectl patch httproute canary-route -n backend-app --type='json' \
  -p='[
    {"op": "replace", "path": "/spec/rules/0/backendRefs/0/weight", "value": 100},
    {"op": "replace", "path": "/spec/rules/0/backendRefs/1/weight", "value": 0}
  ]'

# 적용 확인
kubectl get httproute canary-route -n backend-app -o yaml

# 업그레이드 전 백업
kubectl get gateway,httproute,referencegrant -A -o yaml > gateway-backup.yaml

# Helm 롤백
helm rollback envoy-gateway -n envoy-gateway-system

# 데이터 플레인 Pod 상태 확인
kubectl get pods -n envoy-gateway-system -w