HomeLab Infrastructure
Projects | | Links: Website | Wiki
유휴 노트북 한 대로 시작한 홈서버를, 베어메탈 미니PC + Proxmox + 멀티노드 Kubernetes + ArgoCD GitOps 파이프라인으로 발전시켜 운영했던 인프라입니다. 2026년 10월 운영을 종료하고, 호스팅하던 블로그·위키는 Cloudflare Pages로 이전했습니다.
담당: 하드웨어 구성, Proxmox/K8s 클러스터 구축, GitOps 파이프라인 구성, 운영, 이전
1. Overview
운영 종료 (2026.10)
이 홈랩은 2026년 10월에 운영을 종료했습니다. 블로그(kpryu.cloud)와 위키(wiki.kpryu.cloud)는 Cloudflare Pages로 옮겨 계속 서비스하고 있으며, 아래 내용은 운영 당시의 구성 기록입니다. 이전 과정은 아래 7. Retirement에 정리했습니다.
유휴 노트북 한 대로 Nginx + Self-hosted Runner 기반 CI/CD 서버를 구축한 것을 시작으로, 이후 미니PC(Ryzen 7 4700U, 16GB RAM)에 Proxmox VE 하이퍼바이저를 설치하고 멀티 노드 Kubernetes 클러스터로 발전시켰습니다.
운영 기간 동안 GitHub Actions(CI) + ArgoCD(CD) + Kustomize 기반 GitOps 파이프라인으로, 코드 푸시만으로 도커 이미지 빌드부터 프로덕션 배포까지 완전 자동화했습니다.
2. Phase 1: Idle Laptop CI/CD Server
Home Server Architecture
Architecture of the self-hosted CI/CD pipeline
- GitHub Actions Self-hosted Runner를 이용해 60초 안에 빌드-배포가 완료되는 CI/CD 파이프라인 구축
- Nginx로 정적 사이트 호스팅,
rsync --delete로 변경 파일만 동기화 - TLS(Let’s Encrypt, SSL Labs A+), iptables 기본 DROP, Fail2Ban, Google OTP 2FA. 이 구성은 Phase 2로 넘어오며 Kubernetes 기반으로 대체됨
3. Phase 2: Proxmox K8s GitOps Platform (~2026.10)
Architecture
User → Public IP (kpryu.cloud, Cloudflare DNS + DDNS)
→ LG U+ Router (Port Forwarding 80/443)
→ MetalLB VIP (192.168.219.240)
→ Nginx Ingress Controller
→ Services (kpryu.cloud, wiki.kpryu.cloud, lab.kpryu.cloud)
Infrastructure Layer
| 구성요소 | 기술 |
|---|---|
| Hypervisor | Proxmox VE 9.x |
| K8s | Multi-node cluster (1 Master + 2 Worker) |
| Load Balancer | MetalLB (L2 mode) |
| Ingress | Nginx Ingress Controller |
| TLS | cert-manager + Let’s Encrypt, Cloudflare DNS-01 와일드카드 (자동 갱신) |
| DNS | Cloudflare DNS + 클러스터 내 DDNS 파드(공인 IP 갱신), Pi-hole(집 안 Split-Horizon) |
| VPN | Tailscale (원격 관리) |
CI/CD Pipeline (GitOps)
| 단계 | 도구 |
|---|---|
| Source | GitHub Monorepo (paths 필터로 독립 빌드) |
| Build | GitHub Actions Self-hosted Runner (AMD64 VM) |
| Registry | Docker Hub |
| Manifest | Kustomize (별도 매니페스트 레포) |
| Deploy | ArgoCD (Pull-based Sync) |
Hosted Applications
| 서비스 | 프레임워크 | 경로 |
|---|---|---|
| Main Blog | Jekyll (Hydejack) | kpryu.cloud |
| Tech Wiki | Hugo (PaperMod) | wiki.kpryu.cloud |
| HomeLab Dashboard | Homepage (gethomepage) | lab.kpryu.cloud, LAN .242 |
4. Key Troubleshooting
| # | 이슈 | 원인 | 해결 |
|---|---|---|---|
| 1 | Exit 139 (Segfault) | Alpine musl libc vs Ruby C 확장 충돌 | Debian-slim 멀티 스테이지 빌드로 전환 |
| 2 | cert-manager 무한 Pending | NAT Loopback - 공유기가 내부→공인IP→내부 차단 | CoreDNS에 Split-Horizon DNS 적용 |
| 3 | exec format error | Mac(ARM64)에서 빌드 → 서버(AMD64) 불일치 | Self-hosted Runner VM에서 네이티브 빌드 |
| 4 | Nginx 403 on sub-path | Ingress /wiki 경로와 컨테이너 내부 경로 불일치 | Docker COPY 목적지를 /html/wiki로 조정 |
| 5 | ArgoCD repo-server Unknown | 네트워크 순단으로 파드 좀비 상태 | --force --grace-period=0 강제 삭제 후 재동기화 |
| 6 | Dynamic IP Timeout | ISP IP 변경 + DDNS 갱신 누락 | 수동 갱신 후 Cloudflare DDNS 파드로 자동화 (2026-09) |
| 7 | Ingress 어노테이션 거부 | ingress-nginx 웹훅이 permanent-redirect의 $request_uri 거부 | 구 도메인 301을 앱 컨테이너 nginx에서 처리 |
5. Security
| 영역 | 적용 내용 |
|---|---|
| TLS | cert-manager + Let’s Encrypt, DNS-01 와일드카드 (자동 갱신) |
| 노출 범위 | 공개: 포트폴리오, 위키, 대시보드 / LAN 전용: ArgoCD, Proxmox, Pi-hole |
| 대시보드 권한 | 공개 대시보드의 K8s 위젯은 노드 메트릭만 읽는 ServiceAccount |
| 시크릿 | Cloudflare API 토큰은 존 하나로 범위 제한, git 밖에서 Secret으로만 주입 |
| 원격 접근 | Tailscale (pve 호스트, subnet route) |
6. Results
| 지표 | Phase 1 | Phase 2 |
|---|---|---|
| 배포 시간 | 60초 (rsync) | ~3분 (GitOps 자동) |
| 인프라 | 노트북 1대, Nginx | Proxmox + K8s 3노드 |
| 서비스 | 블로그 1개 | 블로그 + 위키 + 대시보드 |
| 무중단 갱신 | nginx reload (0초) | Ingress 무중단 설정 변경 반영 |
| 클라우드 비용 | 추가 비용 없음 | 추가 비용 없음 (자가 호스팅, 전기/장비 비용 별도) |
| SSL | Certbot A+ | cert-manager 자동 갱신 |
7. Retirement: Cloudflare Pages 이전
미니PC를 다른 용도로 쓰게 되면서 홈랩 운영을 종료했습니다. 외부에 공개하던 서비스는 정적 사이트였기 때문에, 서버 없이 운영할 수 있는 Cloudflare Pages로 옮겼습니다.
| 항목 | 홈랩 (Phase 2) | 이전 후 |
|---|---|---|
| 빌드 | Self-hosted Runner에서 Docker 이미지 빌드 | GitHub-hosted Runner에서 jekyll build / hugo build |
| 배포 | 매니페스트 태그 갱신 → ArgoCD Sync | wrangler pages deploy로 Cloudflare Pages에 직접 업로드 |
| DNS | Cloudflare A 레코드 + 클러스터 DDNS 파드 | Pages 커스텀 도메인 (Cloudflare 관리) |
| TLS | cert-manager DNS-01 와일드카드 | Cloudflare 관리 인증서 |
| 서비스 | 블로그 + 위키 + 대시보드 | 블로그 + 위키 (대시보드는 종료) |
- 무중단 전환:
*.pages.dev에서 먼저 검증하고, DDNS 대상에서 도메인을 뺀 뒤 DNS를 전환한 다음, 마지막으로 클러스터 리소스를 정리하는 순서로 진행 - 정리: Docker 빌드 파일, 이미지 태그를 갱신하던 PAT 등 더 이상 쓰지 않는 시크릿과 홈 DNS(Pi-hole) 의존성 제거
8. Used Skills
- Proxmox VE
- Kubernetes (K3s → kubeadm)
- MetalLB, Nginx Ingress Controller
- cert-manager, Let’s Encrypt
- GitHub Actions (Self-hosted Runner)
- ArgoCD, Kustomize
- Docker (Multi-stage Build)
- Jekyll, Docusaurus, Nginx
- Pi-hole (DNS), Tailscale (VPN)
- iptables, Fail2Ban, Google OTP
- DDNS (No-IP → Cloudflare)
- Cloudflare Pages, Wrangler
- Prometheus, Grafana
