ddd2
2026. 5. 31. 16:16ㆍ카테고리 없음
[사내 위키] Ingress에서 Gateway API로의 마이그레이션 가이드
기존 Ingress 리소스를 Gateway API(Gateway 및 HTTPRoute)로 안전하게 변환하고 검증하기 위한 절차입니다.
1. 사전 준비 단계 (Prerequisites)
- CRD 설치 및 컨트롤러 확인
- Gateway API는 쿠버네티스 기본 내장 리소스가 아니므로 표준 CRD(Custom Resource Definition)를 먼저 클러스터에 설치해야 합니다.
- 사내에서 사용 중인 인프라/서비스 매시 컨트롤러(예: Istio, NGINX Ingress Controller, Envoy Gateway 등)가 Gateway API 정식 버전(v1)을 지원하는지 버전을 확인합니다.
- 역할 분담 정의 (RBAC)
- 인프라/클러스터 관리자: GatewayClass 및 Gateway 리소스 생성 권한 할당.
- 애플리케이션 개발 팀: 본인 네임스페이스 내 HTTPRoute 리소스 생성 권한 할당.
2. 리소스 매핑 구조 이해
변환 전후의 리소스 구조는 다음과 같이 1:N 관계로 매핑됩니다. 기존 인그레스 파일 하나에 있던 내용이 역할에 따라 쪼개지게 됩니다.
- 기존 Ingress의 글로벌 설정 (TLS 인증서, 공용 도메인, 진입 포트) $\rightarrow$ Gateway로 이동
- 기존 Ingress의 라우팅 규칙 (Path 매칭, 백엔드 서비스 연결) $\rightarrow$ HTTPRoute로 이동
3. 3단계 변환 프로세스 (실전 예시)
기존에 사용하던 Standard Ingress 배포 본을 Gateway API로 변환하는 구체적인 예시입니다.
[기존] Ingress 매니페스트
YAML
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-app-ingress
namespace: target-space
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /$2 # 기존 어노테이션 기반 리라이트
spec:
ingressClassName: nginx
tls:
- hosts:
- api.example.com
secretName: example-tls-secret
rules:
- host: api.example.com
http:
paths:
- path: /v1(/|$)(.*)
pathType: ImplementationSpecific
backend:
service:
name: core-service
port:
number: 8080
[변환 후] 1단계: Gateway 리소스 생성 (관리자 영역)
클러스터에 들어오는 진입점과 TLS 인증서를 정의합니다. (인프라 네임스페이스 등에 단 한 번만 생성하여 공유 가능)
YAML
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: cluster-gateway
namespace: infra-system # 인프라 공용 네임스페이스
spec:
gatewayClassName: nginx # 사내 인그레스 클래스 지정
listeners:
- name: https-listener
protocol: HTTPS
port: 443
hostname: "api.example.com"
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: example-tls-secret
namespace: infra-system
allowedRoutes:
namespaces:
from: All # 모든 네임스페이스의 Route 연결 허용 (보안 필요시 Select 가능)
[변환 후] 2단계: HTTPRoute 리소스 생성 (개발 팀 영역)
실제 서비스 경로와 라우팅 규칙을 정의합니다. 기존 어노테이션(rewrite-target)으로 처리하던 복잡한 로직이 표준 필터(Filters) 기능으로 대체됩니다.
YAML
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: core-service-route
namespace: target-space # 애플리케이션이 속한 네임스페이스
spec:
parentRefs:
- name: cluster-gateway
namespace: infra-system # 1단계에서 만든 Gateway 참조
hostnames:
- "api.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /v1
filters:
- type: URLRewrite # 기존의 복잡한 정규식 어노테이션 대신 표준 필터 사용
urlRewrite:
path:
type: ReplacePrefixMatch
replacePrefixMatch: /
backendRefs:
- name: core-service
port: 8080
4. 자동 변환 툴 활용 권장 (ingress2gateway)
수동 변환 외에도 쿠버네티스 공식 서브 프로젝트에서 제공하는 ingress2gateway 오픈소스 CLI 도구를 사용하면 기존 인그레스 파일을 Gateway API 자원으로 자동 변환할 수 있습니다.
- 설치 및 사용법:
-
Bash
# 툴 설치 (Go 환경 필요 또는 바이너리 다운로드) go install sigs.k8s.io/ingress2gateway@latest # 기존 인그레스 파일을 기반으로 Gateway API 파일 리소스 출력 ingress2gateway translate --input-file=my-app-ingress.yaml - 주의: 기본적인 라우팅은 완벽히 변환되지만, 특정 벤더에 종속된 특이한 인그레스 어노테이션(Annotation)은 완벽히 변환되지 않을 수 있으므로 변환 후 수동 검증이 필요합니다.
5. 중단 없는 전환 시나리오 (Zero-Downtime Migration)
운영 중인 서비스의 트래픽 중단을 방지하기 위해 아래 순서로 DNS 및 라우팅을 점진적으로 전환합니다.
- 듀얼 인프라 구성: 기존 Ingress Controller와 신규 Gateway API Controller를 클러스터 내에 동시에 띄워둡니다.
- Gateway 리소스 배포: 위 가이드에 따라 Gateway와 HTTPRoute를 먼저 생성합니다. (이 시점에는 외부 트래픽이 아직 들어오지 않음)
- 내부 검증: 라우팅이 정상 작동하는지 kubectl get httproute로 상태(Ready: True)를 확인하고, 내부 포트포워딩이나 별도 테스트 도메인을 통해 Gateway 단으로 요청이 정상 전달되는지 확인합니다.
- 가중치 기반 DNS 전환: 외부 DNS(Route 53 등)의 가중치 라우팅 기능을 활용하여, 기존 Ingress 로드밸런서 IP에서 신규 Gateway 로드밸런서 IP로 트래픽을 점진적으로 전환합니다 ($10\% \rightarrow 50\% \rightarrow 100\%$).
- 기존 리소스 정리: 완벽히 안정이 확인되면 기존 Ingress 리소스를 삭제합니다.