Skip to main content

Migration Execution Strategy

info

This document is a deep-dive guide for the Gateway API Adoption Guide. It provides a practical migration strategy from NGINX Ingress to Gateway API.

1. Prerequisites: CRD Installation​

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

# Experimental features (optional)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/experimental-install.yaml

Controller-specific installation: AWS LBC v3 (Helm with enableGatewayAPI=true), NGINX Gateway Fabric, Envoy Gateway, Cilium (already enabled with gatewayAPI.enabled=true).

2. 5-Phase Migration Process​

3. Phase-by-Phase Detail​

Phase 1: Preparation — Inventory collection, feature mapping, risk assessment Phase 2: Build — CRD installation, controller deployment, PoC in test environment Phase 3: Parallel Operation — Production Gateway + HTTPRoute creation alongside existing NGINX Ingress Phase 4: Switchover — DNS weighted routing: 10% → 50% → 100% Phase 5: Completion — NGINX Ingress backup, resource removal, documentation

🔄 NGINX Ingress → Gateway API 마이그레이션 매핑
기존 Ingress 기능의 Gateway API 대안
host: example.com→HTTPRoute.spec.hostnames
직접 매핑직접 매핑
path: /api→HTTPRoute.spec.rules[].matches[].path
직접 매핑직접 매핑
pathType: Prefix→path.type: PathPrefix
동일동일
annotations: rewrite-target→filters[].type: URLRewrite
표준화됨표준화됨
annotations: rate-limit→Policy Attachment (구현체별 상이)
진행 중표준화 진행 중
annotations: cors-*→Policy Attachment
진행 중표준화 진행 중
annotations: auth-*→Policy Attachment 또는 외부 인증
외부OAuth2-Proxy 등 권장
annotations: ssl-redirect→Gateway TLS 리스너 자동 처리
자동화됨자동화됨

4. Validation Script​

Validation script checks: HTTPRoute existence, Accepted/Programmed conditions, backend service endpoints, Gateway address, and HTTP request test.

5. Troubleshooting​

🔧 Gateway API 트러블슈팅 가이드
일반적인 문제와 해결 방법
❌ HTTPRoute Accepted=False
원인: Gateway가 HTTPRoute를 거부함
해결: 1. ReferenceGrant 확인 2. GatewayClass 올바른지 확인 3. 네임스페이스 정책 확인
❌ HTTPRoute Programmed=False
원인: 데이터플레인 구성 실패
해결: 1. 백엔드 Service 존재 확인 2. 컨트롤러 로그 확인 3. TLS Secret 유효성 확인
❌ 503 Service Unavailable
원인: 백엔드 엔드포인트 없음
해결: 1. Service의 Endpoints 확인 2. Pod selector 일치 여부 확인 3. Pod 상태 확인 (Ready)
❌ TLS 인증서 오류
원인: Secret이 올바르지 않음
해결: 1. Secret 타입 kubernetes.io/tls 확인 2. tls.crt, tls.key 존재 확인 3. 인증서 유효기간 확인
❌ 404 Not Found
원인: 경로 매칭 실패
해결: 1. PathPrefix vs Exact 타입 확인 2. 대소문자 구분 여부 확인 3. URL 인코딩 확인
❌ Gateway 주소 없음
원인: LoadBalancer 생성 실패
해결: 1. 클라우드 제공자 쿼터 확인 2. 서브넷 IP 고갈 여부 확인 3. 어노테이션 오타 확인

Controller-specific debugging commands provided for: AWS Load Balancer Controller, Cilium Gateway API, NGINX Gateway Fabric, and Envoy Gateway.