헬름 차트로 ingress-nginx 를 새 버전으로 올린 직후, 컨트롤러 파드는 정상인데 기존 호스트로 들어가면 전부 404 가 뜬다. 노드포트도 그대로이고 DNS 도 그대로다.
kubectl get ingressclass
kubectl -n <namespace> get ingress
kubectl -n <namespace> describe ingress <one> | grep -i class
kubectl -n <ingress-ns> logs -l app.kubernetes.io/component=controller --tail=200
컨트롤러 로그에 인그레스 동기화(Scheduled for sync) 이벤트가 하나도 없으면 클래스가 어긋난 것이다.
여기서 자주 헷갈린다. 이름이 비슷한 값이 둘이고 역할이 다르다.
| 값 | 의미 | 관례적 값 |
|---|---|---|
controller.ingressClassResource.name |
IngressClass 리소스의 이름. 인그레스의 spec.ingressClassName 이 이 값을 가리킨다 |
nginx |
controller.ingressClassResource.controllerValue |
IngressClass 의 spec.controller. 어느 컨트롤러 구현이 이 클래스를 처리하는지 식별한다 |
k8s.io/ingress-nginx |
controllerValue 는 컨트롤러 구현을 가리키는 고정 식별자이므로 버전을 올려도 바뀌지 않는다. 이 값을 임의로 ingress-nginx 같은 다른 문자열로 바꾸면 컨트롤러가 자기 클래스를 인식하지 못해 모든 인그레스가 404 로 떨어진다.
컨트롤러 파드의 실제 인자로 확인한다.
kubectl -n <ingress-ns> get deploy ingress-nginx-controller \
-o jsonpath='{.spec.template.spec.containers[0].args}' | tr ',' '\n' | grep -i class
--controller-class=k8s.io/ingress-nginx
--ingress-class=nginx
최근 차트에서는 컨트롤러 서비스를 controller.service.external 과 controller.service.internal 로 나눠 정의한다. 예전 값 이름(controller.service.nodePorts.http 등)만 넘기면 조용히 무시되어 포트가 원하는 대로 열리지 않는다.
베어메탈에서 노드포트 80 · 443 으로 여는 예다.
helm upgrade --install ingress-nginx ./ingress-nginx-<chart-version>.tgz \
-n <ingress-ns> \
--set controller.ingressClassResource.name=nginx \
--set controller.ingressClassResource.controllerValue=k8s.io/ingress-nginx \
--set controller.ingressClass=nginx \
--set controller.service.enabled=true \
--set controller.service.external.enabled=true \
--set controller.service.external.type=NodePort \
--set controller.service.external.ports.http=80 \
--set controller.service.external.ports.https=443 \
--set controller.service.external.nodePorts.http=80 \
--set controller.service.external.nodePorts.https=443 \
--set controller.config.use-forwarded-headers=true
노드포트로 1024 미만 포트를 쓰려면 API 서버의 --service-node-port-range 가 그 범위를 포함해야 한다.
올리기 전에 현재 릴리스의 값을 뽑아 두고 비교한다.
helm -n <ingress-ns> get values ingress-nginx -o yaml > values.before.yaml
helm show values ./ingress-nginx-<chart-version>.tgz > values.new.yaml
업그레이드 후 로그에 이 경고가 쌓이는 경우가 있다.
Unexpected error validating SSL certificate "<ns>/<secret>" for server "*.example.com":
x509: certificate is valid for example.com, not *.example.com
Using default certificate
인증서 SAN 과 인그레스 호스트가 어긋난 것이다. 와일드카드 호스트를 쓰는 인그레스가 있으면 인증서에도 와일드카드 SAN 이 있어야 한다. 이 경고는 404 의 원인이 아니라 별개 문제다.
Service "<ns>/<name>" does not have any active Endpoint 도 마찬가지로 별개다. 해당 서비스의 파드가 없다는 뜻이다.
컨트롤러 최신 릴리스는 controller-v1.15.1 이다 - 2026-09-20 확인. 차트 버전과 컨트롤러 버전은 번호가 다르므로 릴리스 노트에서 대응표를 본다.