1. 개요

Rocky Linux 9.6 (x86_64) 환경에서 Kubernetes를 직접 설치하려면 많은 패키지 설정과 kubeadm 초기화 작업이 필요합니다.
여기서는 Kubespray(Ansible 기반 자동화 툴)를 활용해, 멀티 노드 클러스터를 빠르고 안정적으로 구성하는 방법을 다룹니다.

2. 전체 설치 스크립트

다음 스크립트는 **컨트롤 노드(설치 실행용 서버)**에서 실행하세요.
(모든 노드에 SSH root 접근 가능해야 합니다.)

#!/usr/bin/env bash
# Rocky 9.6 (x86_64) - Kubeadm + Kubespray Kubernetes 설치 자동화
# 작성자: fullmoon-system 블로그
# set -euxo pipefail: 에러 발생 시 즉시 중단 + 디버깅
set -euxo pipefail
trap 'echo -e "\n[ERR ] line $LINENO failed. 로그 확인 필요" >&2' ERR

##############################################
# 1. 환경 변수
##############################################
CLUSTER_NAME="mycluster"
K8S_VERSION="v1.34"        # 설치할 K8s 버전 라인
KUBESPRAY_VER="release-2.24"  # Kubespray 버전 (K8s v1.34 호환)
INVENTORY_DIR="inventory/${CLUSTER_NAME}"

# 클러스터 노드 IP (예: master1, worker1, worker2)
IPS=("192.168.10.10" "192.168.10.11" "192.168.10.12")

##############################################
# 2. 공통 사전 준비 (모든 노드)
##############################################
echo "[STEP 1] 공통 사전 설정 (firewalld/SELinux/커널 파라미터)"
for ip in "${IPS[@]}"; do
ssh root@$ip bash -s <<'EOF'
set -eux
# 방화벽 & SELinux
setenforce 0 || true
sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config
systemctl disable --now firewalld || true

# 커널 모듈
cat <<EOT >/etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOT
modprobe overlay
modprobe br_netfilter

# 커널 파라미터
cat <<EOT >/etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOT
sysctl --system
EOF
done

##############################################
# 3. Kubespray 설치 서버 준비
##############################################
echo "[STEP 2] Kubespray 환경 준비"
dnf install -y epel-release git python3-pip sshpass
pip3 install --upgrade pip
pip3 install ansible-core==2.14.7 jinja2 netaddr pyyaml

# Kubespray 다운로드
if [ ! -d kubespray ]; then
  git clone https://github.com/kubernetes-sigs/kubespray.git
fi
cd kubespray
git fetch --all
git checkout ${KUBESPRAY_VER}
pip3 install -r requirements.txt

##############################################
# 4. 인벤토리 생성
##############################################
echo "[STEP 3] Kubespray 인벤토리 생성"
cp -rfp inventory/sample ${INVENTORY_DIR}

# 자동 인벤토리 빌드
CONFIG_FILE=${INVENTORY_DIR}/hosts.yaml python3 contrib/inventory_builder/inventory.py ${IPS[@]}

##############################################
# 5. 설치 실행
##############################################
echo "[STEP 4] Kubernetes 클러스터 설치 시작"
ansible-playbook -i ${INVENTORY_DIR}/hosts.yaml cluster.yml -b -v \
  --private-key=~/.ssh/id_rsa

##############################################
# 6. 완료 확인
##############################################
echo "[STEP 5] 설치 완료 확인 (마스터 노드에서 kubectl 확인)"
ssh root@${IPS[0]} "export KUBECONFIG=/etc/kubernetes/admin.conf && kubectl get nodes -o wide"

3. 자주 발생하는 에러 & 해결법

❌ ERROR! the playbook: cluster.yml could not be found

  • 원인: Kubespray 디렉토리 안에서 실행하지 않았거나 경로 잘못됨
  • 해결: cd kubespray 후 실행

❌ FAILED! => {"msg": "Timeout (12s) waiting for privilege escalation prompt"}

  • 원인: SSH 접속은 되지만 sudo 권한 문제가 있음
  • 해결: --private-key 대신 -u root 옵션 추가, 또는 become: true 확인

❌ No package matching 'python3' found

  • 원인: 워커 노드에 Python3이 없을 경우 발생
  • 해결: 각 노드에서 dnf install -y python3 사전 설치

❌ CNI 네트워크 설치 실패

  • 원인: 기본 Calico가 네트워크 정책과 충돌하거나 IP 대역 충돌
  • 해결: inventory/mycluster/group_vars/k8s_cluster/k8s-net*.yaml 수정 
    kube_network_plugin: cilium   # Calico 대신 Cilium 사용

❌ Worker 노드 NotReady

  • 원인: 컨테이너 런타임(containerd) 설정 문제
  • 해결: 모든 노드에 containerd 정상 동작 확인 
    systemctl status containerd
journalctl -u containerd | tail -n 50

4. 설치 후 확인

# Control-plane 노드에서 실행
export KUBECONFIG=/etc/kubernetes/admin.conf
kubectl get nodes -o wide
kubectl get pods -A

모든 노드가 Ready 상태, 기본 Pod들이 정상 Running 상태여야 합니다.

✅ 결론

  • Kubeadm + Kubespray는 Rocky9.6 환경에서 가장 안정적인 자동화 Kubernetes 설치 방법입니다.
  • 위 스크립트를 실행하면 사전 준비 → Kubespray 세팅 → 인벤토리 생성 → 클러스터 설치 → 확인 단계가 자동으로 진행됩니다.
  • 에러 발생 가능 지점과 해결법까지 준비해 두면, 프로덕션 환경에서도 빠르게 대응할 수 있습니다.