Kubernetes 클러스터를 운영하다 보면 마스터 노드의 IP를 변경해야 하는 상황이 종종 발생합니다. 예를 들어, 네트워크 재구성, 클러스터 확장, 또는 새로운 인프라 환경으로 이전할 때 기존의 마스터 노드 IP를 유지하기 어려울 수 있습니다.
이때, controlPlaneEndpoint를 IP 대신 호스트네임(예: master1)으로 설정하면 유연성이 크게 향상됩니다.
이를 활용하면 사전에 클러스터를 패키징해 배포한 후, 환경에 맞게 IP만 변경하는 방식으로 운영할 수 있어 클러스터 재설치 없이 손쉽게 마이그레이션이 가능합니다.
이번 글에서는 kubeadm 기반 Kubernetes 클러스터에서 마스터 노드의 IP를 유연하게 변경하는 방법을 설명합니다.
1. kubeadm init.yaml 설정 확인 (IP 대신 호스트네임 사용)
Kubernetes 클러스터를 처음 설정할 때 controlPlaneEndpoint를 고정된 IP가 아니라 호스트네임으로 설정하면 향후 IP 변경이 훨씬 쉬워집니다.
예제 ClusterConfiguration 파일:
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
clusterName: kubernetes
etcd:
local:
dataDir: /var/lib/etcd
networking:
dnsDomain: cluster.local
serviceSubnet: 10.96.0.0/12
podSubnet: 10.244.0.0/16
kubernetesVersion: "v1.27.14"
certificatesDir: /etc/kubernetes/pki
controlPlaneEndpoint: master1:6443 # ⬅ IP 대신 호스트네임 사용
controlPlaneEndpoint를 IP가 아닌 master1처럼 호스트네임으로 설정하면, 클러스터 재설치 없이 /etc/hosts 파일만 수정해 마스터 노드의 IP를 쉽게 변경할 수 있습니다.
2. kubeadm을 이용한 클러스터 초기화
아래 명령어를 실행해 클러스터를 초기화합니다.
kubeadm init --config /root/kubeadm-init.yaml
이제, 주요 Kubernetes 설정 파일에서 기존 IP를 새로운 IP로 업데이트해야 합니다.
3. etcd 및 kube-apiserver 설정 수정
Kubernetes의 etcd와 API Server는 특정 IP를 사용하여 통신하기 때문에, 기존 IP를 새로운 IP로 변경해야 합니다.
📌 kube-apiserver.yaml 수정
vi /etc/kubernetes/manifests/kube-apiserver.yaml
<기존 IP>값을<변경할 IP>로 변경
이 과정이 끝나면, 클러스터가 새 IP에서 정상적으로 동작할 준비가 됩니다.
📌 kube-apiserver.yaml 수정
vi /etc/kubernetes/manifests/kube-apiserver.yaml
- 변경해야 할 IP 목록
metadata.annotations["kubeadm.kubernetes.io/kube-apiserver.advertise-address.endpoint"]-advertise-address
변경 전:
metadata:
annotations:
kubeadm.kubernetes.io/kube-apiserver.advertise-address.endpoint: 192.168.135.53:6443
spec:
containers:
- command:
- kube-apiserver
- --advertise-address=192.168.135.53
변경 후:
metadata:
annotations:
kubeadm.kubernetes.io/kube-apiserver.advertise-address.endpoint: <변경할 IP>:6443
spec:
containers:
- command:
- kube-apiserver
- --advertise-address=<변경할 IP>
📌 etcd.yaml 수정
vi /etc/kubernetes/manifests/etcd.yaml
- 변경해야 할 IP 목록
metadata.annotations["kubeadm.kubernetes.io/etcd.advertise-client-urls"]-listen-client-urls-advertise-client-urls-listen-peer-urls-initial-advertise-peer-urls
변경 전:
metadata:
annotations:
kubeadm.kubernetes.io/etcd.advertise-client-urls: <https://192.168.135.53:2379>
spec:
containers:
- command:
- etcd
- --listen-client-urls=https://192.168.135.53:2379
- --advertise-client-urls=https://192.168.135.53:2379
- --listen-peer-urls=https://192.168.135.53:2380
- --initial-advertise-peer-urls=https://192.168.135.53:2380
변경 후:
metadata:
annotations:
kubeadm.kubernetes.io/etcd.advertise-client-urls: https://<변경할 IP>:2379
spec:
containers:
- command:
- etcd
- --listen-client-urls=https://<변경할 IP>:2379
- --advertise-client-urls=https://<변경할 IP>:2379
- --listen-peer-urls=https://<변경할 IP>:2380
- --initial-advertise-peer-urls=https://<변경할 IP>:2380
이 과정을 거치면 etcd와 kube-apiserver가 새로운 IP에서 정상적으로 동작할 준비가 됩니다.
4. 기존 API-server 및 ETCD 인증서 제거 및 재생성
5-1. /etc/kubernetes 하위 모든 IP 변경
cd /etc/kubernetes/
sudo find . -type f -exec sed -i 's/192.168.135.121/192.168.135.123/g' {} +
5-2. 기존 API-server 및 ETCD 인증서 제거
rm -rf /etc/kubernetes/pki/apiserver.* /etc/kubernetes/pki/etcd/peer.* /etc/kubernetes/pki/etcd/server.*
5-3. 새로운 인증서 생성
kubeadm init phase certs apiserver --apiserver-cert-extra-sans=10.96.0.1,192.168.135.123,master1
kubeadm init phase certs etcd-peer
kubeadm init phase certs etcd-server
5-4. 최종적으로 모든 인증서 갱신
kubeadm certs renew all
5. /etc/hosts 파일 수정 (핵심!)
이제 /etc/hosts 파일에서 master1 호스트네임을 새 IP로 매핑해야 합니다.
vi /etc/host
변경 전:
<기존 IP> master1
변경 후:
<변경할 IP> master1
이렇게 하면 기존 클러스터 설정을 변경하지 않고도, 새로운 IP를 적용할 수 있습니다.
6. kubelet 서비스 재시작
설정이 완료되었으면, kubelet을 재시작하여 변경 사항을 반영합니다.
systemctl restart kubelet
재시작 후, 새로운 IP를 가진 마스터 노드에서 Kubernetes가 정상적으로 동작하는지 확인합니다.
마무리 및 검증
이제 마스터 노드의 IP가 변경되었습니다. 다음 명령어를 실행하여 Kubernetes 클러스터가 정상적으로 동작하는지 확인하세요.
kubectl get nodes
kubectl get pods -A
모든 노드와 파드가 정상적으로 READY 상태로 표시되면 마스터 노드의 IP 변경이 성공적으로 완료된 것입니다.
IP 대신 호스트네임을 사용하는 것이 왜 유용할까?
일반적으로 controlPlaneEndpoint를 특정 IP로 설정하면, 마스터 노드의 IP를 변경할 때마다 클러스터를 재설정해야 하는 번거로움이 있습니다.
하지만 호스트네임을 사용하면 다음과 같은 장점이 있습니다.
✅ 유연한 인프라 운영 – 네트워크 변경 시 /etc/hosts만 수정하면 IP 변경이 가능
✅ 미리 패키징 후 배포 가능 – 사전 구축된 설정을 여러 환경에서 쉽게 활용
✅ 재설치 없이 마이그레이션 가능 – 클러스터를 새 환경으로 옮길 때도 설정 변경 최소화
✅ DNS 기반 운영 가능 – 고정 IP 없이도 내부 DNS를 활용해 클러스터 운영
특히, 대규모 클러스터에서 운영 자동화를 고려할 때 매우 유용합니다.
정리
✅ kubeadm init.yaml에서 controlPlaneEndpoint를 IP 대신 호스트네임으로 설정
✅ kubeadm init 실행
✅ /etc/kubernetes/manifests/etcd.yaml, /etc/kubernetes/manifests/kube-apiserver.yaml에서 IP 변경
✅ /etc/hosts에서 master1 호스트네임을 새로운 IP로 매핑
✅ kubelet 서비스 재시작 후 정상 동작 확인
이 과정을 따르면 kubeadm 기반 Kubernetes 마스터 노드의 IP를 쉽게 변경할 수 있으며, 클러스터를 더욱 유연하게 운영할 수 있습니다.
🚀 사전에 클러스터를 패키징하여 배포한 후, 환경에 맞게 IP만 변경할 수 있도록 설정하면 운영 효율성을 극대화할 수 있습니다!
매주 한 page, 기술 한 spoon 