Kubernetes 클러스터에 마스터 & 워커 노드 추가하기 (확장 가이드)

최근 쿠버네티스 클러스터를 확장해야 할 일이 생겼습니다. 새로운 노드를 추가하면서 여러 명령어를 다시 찾느라 애를 먹었고, "다음엔 좀 더 쉽게 해보자!"는 마음으로 이 글을 정리하게 되었습니다.

🧭 목적

이 글은 Kubernetes 클러스터 확장 시, 마스터 또는 워커 노드를 추가하는 방법과 그에 필요한 명령어를 한눈에 정리한 가이드입니다.

1. 마스터 노드 추가하기 (Master Node Join)

새로운 마스터 노드를 클러스터에 조인시키려면, 기존 마스터 노드에서 몇 가지 작업이 필요합니다. 가장 먼저, 클러스터를 최초 구성할 때 사용했던 kubeadm-config.yaml 파일이 있어야 합니다.

📝 예시 kubeadm-config.yaml

apiVersion: kubeadm.k8s.io/v1beta2
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 10.0.10.101
  bindPort: 6443
nodeRegistration:
  criSocket: /var/run/containerd/containerd.sock
---
apiVersion: kubeadm.k8s.io/v1beta2
kind: ClusterConfiguration
kubernetesVersion: 1.26.3
controlPlaneEndpoint: 10.0.10.100:6443
imageRepository: registry.k8s.io
networking:
  serviceSubnet: 10.96.0.0/12
  podSubnet: 192.168.0.0/16
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd

🔑 인증서 키 생성

기존 마스터 노드에서 아래 명령어를 실행하면, 새로운 마스터 노드를 위한 인증서 키가 생성됩니다:

kubeadm init phase upload-certs --upload-certs --config=kubeadm-config.yaml

예시 출력:

[upload-certs] Using certificate key:
3f92ac5bd1230f44e9e8cbcc65a3e8be9a9d1a501f032bde881a7a2ff21ef8e1

🔗 join 명령어 생성

이제 위에서 생성한 인증서 키를 포함해 join 명령어를 생성합니다:

kubeadm token create --certificate-key 3f92ac5bd1230f44e9e8cbcc65a3e8be9a9d1a501f032bde881a7a2ff21ef8e1 --print-join-command

예시 결과:

kubeadm join 10.0.10.100:6443 --token x7yz12.mj18slwz58r2t8d0 \
  --discovery-token-ca-cert-hash sha256:5f42b9ef35dabc8cce6c1c632bf6e31f9c3aabc90df07d630a0b4c1d2f8b1234 \
  --control-plane --certificate-key 3f92ac5bd1230f44e9e8cbcc65a3e8be9a9d1a501f032bde881a7a2ff21ef8e1

해당 명령어를 새로운 마스터 노드에서 실행하면 클러스터에 성공적으로 추가됩니다.

2. 워커 노드 추가하기 (Worker Node Join)

워커 노드는 훨씬 간단하게 추가할 수 있습니다.
역시 기존 마스터 노드에서 아래 명령어를 실행하면 됩니다.

kubeadm token create --print-join-command

예시 출력:

kubeadm join 10.0.10.100:6443 --token a1b2c3.d4e5f6g7h8i9j0kl \
  --discovery-token-ca-cert-hash sha256:5f42b9ef35dabc8cce6c1c632bf6e31f9c3aabc90df07d630a0b4c1d2f8b1234

이 명령어를 추가하고자 하는 워커 노드에서 실행하면, 해당 노드는 클러스터에 자동으로 연결됩니다.

🧾 정리

마스터 노드 추가 시에는 인증서 키와 --control-plane 옵션이 필요합니다.
워커 노드는 간단한 join 명령어로 추가 가능합니다.
모든 노드에서 containerd, kubelet 등 기본 구성은 완료되어 있어야 합니다.
보안을 위해 생성한 토큰과 인증서 키는 일정 시간이 지나면 만료됩니다. 사용 직후에 노드에 접속하는 것이 좋습니다.

노드 확장은 생각보다 간단하지만, 명령어를 정확히 기억해두는 것이 중요합니다.
이번에 한번 정리해두면 다음 확장 작업은 훨씬 수월해질 거예요!

이 블로그 검색

impact