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

## 📋 개요

이 문서는 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 <pod-name> -n <namespace>

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

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

```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)
