.svg)
%201.svg)
%201.svg){kind=icon}
담당자가 프로모션 코드를 발송해 드립니다.
와탭을 경험해 보세요.
와탭을 경험해 보세요.
와탭을 경험해 보세요.
와탭을 경험해 보세요.
와탭을 경험해 보세요.
와탭을 경험해 보세요.
와탭을 경험해 보세요.
와탭을 경험해 보세요.
WhaTap AI를 경험해 보세요.
Ingress-Nginx 모니터링, 일반 Nginx와 다른 이유
쿠버네티스 환경에서 외부 트래픽을 클러스터 내부로 라우팅할 때 가장 많이 쓰이는 컴포넌트가 Ingress-Nginx Controller입니다. CNCF 생태계에서 사실상 표준 인그레스 솔루션으로 자리잡았고, 수많은 프로덕션 클러스터에서 트래픽의 첫 관문 역할을 하고 있습니다.
다만 한 가지 짚고 갈 점이 있습니다. Kubernetes SIG Network와 Security Response Committee의 2025년 11월 공식 발표에 따라, 커뮤니티 ingress-nginx 프로젝트는 2026년 3월부로 유지보수가 종료되어 신규 기능·버그픽스·보안 패치를 더 이상 받지 않습니다. 업스트림은 Gateway API로의 전환을 권장합니다. 그러나 이미 수많은 프로덕션 클러스터가 ingress-nginx 위에서 돌아가고 있고, 마이그레이션에는 상당한 시간이 걸립니다. 마이그레이션을 마치기 전까지 이 컴포넌트의 가시성을 확보하는 일은 오히려 더 중요해졌습니다.
이름에 "Nginx"가 들어가 있어서 일반 Nginx와 같은 방식으로 모니터링하면 된다고 생각하기 쉽습니다. 하지만 두 컴포넌트는 이름만 비슷할 뿐, 모니터링이 다뤄야 하는 차원이 완전히 다릅니다.
이 차이의 결과로, Ingress-Nginx 운영자가 정말 신경 써야 할 지표도 일반 Nginx와 다릅니다.
- Config Reload가 성공했는가? Ingress 리소스 변경이 실패하면 새 라우팅이 적용되지 않습니다.
- TLS 인증서가 언제 만료되는가? cert-manager로 자동화했더라도 갱신 실패는 발생합니다.
- P50·P90·P99 지연 분포는 어떤가? 평균만 봐서는 인그레스 SLA를 판단할 수 없습니다.
이번 글에서는 Ingress-Nginx 모니터링이 왜 일반 Nginx와 다른 접근이 필요한지, 그리고 와탭의 OpenMetrics Ingress-Nginx 템플릿이 이 차이를 어떻게 한 화면에 정리하는지 살펴봅니다.
Ingress-Nginx 모니터링이 까다로운 이유
1. Config Reload: 보이지 않는 실패가 가장 무섭다
Ingress-Nginx Controller는 쿠버네티스 API 서버를 watch하면서 Ingress 리소스가 변경될 때마다 자동으로 nginx.conf를 다시 생성하고 reload합니다. 일반 Nginx에서는 운영자가 직접 nginx -s reload를 실행하지만, Ingress-Nginx에서는 변경이 잦은 환경일 경우 이 과정이 분당 수십 번 일어나기도 합니다.
문제는 이 reload가 항상 성공하는 것이 아니라는 점입니다.
- 잘못된 어노테이션(
nginx.ingress.kubernetes.io/...) 입력 - 충돌하는 라우팅 규칙
- 백엔드 Service 참조 오류
- TLS Secret 누락 또는 형식 오류
이런 경우 Ingress 리소스는 클러스터에 등록되지만 컨트롤러가 reload에 실패해 새 설정이 적용되지 않습니다. 그 결과 이런 상황이 벌어집니다.
개발자: "어제 Ingress 추가했는데 왜 안 돼요?"
운영자: "음... 일단 Pod 재시작해볼까요?"
이 진단을 정확히 하려면 nginx_ingress_controller_config_last_reload_successful 메트릭을 추적해야 합니다. 이 값이 0이라면 마지막 reload가 실패했다는 뜻입니다. 일반 Nginx 모니터링에는 존재하지 않는 차원의 지표입니다.
2. TLS 인증서 만료: Ingress 운영의 Hidden Killer
쿠버네티스 환경에서 가장 자주 발생하는 사고 중 하나가 TLS 인증서 만료로 인한 서비스 다운입니다. cert-manager로 자동화했더라도 다음과 같은 이유로 갱신이 실패할 수 있습니다.
- Let's Encrypt rate limit 도달
- DNS-01 challenge의 DNS 레코드 변경 누락
- ACME issuer 인증 정보 만료
- Webhook 인증 실패
가장 무서운 점은 이런 실패가 조용히 발생한다는 것입니다. 인증서가 만료되기 전까지는 아무 증상도 없다가, 만료 시점에 갑자기 모든 HTTPS 트래픽이 차단됩니다.
표준적인 해법은 nginx_ingress_controller_ssl_expire_time_seconds 메트릭 추적입니다. 호스트별 인증서 만료 시각을 Unix timestamp로 노출하므로, 다음과 같은 표준 알람 룰을 적용할 수 있습니다.
# 7일 이내 만료 시 알람
(avg(nginx_ingress_controller_ssl_expire_time_seconds) by (host) - time()) < 604800문제는 메트릭이 빌트인 대시보드에 잘 노출되지 않는다는 점입니다. 직접 Grafana 대시보드를 만들 때 잊고 추가하지 않는 경우가 흔합니다. 그리고 잊어버린 그 시점이 바로 사고가 터지는 시점이죠.
3. 평균 지연으로는 진짜 문제를 못 잡는다
일반적으로 응답 시간 모니터링이라고 하면 "평균 응답 시간"을 떠올리지만, 인그레스 환경에서는 평균이 거의 의미 없습니다.
이유는 인그레스가 다양한 백엔드 서비스로 라우팅한다는 데 있습니다. 어떤 서비스는 5ms에 응답하고, 어떤 서비스는 500ms가 걸립니다. 이를 평균 내면 "평균 50ms"가 나오는데, 실제로는 사용자 경험이 양극단으로 갈리고 있는 상황일 수 있습니다.
진짜 필요한 것은 백분위수(percentile) 분포입니다.
- P50: 중앙값. "보통의 사용자"가 경험하는 응답 시간
- P90: 요청의 90%가 이 시간 이내에 처리됨. 상위 10% 요청이 이보다 느림
- P99: 요청의 99%가 이 시간 이내에 처리됨. 가장 느린 1% 요청의 패턴
이를 추출하려면 Ingress-Nginx의 히스토그램 메트릭을 활용해 PromQL의 histogram_quantile() 함수로 계산해야 합니다. 직접 구축할 때 자주 빠뜨리거나 잘못 작성하는 부분입니다.
4. 컨트롤러 자체의 리소스도 지속적으로 추적해야 한다
Ingress-Nginx Controller는 단순한 프록시가 아니라 쿠버네티스 API를 watch하면서 동적으로 동작하는 컨트롤러입니다. 그래서 일반 Nginx와는 다른 형태의 리소스 부하가 발생합니다.
- 클러스터에 Ingress 리소스가 많아질수록 메모리 사용량 증가
- 잦은 reload로 인한 CPU 사용량 spike
- 특정 어노테이션이 워커 프로세스 동작을 변경
특히 컨트롤러 자체의 메모리·CPU 사용량은 인그레스의 트래픽 메트릭과 별도로 추적합니다. 컨트롤러 Pod가 OOM으로 죽으면 클러스터 전체의 외부 트래픽이 영향을 받기 때문입니다.
와탭 OpenMetrics Ingress-Nginx 템플릿: 인그레스의 본질에 맞춘 시각화
와탭 OpenMetrics Ingress-Nginx 템플릿은 위의 모든 차원을 5개 영역으로 정리해 한 화면에 제공합니다.
1. Overview: 컨트롤러 헬스의 5대 카드
대시보드 최상단의 5개 카드는 Ingress-Nginx 컨트롤러의 헬스를 즉시 판별하는 핵심 지표입니다.
여기서 가장 주목할 카드는 Last Config Failed입니다. 이 단순한 숫자 하나가 운영의 핵심 신호 역할을 합니다. 0이면 마지막 reload가 정상이고, 0이 아닌 값이면 즉시 인그레스 변경 사항을 점검해야 합니다.
이는 Ingress-Nginx 커뮤니티가 표준으로 권장하는 알람 룰을 카드 형태로 시각화한 것입니다. 직접 구축했다면 PromQL로 알람 룰을 만들고 별도 패널을 설계해야 했을 정보가, 메인 화면에 카드로 배치되어 있습니다.
2. Ingress Traffic & Network: 트래픽과 네트워크 압력 분리
트래픽 영역은 두 가지 차원으로 시각화됩니다.
Ingress 단위 분석
- Ingress Request Volume (req/s): 인그레스 리소스별 초당 요청 수
- Ingress Success Ratio: 인그레스별 성공률
demo-nginx-ingress처럼 인그레스 이름이 차트 라벨로 자동 표시되어, 어떤 인그레스가 트래픽을 많이 받는지 즉시 식별할 수 있습니다.
네트워크 압력 분석
- Network Inbound Pressure (bytes/s): 컨트롤러로 들어오는 데이터량
- Network Outbound Pressure (bytes/s): 컨트롤러에서 나가는 데이터량
두 차트의 비교는 백엔드 응답 데이터 크기를 잡는 데 유용합니다. Inbound가 30 bytes/s 수준인데 Outbound가 400 bytes/s 이상이라면, 작은 요청이 큰 응답을 받는 패턴(예: 정적 파일 서빙, 대용량 JSON 응답)을 의미합니다.
3. Resource Usage: 컨트롤러 자체의 헬스
k8s.io/ingress-nginx 라벨로 컨트롤러 Pod 자체의 리소스 사용량을 추적합니다.
- Average Memory Usage (bytes): 평균 메모리 사용량
- Average CPU Usage (cores): 평균 CPU 사용량
여기서 메모리가 점진적으로 증가하는 패턴이 보인다면 메모리 누수 또는 인그레스 리소스 폭증을 의심해야 합니다. CPU spike가 잦다면 reload가 너무 자주 일어나고 있다는 신호입니다. 이런 패턴은 트래픽 메트릭만 봐서는 알 수 없습니다.
4. Latency: P50·P90·P99 분리 시각화
가장 가치 있는 영역 중 하나입니다. 백분위수별로 분리된 표가 운영자의 진단 시야를 본질에 맞춥니다.
- P50 Latency: 중앙값. 일반 사용자 경험
- P90 Latency: 요청의 90%가 이 시간 이내에 처리됨
- P99 Latency: 가장 느린 1% 요청의 지연
각 표에는 인그레스 리소스 단위로 백분위수가 표시되므로, 어떤 인그레스가 long-tail 지연 문제를 가지고 있는지 즉시 좁힐 수 있습니다.
하단의 Request Latency Distribution은 Ingress-Nginx의 표준 히스토그램 버킷인 [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10](초)를 그대로 활용합니다. 어떤 버킷에 요청이 가장 많이 쌓이는지 시계열로 보여주므로, 응답 시간 분포의 형태 변화를 추적할 수 있습니다.
5. Certificate: TLS 인증서 만료 추적
이 영역이 이 템플릿의 진짜 킬러 기능입니다.
Ingress Certificate Expiry 표는 호스트별 인증서 만료 시각을 보여줍니다. host 컬럼에는 demo.whatap.local 같은 실제 호스트명이, Value 컬럼에는 만료 시각이 Unix timestamp로 표시됩니다.
현재 시각과의 차이가 줄어들수록 만료가 임박했다는 뜻이며, "만료까지 7일·30일 미만" 같은 임계값으로 알람을 거는 기준이 됩니다.
이 표가 메인 대시보드에 기본 포함되어 있다는 사실 자체가 가치입니다. 직접 구축한 환경에서는 nginx_ingress_controller_ssl_expire_time_seconds 메트릭을 잊고 패널에 추가하지 않았다가, 인증서 만료 사고를 겪은 후에야 추가하는 경우가 많기 때문입니다.
실전 시나리오: "갑자기 새 Ingress가 적용 안 돼요" 5분 진단
가상의 시나리오입니다. 개발팀이 새 서비스의 Ingress 리소스를 배포했는데, 외부에서 접근이 안 된다는 보고가 들어왔습니다.
T+0초, 문의 접수. "방금 배포한 new-payment-ingress가 동작 안 합니다."
T+30초, Last Config Failed 카드 확인. 대시보드를 펼치자마자 5개 카드 중 Last Config Failed가 1로 표시되어 있다면, 즉시 결론이 나옵니다. 마지막 config reload가 실패했다.
T+1분, Config Reloads 카드와 비교. Config Reloads 카운터가 정상적으로 증가하고 있는지 확인합니다. 증가하지 않았다면 컨트롤러가 변경 자체를 감지하지 못한 상황(K8s API 권한 문제 등)이고, 증가했지만 마지막이 실패했다면 새 Ingress 리소스의 어노테이션 또는 형식 문제입니다.
T+2분, kubectl로 검증.
kubectl describe ingress new-payment-ingress
kubectl logs -n ingress-nginx <controller-pod> | grep -i error컨트롤러 Pod 로그에서 reload 실패 사유를 확인합니다. 가령 nginx.ingress.kubernetes.io/rewrite-target 어노테이션의 잘못된 정규식 같은 것들입니다.
T+3분, 수정 적용. 잘못된 어노테이션 수정 후 kubectl apply.
T+4분, 대시보드에서 검증. Last Config Failed가 0으로 돌아오고 Config Reloads가 추가로 증가하는지 확인합니다. 새 Ingress가 정상 적용되었음을 확인.
T+5분, 종료. 개발팀에게 "어노테이션 형식 문제였다, 수정 완료"라고 회신합니다.
직접 구축한 환경에서 같은 진단을 했다면, kubectl로만 진단하면서 "왜 적용이 안 되지?" 헤매다가 결국 컨트롤러 로그까지 확인하는 30분짜리 시나리오가 됩니다. Last Config Failed 카드가 메인 화면에 있다는 것만으로 진단의 출발점이 정확해집니다.
와탭 OpenMetrics Ingress-Nginx 템플릿을 써야 하는 5가지 이유
1. Last Config Failed가 메인 카드: 가장 자주 놓치는 신호를 가장 잘 보이게
Ingress-Nginx 운영에서 가장 흔한 사고 패턴이 "reload가 실패했지만 운영자는 모르는 상황"입니다. 와탭 템플릿은 이 신호를 5개 카드 중 하나로 메인 위치에 배치해서, 대시보드를 펼치자마자 즉시 보이게 합니다.
이는 Ingress-Nginx 커뮤니티의 표준 알람 룰을 시각화로 풀어낸 형태입니다. 별도의 알람 룰 작성 없이도 가장 위험한 신호를 첫 시야에서 잡을 수 있습니다.
2. Certificate Expiry 표가 기본 제공: 망각으로 인한 사고 방지
TLS 인증서 만료는 잊혀지기 가장 쉬운 운영 항목입니다. 와탭 템플릿은 Certificate 영역을 별도 섹션으로 분리하고, 호스트별 만료 시각 표를 기본 제공합니다.
cert-manager를 사용 중이라면 자동 갱신이 정상 동작하는지 검증하는 용도로, 수동 관리 중이라면 만료 임박 호스트를 즉시 식별하는 용도로 활용할 수 있습니다. "어느 날 갑자기 HTTPS가 끊긴다"는 사고를 미연에 방지하는 가장 효과적인 도구입니다.
3. P50·P90·P99 분리: 평균이 가리는 진실을 드러낸다
평균 응답 시간만 보면 인그레스의 진짜 문제를 놓치기 쉽습니다. 와탭 템플릿은 P50·P90·P99를 각각 별도 표로 분리해서, long-tail 지연 문제를 즉시 식별할 수 있게 합니다.
특히 P99 지연은 SLO 관리의 핵심 지표인데, 이를 PromQL의 histogram_quantile()로 직접 추출해 패널을 만드는 작업은 만만치 않습니다. 와탭 템플릿은 이를 표 형태로 기본 제공해, 인그레스별 P99 비교를 즉시 가능하게 합니다.
4. 컨트롤러 헬스와 트래픽 헬스를 같은 화면에서
Ingress-Nginx 운영의 어려운 점 중 하나가 컨트롤러 자체의 문제와 트래픽 자체의 문제를 구분하는 것입니다. 와탭 템플릿은 Resource Usage 영역(컨트롤러 메모리·CPU)과 Traffic & Network 영역(인그레스별 트래픽)을 같은 대시보드에 배치해, 두 차원을 시간축에서 즉시 비교할 수 있게 합니다.
"성공률이 떨어졌다 → 컨트롤러 메모리도 같이 튀었나?" 같은 교차 검증이 한 화면에서 끝납니다.
5. 운영 부담 0: Prometheus + Grafana 직접 구축 불필요
Ingress-Nginx 공식 문서는 Prometheus + Grafana 직접 구축 가이드를 제공하지만, 이를 운영 가능한 수준으로 셋업하려면 ServiceMonitor 설정, PrometheusRule 작성, Grafana 대시보드 import, 알람 정책 수립 등 여러 단계가 필요합니다.
와탭은 OpenAgent에 컨트롤러의 /metrics 엔드포인트(기본 포트 10254)를 등록하면 위 5개 영역이 즉시 동작합니다. 별도의 Prometheus 클러스터 운영 부담 없이, 글로벌 SaaS에서 검증된 인프라 위에서 메트릭을 안정적으로 수집·분석할 수 있습니다.
직접 구축 vs 와탭 OpenMetrics Ingress-Nginx 템플릿
결론: 인그레스는 다른 차원의 모니터링이 필요하다
Ingress-Nginx Controller는 일반 Nginx의 사촌처럼 보이지만, 모니터링이 다뤄야 하는 차원은 본질적으로 다릅니다. Config Reload·TLS 인증서·백분위수 지연·컨트롤러 헬스, 이 네 가지가 일반 Nginx에는 존재하지 않거나 우선순위가 낮은 항목들입니다.
쿠버네티스 환경에서 외부 트래픽의 첫 관문이라는 위치 특성상, Ingress-Nginx의 장애는 클러스터 전체의 외부 가용성 문제로 직결됩니다. 그만큼 모니터링이 정확하게 본질을 향해야 합니다.
와탭 OpenMetrics Ingress-Nginx 템플릿은 이 차이를 정확히 반영해, 인그레스 운영자가 진짜 봐야 할 정보를 메인 화면에 자동으로 정렬합니다. 잊기 쉬운 Certificate Expiry, 가장 자주 놓치는 Last Config Failed, 평균이 가리는 P99 지연. 이 모든 것이 별도 작업 없이 즉시 가시화됩니다.
유지보수 종료 이후에도 기존 인그레스를 안전하게 운영하고 차세대 게이트웨이로 넘어가기 전까지의 공백을 메우려면, 정확한 모니터링이 필수입니다. 인그레스 모니터링은 "Nginx를 보는 일"이 아니라 "클러스터의 관문을 지키는 일"입니다.
15일 무료 체험으로 Ingress-Nginx 템플릿을 직접 확인해보세요.
함께 보면 좋은 자료
