Migration Execution Strategy

📅Published 2026-02-14·🔄Updated 2026-06-26·⏱4 min read

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.

---

Related Documents

• Gateway API Adoption Guide
• Cilium ENI Mode + Gateway API
• Gateway API Official Documentation