K8s 클러스터 초기화 · 컨트롤플레인 설치

쿠버네티스 클러스터 마스터 노드 및 컨트롤플레인(kube apiserver, kube controller manager, kube scheduler, etcd)을 초기화하고 자동 설치합니다.

QUANTUM C&S

쿠버네티스 클러스터 마스터 노드 및 컨트롤플레인(kube-apiserver, kube-controller-manager, kube-scheduler, etcd)을 초기화하고 자동 설치합니다.

이 항목은 워커 노드 조인, 컨테이너 런타임 설치, CNI 네트워크 설치와 함께 하나의 플레이북(k8s.yaml) 실행 안에서 순서대로 처리됩니다. 이 항목만 따로 실행할 수는 없고, 아래 실행 명령은 4개 항목에 공통입니다.

사전 준비 확인

노드가 프로비저닝 단계에서 준비되어 있어야 합니다.

cd /home/ubuntu/k8s
ansible -i inventory/qks/hosts.ubuntu kube-cluster -m ping

모든 노드에서 "ping": "pong"이 나오면 준비된 것입니다.

접속 키(qks.pem)는 배포 서버의 홈 디렉토리(~/qks.pem)에 있어야 합니다.

cp qks.pem ~/qks.pem
chmod 600 ~/qks.pem

설정값 확인

kube_version: "1.36.3"
kube_default_domain: "k8s.example.com"
kube_default_context: "MYCLUSTER"

kube_version

설치할 Kubernetes 버전 (예: 1.36.3). pkgs.k8s.io에 실제 존재하는 마이너 버전이어야 합니다.

kube_default_domain

클러스터 기본 도메인. 인증서 SAN과 내부 서비스 FQDN에 반영됩니다.

kube_default_context

kubectl 설정에 표시되는 클러스터 이름표입니다. 동작에는 영향을 주지 않습니다.

플레이북 실행

./install.sh ubuntu k8s.yaml

설치 흐름 (이 항목에 해당하는 부분)

1. OS 기본 설정 + 인증서 발급/배포   (qks-bootstrap, qks-certificate)
2. Helm 설치                        (qks-helm)
3. Kubernetes 패키지 설치           (qks-kubernetes/k8s/cluster)
4. 로드밸런서(HAProxy) 구성         (qks-load-balancer)
5. 컨트롤플레인 초기화              (qks-kubernetes/k8s/master) ← 이 항목
   - kubeadm init 실행
   - 마스터가 여러 대면 나머지 마스터도 join

4단계에서 구성한 로드밸런서 주소를 5단계의 kubeadm init이 API 서버 접속 대상(고가용성 엔드포인트)으로 사용합니다.

설치 확인

kubectl get pods -n kube-system

etcd, kube-apiserver, kube-controller-manager, kube-scheduler가 마스터 대수만큼 Running인지 확인합니다.

kubectl get nodes

마스터 노드가 control-plane 롤로 Ready 상태여야 합니다.

다음 단계

➕ 워커 노드 조인 워커 노드를 클러스터에 추가

이전 문서

← 노드 프로비저닝 (VM 생성)

다음 문서

워커 노드 조인 · 추가 →