vexplor/kubernetes-setup-guide.md

쿠버네티스 클러스터 구축 가이드

📋 개요

이 문서는 Digital Twin 프로젝트의 쿠버네티스 클러스터 구축 과정을 정리한 가이드입니다.

작성일: 2024년 12월 22일

---

🖥️ 서버 정보

기존 서버 (참조용)

항목	값
IP	211.115.91.170
SSH 포트	12991
사용자	geonhee
OS	Ubuntu 24.04.3 LTS
K8s 버전	v1.28.0
컨테이너 런타임	containerd 1.7.28

새 서버 (구축 완료)

항목	값
IP	112.168.212.142
SSH 포트	22
사용자	wace
호스트명	waceserver
OS	Ubuntu 24.04.3 LTS
K8s 버전	v1.28.15
컨테이너 런타임	containerd 1.7.28
내부 IP	10.10.0.74
CPU	20코어
메모리	31GB

---

🔐 SSH 접속 설정

SSH 키 기반 인증 설정

# 1. 로컬에서 SSH 키 확인
ls -la ~/.ssh/

# 2. 공개키를 서버에 복사
ssh-copy-id -p 12991 geonhee@211.115.91.170  # 기존 서버
ssh-copy-id -p 22 wace@112.168.212.142        # 새 서버

# 3. 비밀번호 없이 접속 테스트
ssh -p 12991 geonhee@211.115.91.170
ssh -p 22 wace@112.168.212.142

SSH Config 설정 (선택사항)

# ~/.ssh/config 파일에 추가
Host wace-old
    HostName 211.115.91.170
    Port 12991
    User geonhee

Host wace-new
    HostName 112.168.212.142
    Port 22
    User wace

---

🚀 쿠버네티스 클러스터 구축 과정

1단계: Swap 비활성화

쿠버네티스는 swap이 활성화되어 있으면 제대로 동작하지 않습니다.

# swap 비활성화
sudo swapoff -a

# 영구적으로 비활성화 (재부팅 후에도 유지)
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# 확인 (아무것도 출력되지 않으면 성공)
swapon --show

2단계: containerd 설정

# containerd 기본 설정 생성
sudo containerd config default | sudo tee /etc/containerd/config.toml

# SystemdCgroup 활성화 (중요!)
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

# containerd 재시작
sudo systemctl restart containerd

# 상태 확인
sudo systemctl is-active containerd

3단계: kubeadm init (클러스터 초기화)

sudo kubeadm init --pod-network-cidr=10.244.0.0/16

출력 결과 (중요 정보):

• 클러스터 초기화 성공
• API 서버: https://10.10.0.74:6443
• 워커 노드 조인 토큰 생성됨

4단계: kubectl 설정

일반 사용자가 kubectl을 사용할 수 있도록 설정합니다.

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# 확인
kubectl cluster-info

5단계: 네트워크 플러그인 설치 (Flannel)

Pod 간 통신을 위한 네트워크 플러그인을 설치합니다.

kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

6단계: 단일 노드 설정

마스터 노드에서도 워크로드를 실행할 수 있도록 taint를 제거합니다.

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

---

✅ 구축 결과

클러스터 상태

kubectl get nodes -o wide

NAME	STATUS	ROLES	VERSION	INTERNAL-IP	OS-IMAGE	CONTAINER-RUNTIME
waceserver	Ready	control-plane	v1.28.15	10.10.0.74	Ubuntu 24.04.3 LTS	containerd://1.7.28

시스템 Pod 상태

kubectl get pods -n kube-system
kubectl get pods -n kube-flannel

컴포넌트	상태
etcd	✅ Running
kube-apiserver	✅ Running
kube-controller-manager	✅ Running
kube-scheduler	✅ Running
kube-proxy	✅ Running
coredns (x2)	✅ Running
kube-flannel	✅ Running

---

📌 워커 노드 추가 (필요 시)

다른 서버를 워커 노드로 추가하려면:

kubeadm join 10.10.0.74:6443 --token 4lfga6.luad9f367uxh0rlq \
    --discovery-token-ca-cert-hash sha256:9bea59b6fd34115c3f893a4b10bacc0a5409192b288564dc055251210081c86e

토큰 만료 시 새 토큰 생성:

kubeadm token create --print-join-command

---

🔧 유용한 명령어

클러스터 정보 확인

# 노드 상태
kubectl get nodes -o wide

# 모든 Pod 상태
kubectl get pods -A

# 클러스터 정보
kubectl cluster-info

# 컴포넌트 상태
kubectl get componentstatuses

문제 해결

# kubelet 로그 확인
sudo journalctl -u kubelet -f

# containerd 로그 확인
sudo journalctl -u containerd -f

# Pod 상세 정보
kubectl describe pod <pod-name> -n <namespace>

# Pod 로그 확인
kubectl logs <pod-name> -n <namespace>

클러스터 리셋 (초기화 실패 시)

sudo kubeadm reset
sudo rm -rf /etc/cni/net.d
sudo rm -rf $HOME/.kube
sudo iptables -F && sudo iptables -t nat -F && sudo iptables -t mangle -F && sudo iptables -X

---

📂 다음 단계: 자동 배포 설정

쿠버네티스 클러스터 구축이 완료되었습니다. 다음 단계로 진행할 사항:

1. Ingress Controller 설치 (외부 트래픽 라우팅) ✅ 완료
2. Cert-Manager 설치 (SSL 인증서 자동 관리)
3. Harbor/Registry 연동 (컨테이너 이미지 저장소)
4. CI/CD 파이프라인 구성 (Gitea Actions) ✅ 완료
5. Helm 설치 (패키지 관리)
6. 애플리케이션 배포 (Deployment, Service, Ingress) ✅ 완료

Gitea Actions 자동 배포 설정 완료

자세한 설정 방법은 KUBERNETES_DEPLOYMENT_GUIDE.md 참조

생성된 파일 목록

.gitea/workflows/deploy.yml          # Gitea Actions 워크플로우
k8s/
├── namespace.yaml                   # 네임스페이스 정의
├── vexplor-config.yaml             # ConfigMap
├── vexplor-secret.yaml.template    # Secret 템플릿
├── vexplor-backend-deployment.yaml # 백엔드 Deployment/Service/PVC
├── vexplor-frontend-deployment.yaml# 프론트엔드 Deployment/Service
├── vexplor-ingress.yaml            # Ingress 설정
├── local-path-provisioner.yaml     # 스토리지 프로비저너
└── ingress-nginx.yaml              # Ingress 컨트롤러 패치

Gitea Repository Secrets 설정 필요

Secret 이름	설명
HARBOR_USERNAME	Harbor 사용자명
HARBOR_PASSWORD	Harbor 비밀번호
KUBECONFIG	base64 인코딩된 Kubernetes config

# KUBECONFIG 생성 방법 (K8s 서버에서 실행)
cat ~/.kube/config | base64 -w 0

---

📞 참고 정보

서버 접속

# 새 서버 (쿠버네티스 클러스터)
ssh -p 22 wace@112.168.212.142

# 기존 서버 (참조용)
ssh -p 12991 geonhee@211.115.91.170

관련 문서

• Kubernetes 공식 문서
• kubeadm 설치 가이드
• Flannel 네트워크 플러그인