NGINX Ingress에서 마이그레이션하기

Calico Ingress Gateway는 Envoy Gateway로 구동되며, Kubernetes 클러스터에서 NGINX Ingress를 대체하는 컴포넌트예요. NGINX Ingress Controller는 2026년 3월에 은퇴했고, 이제 릴리스, 버그 수정, 보안 패치가 더 이상 제공되지 않아요. 이 문서에서는 NGINX Ingress에서 Calico Ingress Gateway로 개념을 어떻게 옮기는지, 단계별 마이그레이션 절차, 그리고 주의해야 할 흔한 문제를 다뤄요.

출처: 문서

본문

이 문서는 NGINX Ingress에서 Calico Ingress Gateway로 가는 개념적 매핑과 단계별 마이그레이션 절차, 주의할 흔한 문제를 다뤄요.

SUCCESS: Gateway API가 NGINX Ingress와 어떻게 다른지 이미 이해하고 있다면 바로 마이그레이션 절차로 넘어가도 돼요. 편의를 위해 선택적인 변환 도구도 제공하고 있어요.

왜 Gateway API인가

NGINX Ingress는 Ingress 객체에 벤더별 어노테이션 문자열로 동작을 담아요. Gateway API는 같은 동작을 타입이 지정된 CRD에 담아서, 규격을 준수하는 어느 컨트롤러(Envoy Gateway, Istio, Cilium, kgateway 등)라도 읽을 수 있게 해요. 마음가짐의 전환은 이렇습니다:

마이그레이션 절차

1단계: 인벤토리 만들기

모든 Ingress 리소스와 그것이 사용하는 어노테이션을 목록화하세요. 어노테이션 접두사를 메모해 두세요(커뮤니티 NGINX는 nginx.ingress.kubernetes.io/를, NGINX Inc / F5는 nginx.org/와 nginx.com/을 사용해요):

kubectl get ingress -A -o yaml

2단계: 리소스 백업하기

무엇이든 바꾸기 전에 현재 Ingress, Service, TLS Secret 상태를 파일로 내보내세요:

kubectl get ingress,service,secret -A -o yaml > pre-migration.yaml

3단계: Gateway API 리소스 작성하기

Ingress 리소스를 Gateway, HTTPRoute, ReferenceGrant, 그리고 필요한 SecurityPolicy, BackendTrafficPolicy, ClientTrafficPolicy 리소스로 옮겨 적으세요. 생성된 각 리소스를 원래 Ingress와 비교해 보세요.

INFO: 기존 Ingress YAML 파일에서 Gateway API 리소스를 생성하도록 돕는 변환 도구를 제공하고 있어요.

4단계: 리소스 검증하기

3단계에서 작성한 리소스에 대해 egctl experimental translate를 실행하면, 클러스터에 적용하기 전에 스키마나 의미 오류를 미리 잡아낼 수 있어요:

egctl experimental translate --type gateway-api --file gateway-api.yaml --output yaml

gateway-api.yaml은 여러분이 작성(또는 생성)한 Gateway API 매니페스트 경로로 바꿔 주세요.

5단계: 비프로덕션 클러스터에 적용하고 테스트하기

Calico Ingress Gateway가 돌아가는 비프로덕션 클러스터에 적용하세요. 다음 항목을 점검해요:

• TLS — 인증서 체인, SNI 선택, HTTPS 리다이렉트, HSTS
• 인증(Auth) — 유효한 자격 증명/토큰과 무효한 자격 증명/토큰으로 보호된 모든 라우트
• 레이트 리밋 — 임계값이 기대한 동작과 일치하는지 확인 (참고: NGINX는 leaky bucket, Envoy는 token bucket을 사용해요 — 같은 숫자라도 버스트 의미론이 달라요)
• 타임아웃과 재시도 — 의도적으로 업스트림을 느리게 하거나 실패시킨 상태에서 확인
• 세션 어피니티 — 같은 클라이언트의 반복 요청이 같은 백엔드로 가는지
• CORS — 보호되는 모든 오리진에서 preflight 응답이 NGINX 동작과 일치하는지

6단계: 프로덕션에서 병행 운영하기

기존 NGINX Ingress 컨트롤러와 함께 Calico Ingress Gateway를 배포하세요. 다음 중 하나로 트래픽을 점진적으로 옮겨요:

• 두 LoadBalancer 주소 사이의 DNS 가중치
• 양쪽 앞에서 헤더 기반 또는 쿼리 파라미터 기반 라우팅
• 엣지 로드 밸런서에서의 퍼센트 카나리

대표적인 부하에서 동등성(parity)이 증명될 때까지 NGINX를 살려 두고 트래픽을 계속 서빙하세요. 이것이 롤백 경로이기도 해요: Calico Ingress Gateway가 오동작하면 DNS 변경이나 퍼센트 조정을 되돌려서 트래픽을 NGINX로 다시 옮기면 돼요.

7단계: NGINX 제거하기

동등성이 증명되고 트래픽이 전부 Calico Ingress Gateway로 넘어갔다면, NGINX Ingress 컨트롤러를 은퇴시키고 Ingress 리소스를 삭제하세요.

흔한 문제

• 스니펫 어노테이션이 조용히 사라짐. ingress-nginx 1.15+는 configuration-snippet이나 server-snippet에 SSL 변수가 담긴 Ingress를 조용히 버려요. 전환 후 "사라진" 라우트가 많이 보인다면 스니펫에 의존했는지 확인해 보세요.
• 어노테이션 접두사 감지. 변환기는 nginx.ingress.kubernetes.io/와 nginx.org//nginx.com/을 자동으로 구분해요. 대량 변환 전에 대표 샘플로 이중 확인하세요.
• Envoy Gateway 버전 차이. 일부 필드(예: SecurityPolicy.spec.tls와 ClientTrafficPolicy.spec.tls)는 EG 릴리스 사이에서 이동했어요. Calico Ingress Gateway는 현재 EG 1.5.x를 탑재해요. 생성된 YAML을 EG 문서가 아니라 클러스터에 실제 배포된 버전 기준으로 검증하세요.
• 레이트 리밋 의미론이 다름. NGINX는 leaky bucket, Envoy는 token bucket을 써요. 같은 숫자 제한도 버스트 트래픽에서는 다르게 동작해요.
• ReferenceGrant는 선택 사항이 아니에요. 크로스 네임스페이스 참조(HTTPRoute → Service, Gateway → TLS Secret)에는 명시적인 ReferenceGrant가 필요해요. 변환기가 이를 생성해 주지만, 출력을 손으로 고치다가 하나를 빠뜨리면 라우팅이 조용히 깨질 수 있어요.

변환 도구

변환 도구는 기존 Ingress YAML 파일로부터 Gateway API 리소스 초안을 만들어 줘요. 입력 창에 Ingress 객체를 하나 이상 붙여 넣으면 도구가 다음을 돌려줘요:

• 지원되는 NGINX 어노테이션에 대해 Gateway, HTTPRoute, ReferenceGrant, 그리고 필요한 SecurityPolicy, BackendTrafficPolicy, ClientTrafficPolicy 리소스를 담은 멀티 문서 YAML
• 무엇이 변환됐고 무엇이 건너뛰어졌는지, 지원되지 않는 어노테이션과 Envoy 관점의 우회 방법을 설명하는 마크다운 형식의 마이그레이션 플레이북

도구는 어노테이션 접두사(커뮤니티 NGINX vs NGINX Inc / F5)를 자동으로 감지하고 두 컨트롤러를 모두 지원해요. 모든 처리는 브라우저에서 일어나요 — 어떤 YAML도 여러분의 머신을 떠나지 않아요. 전체 어노테이션 레퍼런스(어떤 어노테이션이 깔끔하게 변환되고 어떤 것이 사람의 판단이 필요한지)는 도구 사이트에 정리되어 있어요.

WARNING: 출력 결과는 완성된 마이그레이션이 아니라 시작점 초안이에요.

생성된 모든 리소스는 검토하고, egctl로 검증하고, 비프로덕션 클러스터에서 테스트하고, 프로덕션 트래픽을 전환하기 전에 기존 NGINX 구성과의 동등성을 증명해야 해요. 도구는 엣지 케이스에서 잘못되거나 불완전한 출력을 낼 수 있으니 — 각 리소스를 라이브 구성과 대조하고, 대표적인 트래픽으로 직접 확인한 뒤 프로덕션에 올리세요.

도움이 필요하신가요?

커뮤니티 도움은 Calico Users Slack에서 물어보세요. 복잡한 마이그레이션(수백 개의 Ingress 리소스, 커스텀 NGINX 스니펫, mTLS, NGINX Plus 기능)이라면 Tigera 엔지니어와 상담하세요.

더 알아보기 (Learn more)

핵심은 어노테이션 문자열에서 타입 지정 CRD로의 이동이에요. 병행 운영 단계에서 동등성을 증명해 두면 롤백 경로가 항상 열려 있어 안심할 수 있어요. 스니펫 어노테이션과 ReferenceGrant만큼은 전환 전 반드시 확인하세요.