# 쿠버네티스 클러스터 구축 가이드 ## 📋 개요 이 문서는 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 키 기반 인증 설정 ```bash # 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 설정 (선택사항) ```bash # ~/.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이 활성화되어 있으면 제대로 동작하지 않습니다. ```bash # swap 비활성화 sudo swapoff -a # 영구적으로 비활성화 (재부팅 후에도 유지) sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab # 확인 (아무것도 출력되지 않으면 성공) swapon --show ``` ### 2단계: containerd 설정 ```bash # 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 (클러스터 초기화) ```bash sudo kubeadm init --pod-network-cidr=10.244.0.0/16 ``` **출력 결과 (중요 정보)**: - 클러스터 초기화 성공 - API 서버: https://10.10.0.74:6443 - 워커 노드 조인 토큰 생성됨 ### 4단계: kubectl 설정 일반 사용자가 kubectl을 사용할 수 있도록 설정합니다. ```bash 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 간 통신을 위한 네트워크 플러그인을 설치합니다. ```bash kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml ``` ### 6단계: 단일 노드 설정 마스터 노드에서도 워크로드를 실행할 수 있도록 taint를 제거합니다. ```bash kubectl taint nodes --all node-role.kubernetes.io/control-plane- ``` --- ## ✅ 구축 결과 ### 클러스터 상태 ```bash 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 상태 ```bash 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 | --- ## 📌 워커 노드 추가 (필요 시) 다른 서버를 워커 노드로 추가하려면: ```bash kubeadm join 10.10.0.74:6443 --token 4lfga6.luad9f367uxh0rlq \ --discovery-token-ca-cert-hash sha256:9bea59b6fd34115c3f893a4b10bacc0a5409192b288564dc055251210081c86e ``` **토큰 만료 시 새 토큰 생성**: ```bash kubeadm token create --print-join-command ``` --- ## 🔧 유용한 명령어 ### 클러스터 정보 확인 ```bash # 노드 상태 kubectl get nodes -o wide # 모든 Pod 상태 kubectl get pods -A # 클러스터 정보 kubectl cluster-info # 컴포넌트 상태 kubectl get componentstatuses ``` ### 문제 해결 ```bash # kubelet 로그 확인 sudo journalctl -u kubelet -f # containerd 로그 확인 sudo journalctl -u containerd -f # Pod 상세 정보 kubectl describe pod -n # Pod 로그 확인 kubectl logs -n ``` ### 클러스터 리셋 (초기화 실패 시) ```bash 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](docs/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 | ```bash # KUBECONFIG 생성 방법 (K8s 서버에서 실행) cat ~/.kube/config | base64 -w 0 ``` --- ## 📞 참고 정보 ### 서버 접속 ```bash # 새 서버 (쿠버네티스 클러스터) ssh -p 22 wace@112.168.212.142 # 기존 서버 (참조용) ssh -p 12991 geonhee@211.115.91.170 ``` ### 관련 문서 - [Kubernetes 공식 문서](https://kubernetes.io/docs/) - [kubeadm 설치 가이드](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/) - [Flannel 네트워크 플러그인](https://github.com/flannel-io/flannel)