verify.sh 4단계 실패 — Jenkins 컨테이너에서 127.0.0.1:6443 connection refused

Question

환경 macOS (Apple Silicon) Docker Desktop 4.93.0, Kubernetes v1.36.1 (kubeadm 모드) 증상 setup-mac.sh 실행 후 bash verify.sh 를 돌리면 1~3단계는 통과합니다. 4단계(Jenkins 컨테이너 내부에서 K8s 접속)만 아래 에러로 실패했습니다. The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port? 원인 호스트의 ~/.kube/config 에 클러스터 주소가 https://127.0.0.1:6443 으로 저장되어 있었습니다. 이 파일이 그대로 Jenkins 컨테이너에 마운트됩니다. 컨테이너 안에서 127.0.0.1 은 호스트가 아니라 컨테이너 자기 자신이라서 접속이 거부됩니다. 교안의 docker-compose.yml ( extra_hosts: kubernetes.docker.internal:host-gateway )은 kubeconfig 주소가 kubernetes.docker.internal 이라고 전제하고 있습니다. 그런데 제 Mac은 /etc/hosts 에 kubernetes.docker.internal 항목이 없었고, Docker Desktop이 kubeconfig에 127.0.0.1 을 쓰고 있었습니다. Docker 공식 문서에도 Mac에서는 kubernetes.docker.internal 이 127.0.0.1 로 해석되도록 등록하는 것이 사용자 책임이라고 되어 있습니다. Windows에는 자동 등록 설정이 있지만 Mac에는 없습니다. https://docs.docker.com/desktop/setup/install/mac-permission-requirements/ 해결 /etc/hosts 에 이름을 등록했습니다. sudo sh -c 'echo "127.0.0.1 kubernetes.docker.internal" >> /etc/hosts' kubeconfig 클러스터 주소를 바꿨습니다. kubectl config set-cluster docker-desktop --server=https://kubernetes.docker.internal:6443 bash verify.sh 를 다시 실행하니 4단계까지 모두 통과했습니다. Jenkins 컨테이너 재시작은 필요 없었습니다.

Dowon Lee · Answer

안녕하세요, 이도원입니다. 정보 공유해 주셔서 감사드립니다. macOS에 Docker Desktop을 설치했다고 해서 /etc/hosts 에 kubernetes.docker.internal 항목이 반드시 생성되는 것은 아닙니다. Docker Desktop은 내부 DNS/가상 네트워크를 통해 host.docker.internal , kubernetes.docker.internal 같은 이름을 해석하는 경우가 많아서, /etc/hosts 에 명시적으로 다음 항목이 없어도 동작할 수 있습니다. kubernetes.docker.internal 은 Docker Desktop에서 Kubernetes를 활성화했을 때 Kubernetes API 서버 접근용 이름으로 사용될 수 있지만, 버전이나 설정에 따라 /etc/hosts 에 직접 기록되는 방식이 아닐 수 있습니다. 말씀하셨던 문제를 해결하는 방법으로 /etc/hosts 를 수정하는 것과 현재의 kubeconfig를 확인해서 적용하시는 것이 좋다고 생각됩니다. kubectl config view --minify 감사합니다.

communityai8509 · Answer

안녕하세요, 인프런 AI 인턴입니다. 터프남님 Jenkins 컨테이너 내부에서 127.0.0.1:6443 으로 접속할 때, 127.0.0.1 은 호스트가 아닌 컨테이너 자신을 가리키므로 Kubernetes API Server에 연결할 수 없습니다. 컨테이너에서 호스트의 Kubernetes API Server에 접근하려면 kubeconfig의 서버 주소를 호스트로 해석 가능한 도메인( kubernetes.docker.internal )으로 변경하고, Docker Compose에서 해당 호스트를 연결해 주어야 합니다. Kubernetes Dashboard를 호스트에서 외부 접근하는 과정과 포트 포워딩 확인 방법을 다룬 유사한 답변을 참고해 주세요. Kubernets 설치 관련 질문 해당 답변에서도 kubectl proxy 실행 시 지정한 Master Node의 IP로 접속하도록 안내하고 있으며, 컨테이너 또는 외부 환경에서 Kubernetes API에 접근할 때 localhost 대신 접근 가능한 호스트 주소를 사용해야 한다는 점이 핵심입니다. 또한 서비스의 외부 포트는 kubectl get services 명령으로 확인할 수 있습니다. 추가로 질문자님께서 적용하신 것처럼 다음과 같이 kubeconfig의 API Server 주소를 변경하는 방식이 적절합니다. kubectl config set-cluster docker-desktop \ --server=https://kubernetes.docker.internal:6443 macOS에서 kubernetes.docker.internal 이 호스트로 해석되지 않는 경우에는 /etc/hosts 에 해당 이름을 등록해야 하며, Docker Compose의 extra_hosts 설정도 함께 확인해야 합니다. 저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다. 현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏 추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.