306 lines
7.7 KiB
Markdown
306 lines
7.7 KiB
Markdown
# 쿠버네티스 클러스터 구축 가이드
|
|
|
|
## 📋 개요
|
|
|
|
이 문서는 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)
|