Kubernetes Gateway API와 Envoy Gateway 트래픽 관리 실전 2026

• 개요
• Gateway API vs Ingress: 왜 전환해야 하는가
• 아키텍처
  • Gateway API 리소스 계층 구조
  • Envoy Gateway 아키텍처
• Gateway API 구현체 비교
• 핵심 리소스 설명
  • GatewayClass와 Gateway
  • HTTPRoute
  • GRPCRoute
  • BackendTLSPolicy
• 트래픽 관리 패턴
  • 카나리 배포 (가중치 기반 트래픽 분할)
  • 트래픽 미러링
  • 헤더 기반 라우팅
  • Rate Limiting (Envoy Gateway BackendTrafficPolicy)
• Envoy Gateway 설치와 초기 설정
  • Helm 기반 설치
  • supportedFeatures 확인
• 트러블슈팅
  • Route가 Gateway에 연결되지 않는 경우
  • 트래픽이 백엔드에 도달하지 않는 경우
  • Rate Limiting이 동작하지 않는 경우
• 실패 사례와 복구 절차
  • 사례 1: Gateway 업데이트 중 트래픽 중단
  • 사례 2: 잘못된 HTTPRoute 배포로 인한 라우팅 오류
  • 사례 3: Rate Limit Redis 장애 시 트래픽 폭주
• 운영 체크리스트
  • 배포 전 체크리스트
  • 모니터링 체크리스트
  • 업그레이드 체크리스트
  • Ingress에서 마이그레이션 체크리스트
• 마무리
• 참고자료

개요

2026년 3월 현재, Kubernetes Ingress NGINX의 유지보수 종료가 임박하면서 Gateway API로의 전환은 선택이 아닌 필수가 되었다. Gateway API는 v1.4까지 릴리스되며 BackendTLSPolicy, Named Rules, supportedFeatures 등 핵심 기능이 Standard 채널로 승격되었고, Envoy Gateway는 v1.6.x까지 진화하면서 SecurityPolicy, 글로벌/로컬 Rate Limiting, mTLS 등 엔터프라이즈급 트래픽 관리 기능을 제공하고 있다.

이 글에서는 Gateway API의 핵심 리소스 구조를 이해하고, Envoy Gateway를 구현체로 선택하여 운영 환경에서 실제로 트래픽을 관리하는 방법을 다룬다. 카나리 배포, 트래픽 미러링, 헤더 기반 라우팅, Rate Limiting, BackendTLSPolicy를 활용한 백엔드 mTLS까지 실전에서 바로 적용할 수 있는 패턴을 코드와 함께 제시한다.

Gateway API vs Ingress: 왜 전환해야 하는가

Ingress 리소스는 Kubernetes 초기부터 HTTP 트래픽 라우팅의 표준이었지만, 벤더별 어노테이션에 의존하는 구조적 한계가 있었다. Gateway API는 이 문제를 근본적으로 해결한다.

핵심 전환 동기는 세 가지다. 첫째, Ingress NGINX가 2026년 3월 유지보수 종료를 앞두고 있어 보안 패치가 중단된다. 둘째, Gateway API는 L4/L7 프로토콜을 통합 관리할 수 있어 TCP, UDP, gRPC 워크로드를 별도의 메커니즘 없이 처리한다. 셋째, 4가지 페르소나(인프라 제공자, 클러스터 운영자, 애플리케이션 관리자, 애플리케이션 개발자)에 맞춘 역할 분리가 멀티팀 환경에서 운영 효율을 극대화한다.

아키텍처

Gateway API 리소스 계층 구조

Gateway API는 세 계층으로 나뉜다. GatewayClass는 인프라 제공자가 정의하는 템플릿이다. Gateway는 클러스터 운영자가 GatewayClass를 기반으로 생성하는 로드밸런서 인스턴스다. Route(HTTPRoute, GRPCRoute, TLSRoute, TCPRoute)는 애플리케이션 개발자가 트래픽 라우팅 규칙을 정의하는 리소스다.

이 계층 구조 덕분에 클러스터 운영자는 TLS 인증서와 리스너 포트를 관리하면서, 애플리케이션 개발자는 자신의 네임스페이스 안에서 독립적으로 라우팅 규칙을 배포할 수 있다. ReferenceGrant 리소스를 통해 네임스페이스 간 참조 권한을 명시적으로 제어할 수 있다.

Envoy Gateway 아키텍처

Envoy Gateway는 Gateway API의 구현체로, 컨트롤 플레인과 데이터 플레인으로 구성된다. 컨트롤 플레인은 Gateway API 리소스를 감시(watch)하고 이를 Envoy 프록시 설정으로 변환한다. 데이터 플레인은 실제 트래픽을 처리하는 Envoy 프록시 인스턴스들이다. Envoy Gateway 컨트롤러가 Gateway 리소스를 감지하면 자동으로 Envoy 프록시 Deployment와 Service를 프로비저닝한다.

Envoy Gateway만의 차별점은 BackendTrafficPolicy, SecurityPolicy, ClientTrafficPolicy, EnvoyExtensionPolicy 같은 확장 CRD를 통해 Rate Limiting, 인증/인가, 트래픽 제어를 선언적으로 관리할 수 있다는 점이다.

Gateway API 구현체 비교

운영 환경에서 Gateway API 구현체를 선택할 때 다음 비교를 참고한다.

이 글에서는 Envoy Gateway를 중심으로 다루지만, Gateway API 표준을 따르므로 핵심 리소스(GatewayClass, Gateway, HTTPRoute, GRPCRoute) 정의는 다른 구현체에서도 동일하게 적용된다.

핵심 리소스 설명

GatewayClass와 Gateway

GatewayClass는 어떤 컨트롤러가 Gateway를 관리할지 지정하는 클러스터 범위 리소스다. Gateway는 실제 리스너(포트, 프로토콜, TLS 설정)를 정의하는 네임스페이스 범위 리소스다.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: infra
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-tls
            namespace: infra
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: 'true'
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same

이 설정에서 HTTPS 리스너는 gateway-access: "true" 레이블이 있는 네임스페이스의 Route만 허용한다. HTTP 리스너는 같은 네임스페이스의 Route만 허용하여 HTTPS 리다이렉트 전용으로 사용한다. allowedRoutes를 통한 이런 세분화된 접근 제어가 Ingress 대비 Gateway API의 가장 큰 장점 중 하나다.

HTTPRoute

HTTPRoute는 HTTP 트래픽의 라우팅 규칙을 정의한다. Gateway API v1.4에서 도입된 Named Rules 기능을 사용하면 각 규칙에 이름을 부여하여 관측성과 정책 타겟팅을 강화할 수 있다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: app
spec:
  parentRefs:
    - name: production-gateway
      namespace: infra
      sectionName: https
  hostnames:
    - 'api.example.com'
  rules:
    - name: health-check
      matches:
        - path:
            type: Exact
            value: /healthz
      backendRefs:
        - name: api-service
          port: 8080
    - name: api-v2
      matches:
        - path:
            type: PathPrefix
            value: /api/v2
          headers:
            - name: X-API-Version
              value: '2'
      backendRefs:
        - name: api-v2-service
          port: 8080
    - name: api-default
      matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-v1-service
          port: 8080

Named Rules(name: health-check, name: api-v2, name: api-default)는 Envoy 메트릭에서 각 규칙별 트래픽 통계를 확인할 때 유용하다. 또한 BackendTrafficPolicy에서 특정 규칙만 타겟팅할 수 있어 세분화된 트래픽 정책 적용이 가능하다.

GRPCRoute

GRPCRoute는 gRPC 트래픽을 네이티브로 라우팅한다. Gateway API v1.1부터 Standard 채널에 포함되어 GA 상태다.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-route
  namespace: app
spec:
  parentRefs:
    - name: production-gateway
      namespace: infra
      sectionName: https
  hostnames:
    - 'grpc.example.com'
  rules:
    - matches:
        - method:
            service: myapp.UserService
            method: GetUser
      backendRefs:
        - name: user-service-grpc
          port: 50051
    - matches:
        - method:
            service: myapp.OrderService
      backendRefs:
        - name: order-service-grpc
          port: 50051

GRPCRoute를 사용하는 Gateway는 HTTP/2를 필수로 지원해야 한다. Envoy Gateway는 기본적으로 HTTP/2를 지원하므로 추가 설정 없이 gRPC 라우팅이 동작한다.

BackendTLSPolicy

BackendTLSPolicy는 Gateway API v1.4에서 Standard 채널로 승격된 리소스로, Gateway와 백엔드 Pod 사이의 TLS 연결을 설정한다. 이를 통해 게이트웨이에서 백엔드까지 end-to-end 암호화를 구현할 수 있다.

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

이 설정은 Gateway가 api-service로 요청을 전달할 때 TLS를 사용하도록 강제하며, ConfigMap에 저장된 CA 인증서로 백엔드의 인증서를 검증한다. hostname 필드는 백엔드 인증서의 SAN(Subject Alternative Name)과 일치해야 한다.

트래픽 관리 패턴

카나리 배포 (가중치 기반 트래픽 분할)

Gateway API의 가중치 기반 트래픽 분할은 카나리 배포의 핵심 메커니즘이다. backendRefs에 weight를 지정하여 트래픽 비율을 조절한다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
  namespace: app
spec:
  parentRefs:
    - name: production-gateway
      namespace: infra
      sectionName: https
  hostnames:
    - 'app.example.com'
  rules:
    - name: canary-split
      matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: app-stable
          port: 8080
          weight: 90
        - name: app-canary
          port: 8080
          weight: 10

이 설정은 전체 트래픽의 90%를 안정 버전(app-stable)으로, 10%를 카나리 버전(app-canary)으로 라우팅한다. 카나리 검증이 완료되면 weight를 점진적으로 조정하여 0/100으로 전환한다.

Flagger와 같은 Progressive Delivery 도구와 결합하면 메트릭 기반 자동 카나리 프로모션을 구현할 수 있다. Flagger는 Gateway API를 네이티브로 지원하므로 HTTPRoute의 backendRefs weight를 자동으로 조정한다.

운영 시 주의할 점은 weight가 상대적 비율이라는 것이다. weight: 90과 weight: 10은 9:1 비율이고, weight: 9와 weight: 1도 동일한 9:1 비율이다. 가독성을 위해 합계를 100으로 맞추는 것을 권장한다.

트래픽 미러링

트래픽 미러링은 프로덕션 트래픽의 복사본을 테스트 환경으로 보내 실제 트래픽으로 검증할 때 사용한다. 미러된 트래픽의 응답은 클라이언트에게 반환되지 않으므로 프로덕션에 영향을 주지 않는다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mirror-route
  namespace: app
spec:
  parentRefs:
    - name: production-gateway
      namespace: infra
      sectionName: https
  hostnames:
    - 'api.example.com'
  rules:
    - name: mirror-to-staging
      matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: RequestMirror
          requestMirror:
            backendRef:
              name: api-staging
              port: 8080
      backendRefs:
        - name: api-production
          port: 8080

주의사항이 있다. 하나의 HTTPRoute 규칙에 복수의 RequestMirror 필터를 적용할 수 없다. 여러 대상으로 미러링이 필요하면 별도의 규칙을 정의하거나, 미러링 대상 서비스에서 다시 분기하는 구조를 설계해야 한다.

헤더 기반 라우팅

A/B 테스트나 특정 사용자 그룹에게 새 버전을 노출할 때 헤더 기반 라우팅을 활용한다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-routing
  namespace: app
spec:
  parentRefs:
    - name: production-gateway
      namespace: infra
      sectionName: https
  hostnames:
    - 'app.example.com'
  rules:
    - name: beta-users
      matches:
        - headers:
            - name: X-Beta-User
              value: 'true'
      backendRefs:
        - name: app-beta
          port: 8080
    - name: internal-debug
      matches:
        - headers:
            - name: X-Debug-Mode
              value: 'enabled'
          path:
            type: PathPrefix
            value: /api
      filters:
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            add:
              - name: X-Debug-Backend
                value: 'debug-v2'
      backendRefs:
        - name: app-debug
          port: 8080
    - name: default
      matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: app-production
          port: 8080

규칙의 순서가 중요하다. Gateway API는 가장 구체적인 매칭을 우선 적용하지만, 동일한 구체성을 가진 규칙은 정의 순서대로 평가된다. 헤더 매칭이 있는 규칙을 기본 규칙보다 먼저 배치해야 한다.

Rate Limiting (Envoy Gateway BackendTrafficPolicy)

Envoy Gateway는 BackendTrafficPolicy CRD를 통해 글로벌 Rate Limiting과 로컬 Rate Limiting을 모두 지원한다. v1.6부터는 두 가지를 동시에 적용할 수 있다.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: api-rate-limit
  namespace: app
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: api-route
  rateLimit:
    type: Global
    global:
      rules:
        - clientSelectors:
            - headers:
                - name: X-API-Key
                  type: Distinct
          limit:
            requests: 1000
            unit: Hour
        - clientSelectors:
            - headers:
                - name: X-API-Tier
                  value: 'premium'
          limit:
            requests: 10000
            unit: Hour
        - limit:
            requests: 100
            unit: Minute

이 설정은 세 단계로 Rate Limiting을 적용한다. 첫째, X-API-Key 헤더의 고유 값별로 시간당 1000건을 허용한다. 둘째, X-API-Tier가 premium인 요청은 시간당 10000건까지 허용한다. 셋째, 어떤 조건에도 해당하지 않는 요청은 분당 100건으로 제한한다.

글로벌 Rate Limiting은 별도의 Redis 기반 Rate Limit 서비스가 필요하다. Envoy Gateway를 Helm으로 설치할 때 rateLimit.backend.redis.host 값을 설정해야 한다.

# Envoy Gateway 설치 시 글로벌 Rate Limiting을 위한 Redis 설정
helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.6.3 \
  -n envoy-gateway-system --create-namespace \
  --set rateLimit.backend.redis.host=redis.infra.svc.cluster.local \
  --set rateLimit.backend.redis.port=6379

로컬 Rate Limiting은 Redis 없이 각 Envoy 인스턴스 자체에서 동작하므로 설정이 간단하지만, Pod 수에 따라 실제 허용량이 달라진다는 점을 고려해야 한다. Envoy Pod가 3개이고 로컬 한도가 분당 100건이면, 전체 클러스터 기준 최대 분당 300건이 허용될 수 있다.

Envoy Gateway 설치와 초기 설정

Helm 기반 설치

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

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

# GatewayClass 확인
kubectl get gatewayclass
# NAME            CONTROLLER                                      ACCEPTED
# eg              gateway.envoyproxy.io/gatewayclass-controller    True

# Gateway 생성 후 프록시 프로비저닝 확인
kubectl get gateway -n infra
kubectl get pods -n envoy-gateway-system

설치 후 GatewayClass의 ACCEPTED 상태가 True인지 반드시 확인한다. False인 경우 컨트롤러 Pod의 로그를 확인해야 한다.

supportedFeatures 확인

Gateway API v1.4부터 GatewayClass의 status에 supportedFeatures 필드가 추가되었다. 이를 통해 구현체가 어떤 기능을 지원하는지 프로그래밍적으로 확인할 수 있다.

# GatewayClass가 지원하는 기능 목록 확인
kubectl get gatewayclass eg -o jsonpath='{.status.supportedFeatures}' | jq .

이 결과에서 HTTPRouteRequestMirror, HTTPRouteBackendTimeout, GRPCRouteListenerHostnameMatching 등의 기능 지원 여부를 확인할 수 있어, 운영 환경에서 특정 기능을 사용하기 전에 호환성을 검증하는 데 유용하다.

트러블슈팅

Route가 Gateway에 연결되지 않는 경우

가장 흔한 문제는 HTTPRoute가 Gateway에 attach되지 않는 것이다. 다음 순서로 진단한다.

첫째, HTTPRoute의 parentRefs가 올바른 Gateway를 참조하는지 확인한다. namespace를 생략하면 같은 네임스페이스의 Gateway를 찾으므로, 다른 네임스페이스의 Gateway를 참조할 때는 반드시 namespace를 명시해야 한다.

둘째, Gateway의 allowedRoutes 설정을 확인한다. from: Selector를 사용하면 HTTPRoute가 있는 네임스페이스에 해당 레이블이 있어야 한다. 네임스페이스에 레이블을 추가하는 것을 잊는 경우가 많다.

# HTTPRoute 상태 확인
kubectl get httproute api-route -n app -o yaml | yq '.status'

# Gateway 리스너 상태 확인
kubectl get gateway production-gateway -n infra -o yaml | yq '.status.listeners'

# 네임스페이스 레이블 확인 및 추가
kubectl get ns app --show-labels
kubectl label ns app gateway-access=true

셋째, sectionName이 지정된 경우 Gateway 리스너 이름과 정확히 일치하는지 확인한다.

트래픽이 백엔드에 도달하지 않는 경우

Route가 정상적으로 attach되었는데도 502 또는 503 에러가 발생하면, 백엔드 서비스의 상태를 점검한다.

# 백엔드 서비스와 엔드포인트 확인
kubectl get svc api-service -n app
kubectl get endpoints api-service -n app

# Envoy 프록시 로그 확인
kubectl logs -n envoy-gateway-system -l app.kubernetes.io/component=proxy --tail=100

# Envoy 프록시 설정 덤프
kubectl port-forward -n envoy-gateway-system deploy/envoy-production-gateway 19000:19000 &
curl localhost:19000/config_dump | jq '.configs[] | select(.["@type"] | contains("route"))'

BackendTLSPolicy를 적용한 경우, 백엔드 Pod의 TLS 인증서가 올바르게 설정되었는지, hostname이 인증서의 SAN과 일치하는지 확인한다.

Rate Limiting이 동작하지 않는 경우

글로벌 Rate Limiting 미동작 시 체크리스트는 다음과 같다. Redis 연결 상태를 확인한다. Rate Limit 서비스 Pod가 정상 동작 중인지 확인한다. BackendTrafficPolicy의 targetRefs가 올바른 HTTPRoute를 참조하는지 확인한다.

# Rate Limit 서비스 상태 확인
kubectl get pods -n envoy-gateway-system -l app.kubernetes.io/component=ratelimit

# Rate Limit 서비스 로그
kubectl logs -n envoy-gateway-system -l app.kubernetes.io/component=ratelimit --tail=50

# Redis 연결 테스트
kubectl exec -n envoy-gateway-system deploy/envoy-ratelimit -- redis-cli -h redis.infra.svc.cluster.local ping

실패 사례와 복구 절차

사례 1: Gateway 업데이트 중 트래픽 중단

Gateway 리소스의 리스너를 변경하면 Envoy 프록시가 재시작될 수 있다. 프로덕션 환경에서 리스너를 추가/삭제할 때 무중단을 보장하려면 다음 절차를 따른다.

먼저 PodDisruptionBudget(PDB)을 설정하여 최소 가용 Pod 수를 보장한다. Envoy Gateway v1.6에서는 EnvoyProxy CRD를 통해 PDB를 직접 설정할 수 있다. 변경 전 Envoy 프록시의 replica 수를 충분히 확보한다(최소 2개 이상). 리스너 변경은 트래픽이 적은 시간대에 수행하고, 변경 직후 Gateway의 status.listeners를 모니터링하여 모든 리스너가 Accepted/Programmed 상태인지 확인한다.

사례 2: 잘못된 HTTPRoute 배포로 인한 라우팅 오류

HTTPRoute에 잘못된 backendRef를 지정하거나 weight를 0으로 설정하면 특정 경로의 트래픽이 드롭된다. 복구 절차는 다음과 같다.

# 문제가 있는 HTTPRoute 즉시 롤백
kubectl rollout undo httproute api-route -n app  # HTTPRoute는 rollout을 지원하지 않음

# 대신 이전 버전의 매니페스트를 다시 적용
kubectl apply -f httproute-previous-version.yaml

# 또는 GitOps 환경에서 git revert 후 자동 동기화
git revert HEAD
git push origin main

HTTPRoute는 Deployment처럼 rollout 기능이 없으므로, 반드시 GitOps(ArgoCD, Flux)를 통해 매니페스트를 버전 관리해야 한다. Git 히스토리가 곧 롤백 메커니즘이 된다.

사례 3: Rate Limit Redis 장애 시 트래픽 폭주

글로벌 Rate Limiting의 Redis가 다운되면, 기본적으로 Envoy는 Rate Limit 서비스에 연결할 수 없을 때 요청을 허용(fail-open)한다. 이는 가용성을 우선하는 설계이지만, 백엔드가 갑작스러운 트래픽 증가를 감당하지 못할 수 있다.

대응 방안으로, 글로벌 Rate Limiting과 로컬 Rate Limiting을 함께 적용한다. 로컬 Rate Limiting은 Redis에 의존하지 않으므로 Redis 장애 시에도 기본적인 트래픽 보호가 가능하다. Redis는 반드시 고가용성 구성(Redis Sentinel 또는 Redis Cluster)으로 배포한다.

운영 체크리스트

배포 전 체크리스트

• GatewayClass의 ACCEPTED 상태가 True인지 확인
• Gateway의 모든 리스너가 Accepted/Programmed 상태인지 확인
• HTTPRoute/GRPCRoute의 parentRef가 올바른 Gateway와 sectionName을 참조하는지 확인
• TLS 인증서의 만료일이 충분한지 확인 (cert-manager 사용 시 자동 갱신 설정 검증)
• BackendTLSPolicy의 hostname이 백엔드 인증서 SAN과 일치하는지 확인
• Rate Limiting 설정 시 Redis 연결 상태 확인
• Envoy 프록시의 HPA 설정이 예상 트래픽을 수용할 수 있는지 확인

모니터링 체크리스트

• Gateway 리소스의 status.conditions를 주기적으로 모니터링
• Envoy 프록시의 메트릭(요청 수, 지연 시간, 에러율)을 Prometheus/Grafana로 수집
• Rate Limit 히트 횟수를 모니터링하여 임계값 적정성 검증
• TLS 인증서 만료 알림 설정 (최소 14일 전)
• Envoy 프록시 Pod의 리소스 사용량(CPU, Memory) 모니터링

업그레이드 체크리스트

• Gateway API CRD 버전과 Envoy Gateway 버전의 호환성 매트릭스 확인
• CRD를 먼저 업그레이드한 후 컨트롤러를 업그레이드
• 업그레이드 전 기존 리소스의 백업 수행 (kubectl get gateway,httproute,grpcroute -A -o yaml)
• 스테이징 환경에서 먼저 업그레이드 검증
• 업그레이드 후 모든 Route의 attach 상태와 트래픽 정상 흐름 확인

Ingress에서 마이그레이션 체크리스트

• ingress2gateway 도구를 사용하여 기존 Ingress를 Gateway API 리소스로 변환
• 변환된 리소스를 수동 검토하여 어노테이션 기반 설정이 올바르게 매핑되었는지 확인
• Ingress와 Gateway API를 동시에 운영하면서 점진적으로 트래픽을 이전
• DNS 전환은 마지막 단계에서 수행하고, 이전 Ingress는 롤백용으로 최소 1주일 유지

# ingress2gateway 도구를 사용한 변환
go install github.com/kubernetes-sigs/ingress2gateway@latest
ingress2gateway print --providers ingress-nginx --all-namespaces

# 변환 결과를 파일로 저장 후 검토
ingress2gateway print --providers ingress-nginx --all-namespaces > gateway-resources.yaml

마무리

Gateway API는 2026년 현재 Kubernetes 네트워킹의 새로운 표준으로 확고히 자리잡았다. v1.4에서 BackendTLSPolicy, Named Rules, supportedFeatures가 Standard 채널로 승격되면서 운영 환경에서의 신뢰성이 크게 높아졌다. Envoy Gateway v1.6은 글로벌/로컬 Rate Limiting 동시 적용, SecurityPolicy의 TCPRoute 확장, mTLS 설정 등 엔터프라이즈 요구사항을 충족하는 기능을 갖추고 있다.

기존 Ingress에서 전환을 계획하고 있다면, ingress2gateway 도구를 활용한 점진적 마이그레이션을 권장한다. Gateway API와 기존 Ingress는 동일 클러스터에서 공존할 수 있으므로, 서비스 단위로 안전하게 전환할 수 있다. 가장 중요한 것은 GitOps를 통한 매니페스트 버전 관리와, 충분한 모니터링/알림 체계를 구축하는 것이다.

참고자료

• Gateway API 공식 문서
• Gateway API v1.4 릴리스 블로그
• Envoy Gateway 공식 문서
• Envoy Gateway v1.6.0 릴리스 노트
• Envoy Gateway Rate Limiting 가이드
• Ingress에서 Gateway API로 마이그레이션 가이드
• Envoy Gateway 1.3 릴리스 하이라이트 (Tetrate)
• NGINX Ingress에서 Envoy Gateway로 마이그레이션 사례 (Qovery)
• Gateway API 구현체 목록