제 이전 포스트들을 통해 NGINX 인그레스(Ingress)의 은퇴 소식을 접해오셨다면 지금까지의 이야기를 잘 알고 계실 겁니다. 커뮤니티의 Ingress NGINX 프로젝트는 2026년 3월에 종료되었으며, Microsoft의 NGINX 기반 App Routing 애드온에 대한 확장 지원은 2026년 11월까지 유지됩니다. 저는 그동안 시간을 벌기 위해 독립형 NGINX에서 AKS App Routing 애드온으로 원활하게 마이그레이션하는 방법과, 장기적인 대안으로 Application Gateway for Containers로 마이그레이션하는 방법을 다루었습니다. 두 포스트 모두에서 Microsoft가 Istio와 Gateway API를 기반으로 한 새로운 버전의 App Routing 애드온을 준비 중이라고 언급했었는데요, 드디어 프리뷰(Preview) 버전으로 공개되었습니다.
이번에 공개된 App Routing Gateway API 구현체는 현재 NGINX 기반 App Routing 애드온을 사용하는 모든 사용자에게 Microsoft가 권장하는 마이그레이션 경로입니다. 이 방식은 NGINX에서 완전히 벗어나 Kubernetes Gateway API로 전환하며, 내부적으로는 경량화된 Istio 컨트롤 플레인이 게이트웨이 인프라를 관리합니다. 이것이 정확히 무엇인지, 다른 옵션들과 어떻게 다른지, 그리고 기존 NGINX 및 App Routing 애드온에서 어떻게 마이그레이션하는지 살펴보겠습니다.
이것은 무엇인가요?
새로운 App Routing 모드는 Ingress API 대신 Kubernetes Gateway API를 사용합니다. 이 애드온을 활성화하면 AKS는 Envoy 기반 게이트웨이 프록시를 관리하기 위해 Istio 컨트롤 플레인(istiod)을 배포합니다. 여기서 중요한 점은 이것이 전체(Full) Istio 서비스 메시가 아니라는 것입니다. 사이드카 주입(Sidecar injection)도 없고, 워크로드를 위한 Istio CRD도 설치되지 않습니다. Istio는 오직 인그레스 트래픽을 위한 게이트웨이 프록시를 관리하는 특정 역할만 수행합니다.
Gateway 리소스를 생성하면 AKS는 Envoy 디플로이먼트(Deployment), LoadBalancer 서비스, HPA(HorizontalPodAutoscaler, 기본적으로 80% CPU에서 2~5개 복제본), 그리고 PDB(PodDisruptionBudget)를 프로비저닝합니다. 이 모든 것이 관리형으로 제공됩니다. 사용자는 Gateway와 HTTPRoute 리소스만 작성하면 되며, 나머지는 AKS가 모두 처리합니다.
이는 기존의 Ingress API와는 근본적으로 다른 구조입니다. 진입점과 라우팅 규칙을 하나의 Ingress 리소스에 결합하는 대신, Gateway API는 이를 여러 계층으로 나눕니다.
- GatewayClass: 게이트웨이 인프라의 유형을 정의합니다 (이 경우 AKS가 제공).
- Gateway: 리스너를 포함한 실제 게이트웨이 인스턴스를 생성합니다.
- HTTPRoute: 라우팅 규칙을 정의하고 특정 Gateway에 연결합니다.
이러한 분리는 Gateway API의 주요 장점 중 하나입니다. 플랫폼 팀은 Gateway 리소스를 관리하고, 애플리케이션 팀은 공용 인프라를 건드리지 않고도 자신들의 HTTPRoute를 독립적으로 관리할 수 있습니다. 누군가 공유된 Ingress를 수정하다가 실수로 모든 팀의 라우팅을 망가뜨린 경험이 있다면, 왜 이 구조가 중요한지 공감하실 겁니다.
Istio 서비스 메시 애드온과는 어떻게 다른가요?
이미 AKS에서 Istio 서비스 메시 애드온을 사용 중이거나 고려하고 계신다면, 이번 App Routing은 그것과는 별개의 기능임을 알아야 합니다.
App Routing Gateway API 모드는 approuting-istio GatewayClass를 사용하며, Istio CRD를 설치하지 않고, 사이드카 주입을 활성화하지 않으며, 업데이트를 인플레이스(in-place) 방식으로 처리합니다. 반면, 전체 Istio 서비스 메시 애드온은 istio GatewayClass를 사용하고, 클러스터 전체에 Istio CRD를 설치하며, 사이드카 주입을 지원하고, 부 버전(minor version) 업그레이드 시 카나리(Canary) 방식을 사용합니다.
두 기능은 동시에 실행될 수 없습니다. Istio 서비스 메시 애드온이 활성화되어 있다면 App Routing Gateway API를 활성화하기 전에 이를 비활성화해야 합니다(반대도 마찬가지입니다). 서비스 간 mTLS, 트래픽 정책, 텔레메트리 같은 전체 메시 기능이 필요하다면 Istio 서비스 메시 애드온을 그대로 사용하세요. 메시의 오버헤드 없이 Gateway API를 통한 관리형 인그레스만 필요하다면 이번 App Routing이 올바른 선택입니다.
현재 한계점
새로운 App Routing 솔루션은 현재 프리뷰 단계이므로 아직 운영 환경에서 실행해서는 안 됩니다. 또한 기존 애드온과 비교했을 때 몇 가지 차이점이 있으므로 마이그레이션 계획 시 주의가 필요합니다.
가장 큰 차이점은 Gateway API의 경우 DNS 및 TLS 인증서 관리 자동화가 아직 지원되지 않는다는 점입니다. 현재 NGINX 기반 애드온에서 az aks approuting update 및 az aks approuting zone add를 사용하여 Key Vault 및 Azure DNS 통합을 자동화하고 있었다면, 이 워크플로우는 그대로 이어지지 않습니다. TLS 터미네이션은 여전히 가능하지만 수동으로 설정해야 합니다. AKS 문서에서 단계를 설명하고 있지만, 현재의 NGINX 애드온보다는 손이 더 많이 갑니다. 이 기능은 정식 출시(GA) 시점에 해결될 것으로 예상됩니다.
SNI 패스스루(TLSRoute) 및 이그레스(Egress) 트래픽 관리도 지원되지 않습니다. 그리고 앞서 언급했듯이 Istio 서비스 메시 애드온과는 상호 배타적입니다.
자동화된 DNS 및 TLS 관리에 크게 의존하는 운영 워크로드라면 GA를 기다리거나, 대안으로 Application Gateway for Containers를 살펴보는 것이 좋습니다. 하지만 수동 TLS 설정을 감당할 수 있는 팀이나 비운영 환경에서는 지금 바로 테스트를 시작하지 않을 이유가 없습니다.
시작하기
기능을 활성화하기 전에 aks-preview CLI 확장(버전 19.0.0b24 이상)이 필요하며, 관리형 Gateway API CRD 및 App Routing Gateway API 프리뷰 기능 플래그를 등록해야 합니다.
az extension add --name aks-preview
az extension update --name aks-preview
# 관리형 Gateway API CRDs (필수 의존성)
az feature register --namespace "Microsoft.ContainerService" --name "ManagedGatewayAPIPreview"
# App Routing Gateway API 구현체
az feature register --namespace "Microsoft.ContainerService" --name "AppRoutingIstioGatewayAPIPreview"
기능 플래그 등록에는 몇 분 정도 소요될 수 있습니다. 등록이 완료되면 새 클러스터나 기존 클러스터에 애드온을 활성화합니다. --enable-gateway-api(관리형 Gateway API CRD 설치용)와 --enable-app-routing-istio(Istio 기반 구현체용)가 모두 필요합니다.
# 새 클러스터 생성 시
az aks create \
--resource-group ${RESOURCE_GROUP} \
--name ${CLUSTER} \
--location swedencentral \
--enable-gateway-api \
--enable-app-routing-istio
# 기존 클러스터 업데이트 시
az aks update \
--resource-group ${RESOURCE_GROUP} \
--name ${CLUSTER} \
--enable-gateway-api \
--enable-app-routing-istio
istiod가 실행 중인지 확인합니다.
kubectl get pods -n aks-istio-system
두 개의 istiod 포드가 Running 상태여야 합니다.
(참고: 원문 이미지 위치)
여기서부터 Gateway와 HTTPRoute를 생성하여 트래픽 흐름을 테스트할 수 있습니다. 빠른 검증을 원하신다면 httpbin 샘플 앱을 사용하는 AKS 퀵스타트 가이드를 따라가 보세요.
NGINX 인그레스에서 마이그레이션하기
독립형 NGINX(Helm 설치)를 사용하든 NGINX 기반 App Routing 애드온을 사용하든 마이그레이션 프로세스는 기본적으로 동일합니다. Ingress API 리소스를 Gateway API 리소스로 옮기는 과정이며, 전환 기간 동안 기존 컨트롤러와 새 컨트롤러가 나란히 실행됩니다. 유일한 차이점은 마지막에 정리해야 할 리소스와, App Routing 애드온 사용자라면 기존의 DNS/TLS 자동화에 의존하고 있었는지 여부입니다.
1. 인그레스 리소스 파악하기
가장 먼저 현재 무엇을 사용 중인지 파악하세요.
kubectl get ingress --all-namespaces \
-o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.ingressClassName'
특히 커스텀 스니펫(snippets), Lua 설정 등 NGINX 전용 동작에 크게 의존하는 부분이 있는지 확인하세요. 이러한 설정은 Gateway API에 직접적인 대응 기능이 없을 수 있으므로 수동 확인이 필요합니다.
2. 인그레스 리소스를 Gateway API로 변환하기
ingress2gateway 툴(v1.0.0)은 Ingress 리소스를 Gateway API 리소스로 변환하는 것을 도와줍니다. 이 툴은 30개 이상의 일반적인 NGINX 어노테이션을 지원하며 Gateway 및 HTTPRoute YAML을 생성합니다.
# 설치
go install github.com/kubernetes-sigs/[email protected]
# 라이브 클러스터에서 변환
ingress2gateway print --providers=ingress-nginx -A > gateway-resources.yaml
# 또는 로컬 파일에서 변환
ingress2gateway print --providers=ingress-nginx --input-file=./manifests/ingress.yaml > gateway-resources.yaml
출력된 결과물을 꼼꼼히 검토하세요. 툴이 변환할 수 없는 어노테이션은 생성된 YAML에 주석으로 표시하므로 어떤 부분을 수동으로 작업해야 하는지 알 수 있습니다. 일반적인 차이점으로는 커스텀 설정 스니펫이나 Gateway API의 라우팅 모델에 깔끔하게 매핑되지 않는 정규식 기반 리라이트(rewrite) 등이 있습니다.
생성된 Gateway 리소스의 gatewayClassName이 approuting-istio로 설정되어 있는지 반드시 확인하세요.
3. DNS 및 TLS 처리
독립형 NGINX를 사용해왔다면 이미 DNS와 TLS를 직접 관리하고 있을 것이므로 크게 바뀔 것은 없습니다. 새 게이트웨이 IP에 맞게 인증서 Secret과 DNS 레코드를 준비하세요.
만약 App Routing 애드온의 자동화(Key Vault 통합 등)를 사용 중이었다면 이 부분이 고민이 될 것입니다. 해당 자동화는 아직 Gateway API 구현체에서 지원되지 않으므로 GA 전까지는 다른 방식을 찾아야 합니다.
TLS의 경우 Kubernetes Secret을 수동으로 생성하거나 Key Vault에서 동기화하는 워크플로우를 설정할 수 있습니다. Gateway API 트래픽 보안에 관한 AKS 문서를 참고하세요. DNS의 경우 레코드를 직접 관리하거나 자동화를 위해 ExternalDNS를 사용할 수 있습니다. ExternalDNS는 Gateway API 리소스를 지원하므로 좋은 대안이 될 수 있습니다.
4. 배포 및 검증
애드온이 활성화된 상태에서 변환된 리소스를 적용합니다.
kubectl apply -f gateway-resources.yaml
게이트웨이가 구성되어 외부 IP를 할당받을 때까지 기다립니다.
kubectl wait --for=condition=programmed gateways.gateway.networking.k8s.io <gateway-name>
export GATEWAY_IP=$(kubectl get gateways.gateway.networking.k8s.io <gateway-name> -ojsonpath='{.status.addresses[0].value}')
여기서 핵심은 기존 NGINX 컨트롤러가 여전히 실행 중이며 운영 트래픽을 처리하고 있다는 점입니다. Gateway API 리소스는 aks-istio-system 네임스페이스의 Istio 기반 컨트롤러에 의해 별도로 처리됩니다. 이 병렬 실행 덕분에 안전한 마이그레이션이 가능합니다.
새 게이트웨이 IP를 대상으로 라우팅을 테스트하세요. DNS는 여전히 이전 시스템을 가리키고 있을 것이므로 Host 헤더를 직접 지정해야 합니다.
curl -H "Host: myapp.example.com" http://$GATEWAY_IP
전체 검증 세트를 실행하세요. TLS, 경로 라우팅, 헤더, 인증 등 애플리케이션이 의존하는 모든 요소를 확인하세요. DNS를 업데이트하기 전까지는 운영 환경에 변화가 없으므로 충분한 시간을 갖고 테스트하세요.
5. DNS 전환 및 정리
준비가 되었다면 DNS TTL을 60초로 낮추고(사전에 진행), DNS 레코드가 새 게이트웨이 IP를 가리키도록 업데이트합니다. 롤백 가능성을 위해 기존 NGINX 컨트롤러를 24~48시간 동안 계속 실행해 두세요.
트래픽이 Gateway API 경로를 통해 정상적으로 흐르는 것을 확인한 후, 이전 설정을 정리합니다.
독립형 NGINX를 사용했던 경우:
helm uninstall ingress-nginx -n ingress-nginx
kubectl delete namespace ingress-nginx
NGINX 기반 App Routing 애드온을 사용했던 경우:
기존 webapprouting IngressClass를 사용하는 리소스가 없는지 확인한 후 애드온을 비활성화합니다.
az aks approuting disable --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}
비활성화 후에도 app-routing-system 네임스페이스에 일부 리소스가 남을 수 있습니다. 모든 것이 정상임을 확인한 후 네임스페이스를 삭제하여 정리하세요.
kubectl delete ns app-routing-system
업그레이드 및 수명 주기
Istio 컨트롤 플레인 버전은 AKS 클러스터의 Kubernetes 버전과 연결됩니다. AKS는 릴리스 주기에 따라 패치 업그레이드를 자동으로 처리하며, 부 버전 업그레이드는 클러스터 업그레이드 시 또는 해당 AKS 버전에 새 Istio 버전이 출시될 때 인플레이스로 이루어집니다.
Istio 서비스 메시 애드온과 달리 여기서는 업그레이드가 카나리 방식이 아닌 인플레이스 방식이라는 점을 유의하세요. 각 게이트웨이의 HPA와 PDB가 중단을 최소화해주겠지만, 운영 환경에서는 이에 맞춰 계획을 세워야 합니다. 유지 관리 기간(Maintenance windows)이 설정되어 있다면 istiod 업그레이드는 해당 시간을 준수합니다.
지금 무엇을 해야 할까요?
일정은 변하지 않았습니다. 커뮤니티의 독립형 NGINX 인그레스 프로젝트는 2026년 3월에 종료되었으므로, 이를 계속 사용 중이라면 이미 기술 지원이 종료된 소프트웨어를 실행하고 있는 셈입니다. NGINX App Routing 애드온은 2026년 11월까지 지원되므로 시간이 조금 더 있지만, 그리 넉넉하지는 않습니다.
- 독립형 NGINX 사용 시: 시간을 벌기 위해 지금 바로 App Routing 애드온으로 옮겨간 후, Gateway API 모드나 AGC로의 마이그레이션을 계획하세요.
- NGINX App Routing 애드온 사용 시: 지금 바로 비운영 환경에서 Gateway API 모드를 테스트하기 시작하세요. 리소스 모델에 익숙해지고, 프리뷰 단계의 TLS/DNS 제약을 파악한 뒤 GA가 되거나 11월이 다가오기 전에 마이그레이션할 준비를 마쳐야 합니다.
- 즉시 운영 가능한 자동화가 필요한 경우: GA를 기다릴 수 없고 지금 당장 운영 수준의 TLS/DNS 자동화가 필요하다면, 현재로서는 Application Gateway for Containers가 최선의 선택입니다.
어떤 경로를 선택하든 11월이 오기 전에 계획을 세우세요. 운영 인프라에서 지원이 종료된 인그레스 소프트웨어를 실행하는 것은 결코 바람직한 상황이 아닙니다.