jupocket

미니큐브(NodePort) 서비스가 로컬에서 바로 안 열리는 이유와 해결 방법 정리

—

쿠버네티스에서 Service를 NodePort로 만들면 “노드 IP + 포트로 접속하면 되겠지”라고 생각하기 쉽습니다. 그런데 미니큐브(minikube)로 실습할 때는 로컬 PC에서 노드IP:NodePort로 접속이 안 되는 상황을 자주 만납니다. 이 글에서는 왜 이런 일이 생기는지, 그리고 로컬에서 서비스에 정상적으로 접속하는 가장 현실적인 방법이 무엇인지 정리합니다.

1. 현상: Service(NodePort)는 만들었는데 접속이 안 된다

Service가 NodePort로 생성되면 다음처럼 보입니다.

  • TYPE: NodePort
  • PORT(S): 80:30080/TCP

여기서 많은 사람이 http://<노드IP>:30080로 접속을 시도합니다. 하지만 로컬 환경에서는 이 시도가 실패하는 경우가 많습니다. 특히 macOS에서 Docker 드라이버 기반으로 미니큐브를 돌릴 때 이 현상이 더 자주 나타납니다.

2. 왜 로컬에서 

노드IP:NodePort

로 바로 접속이 안 될까?

결론은 네트워크 구조 때문입니다. 미니큐브는 “내 PC 안에 쿠버네티스 클러스터를 하나 더 만든 것”인데, 이 클러스터는 로컬 PC와 같은 네트워크에 있는 것이 아니라, 가상 환경(또는 Docker 내부 네트워크) 안에 별도 네트워크로 존재합니다.

즉, 아래처럼 네트워크가 분리되어 있습니다.

  • 로컬 PC 네트워크(호스트 네트워크)
  • 미니큐브 클러스터 네트워크(가상/컨테이너 네트워크)

NodePort는 “클러스터 노드의 네트워크 인터페이스”에 포트를 여는 방식인데, 로컬 PC 입장에서는 그 노드 IP가 내 네트워크에서 라우팅 가능한 IP가 아닐 수 있습니다. 그래서 노드IP:NodePort를 때려도 연결이 안 됩니다.

특히 macOS + Docker 드라이버 조합에서는 미니큐브 노드가 Docker 내부에 컨테이너로 떠 있기 때문에, 노드 IP는 Docker 내부망 대역이 되고 로컬에서 직접 접근할 경로가 막히는 케이스가 흔합니다.

3. 그럼 어떻게 접속해야 할까? (실습 기준 정답)

로컬에서 빠르게 접속하는 가장 쉬운 방법은 minikube service 명령어를 사용하는 것입니다.

3.1 

minikube service

가 해주는 일

minikube service는 특정 Service로 접속할 수 있는 임시 URL을 생성합니다. 이 URL은 로컬에서 접근 가능한 형태(예: 127.0.0.1)로 만들어지고, 요청이 들어오면 미니큐브가 내부적으로 Service → Pod로 전달합니다.

즉, “내 PC가 직접 노드IP로 들어가는 것”이 아니라, minikube가 중간에서 접속 통로를 만들어주는 방식입니다.

4. 해결 방법: 

minikube service

로 임시 접속 URL 만들기

예를 들어 Service 이름이 nginx-service라면 아래처럼 실행합니다.

minikube service nginx-service --url

실행하면 아래처럼 URL이 출력됩니다.

http://127.0.0.1:51922

이제 로컬 PC에서 해당 URL로 접속하면 됩니다.

  • 브라우저: http://127.0.0.1:51922
  • curl: curl http://127.0.0.1:51922

여기서 한 가지 중요한 점이 있습니다. 이 URL은 “고정 주소”가 아니라 임시로 생성되는 접근 통로이기 때문에, 명령 실행을 종료하면(예: CTRL + C) 접속이 끊길 수 있습니다.

macOS에서 Docker 드라이버를 쓰는 경우 다음과 같은 안내 메시지가 함께 나오기도 합니다.

  • darwin에서 Docker 드라이버를 사용하고 있기 때문에, 터미널을 열어야 실행할 수 있습니다.

이 문구는 “이 접속 통로가 터미널 세션에 묶여 있을 수 있다”는 의미로 이해하면 됩니다. 실습 단계에서는 정상 동작이며, 운영 방식과는 다릅니다.

5. 실습 종료: 리소스 정리

테스트가 끝나면 배포한 디플로이먼트를 삭제합니다.

kubectl delete deployment nginx-deploy

Service까지 정리하려면 아래도 추가합니다.

kubectl delete service nginx-service

6. 한 줄 요약

미니큐브에서 NodePort로 서비스를 만들었는데 로컬에서 노드IP:NodePort로 접속이 안 되는 이유는, 로컬 네트워크와 미니큐브 클러스터 네트워크가 분리되어 있어 라우팅이 안 되기 때문입니다. 실습에서 가장 간단한 해결 방법은 minikube service <서비스명> –url로 로컬에서 접근 가능한 임시 URL을 만들어 접속하는 것입니다.