목표

현재 외부에 있는 홈 서버 환경을 조금 더 체계적이고 구조적으로 관리해 보고자 이 시리즈를 시작한다. 단순한 토이 프로젝트용 서버가 아니라, 고가용성(HA)을 갖춘 쿠버네티스(Kubernetes) 클러스터와 대규모 언어 모델(LLM) 서빙까지 고려한 멋진 구성을 한번 해보려 한다.

🖥️ 현재 보유 하드웨어 및 인프라 구성

물리적인 PC 및 네트워크 장비 구성은 다음과 같다.

Master Nodes (3대): Intel NUC (소형 폼팩터, 저전력으로 24시간 컨트롤 플레인 유지)
Worker Nodes (3대): Xeon 프로세서 기반 워크스테이션 (주요 워크로드 처리)
VM Machine (1대): 42 Core 기반의 고성능 서버 (KVM/Proxmox 기반 워커 노드 추가 및 테스트 환경 프로비저닝 용도)
AI/LLM Server (1대): Mac Studio M3 Max 128GB (로컬 LLM 모델 호출 및 서빙 전용)
Network: Ubiquiti UniFi USG-Pro-4 (방화벽/라우터) & US 24 PoE 250W (스위치)

아래는 현재 구성되어 있는 인프라의 네트워크 토폴로지다.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1e1e1e', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#333', 'lineColor': '#007aff', 'background': '#121212', 'clusterBkg': '#1a1d24', 'clusterBorder': '#333' }}}%%
graph TD
    %% 상단 ISP 및 유니파이 장비 세팅
    ISP(("🌐<br>ISP"))
    USG["🖧<br>USG-Pro-4"]
    SW["🖧<br>US 24 PoE 250W"]

    ISP --- USG
    USG --- SW

    %% K8s 마스터 노드 그룹
    subgraph K8S_Master ["🔹 Kubernetes Master Nodes"]
        M1["🗄️<br>master-1"]
        M2["🗄️<br>master-2"]
        M3["🗄️<br>master-3"]
    end

    %% K8s 워커 노드 그룹
    subgraph K8S_Worker ["🔹 Kubernetes Worker Nodes"]
        W1["💻<br>worker-1"]
        W2["💻<br>worker-2"]
        W3["💻<br>worker-3"]
    end

    %% 인프라 및 기타 장비 그룹
    subgraph Infra ["🔸 Infrastructure & Devices"]
        BAS["🖥️<br>bastion"]
        MAC["🔲<br>mac studio"]
        CTRL["📟<br>controller"]
        KT1["📡<br>KT router1"]
        KT2["📡<br>KT router2"]
    end

    %% MAC 주소 기반 가상머신/기기 그룹
    subgraph VMs["🔸 VMs (KVM/QEMU) & Others"]
        C1["💻<br>00:e0:24:3b:02:85"]
    end

    %% 스위치에서 각 기기들로 연결
    SW --- M1
    SW --- M2
    SW --- M3
    
    SW --- W1
    SW --- W2
    SW --- W3
    
    SW --- BAS
    SW --- MAC
    SW --- CTRL
    SW --- KT1
    SW --- KT2
    
    SW --- C1


    %% 색상 및 스타일 지정
    classDef default fill:#222,stroke:#444,stroke-width:1px,color:#ddd;
    classDef unifi fill:#2d3139,stroke:#007aff,stroke-width:2px,color:#fff;
    classDef isp fill:none,stroke:none,color:#007aff,font-weight:bold;

    class ISP isp;
    class USG,SW unifi;
    linkStyle default stroke:#007aff,stroke-width:2px;

위 환경을 바탕으로, 앞으로 하나씩 설정하고 구축해 나갈 계획들을 4개의 Phase로 나누어 정리해 보았다. 앞으로 각 Phase를 진행하며 겪는 트러블슈팅과 설정 과정들을 개별 게시글로 풀어갈 예정이다. 일부는 게시글을 쓰기 전에 검증하였고, 일부는 계획이므로 순서라던지 이런게 변경 될 수 있다.

🛠️ 구축 마일스톤 (Action Plan)

Phase 1: 네트워크 설계 및 보안 구성 (UniFi)

핵심 인프라가 외부에 노출되는 것을 최소화하고, 안전한 원격 관리를 위한 기반 네트워크를 공사하는 단계.

VLAN 망 분리: UniFi Network에서 관리망/K8s 노드망(VLAN 20) 및 외부 서비스용 망(VLAN 30) 분리.
Static IP (고정 IP) 할당: 스위치에 물린 모든 물리 장비(NUC, Xeon, Mac Studio 등)의 MAC 주소를 기반으로 고정 IP 부여.
방화벽(Firewall) 룰 설정: 망 격리를 통한 보안 강화 (K8s 내부망에서 외부로 나가는 트래픽 제어 및 접근 통제).
원격 VPN 구성: 외부에서 안전하게 관리망에 접근하기 위한 VPN 구축. (※ USG-Pro-4 장비 특성상 WireGuard 공식 지원이 되지 않았고, 기본 기능인 L2TP VPN을 구성하거나 Bastion 호스트에 Tailscale 서브넷 라우터를 올려 우회 접속망 구축 예정)

Phase 2: 인프라 OS 세팅 및 프로비저닝 (Pre-K8s)

쿠버네티스를 올리기 전, 물리 머신들과 가상 머신들의 OS 환경을 일치시키고 자동화 준비를 하는 단계.

해당 사항은, ansible 이라던지 IaC 구성을 통해 진행해 볼 예정이다.

Bastion(배스천) 호스트 구성: 내부망 접근 및 K8s 배포(Ansible)를 총괄할 중앙 통제 서버 세팅.
SSH Key 배포 및 패스워드리스 설정: Bastion 호스트에서 모든 Master/Worker 노드 및 VM 머신으로 비밀번호 없이 접근 가능하도록 SSH Key 연동.
OS 기본 최적화: 모든 노드의 Swap 메모리 비활성화, 방화벽(ufw) 포트 개방, 타임존 및 NTP 동기화.
VM 하이퍼바이저 구축: 42 Core 머신에 Proxmox 또는 KVM을 세팅하여, 언제든 K8s 워커 노드로 합류시킬 수 있는 가상머신 템플릿(Cloud-init 등) 제작.

Phase 3: K8s HA 클러스터 구축 (Kubespray)

수동 설치(kubeadm) 대신 **Kubespray (Ansible 기반)**를 활용하여 여러 대의 노드를 한 번에 프로비저닝하고 쉽게 스케일 아웃할 수 있는 환경을 구축하는 단계.

Kubespray Inventory 작성: Bastion 호스트에서 inventory.ini를 구성하여 마스터 3대, 워커 3대(+VM 워커)의 롤(Role) 정의.
Kube-vip 설정 (Control Plane HA): Kubespray 설정 파일(all.yml, k8s-cluster.yml)에 kube-vip를 활성화. 마스터 노드 3대를 묶어줄 **단일 VIP (예: 192.168.20.10)**를 할당하여 API 서버 로드밸런싱 구현.
CNI (컨테이너 네트워크 인터페이스) 선택: 기본 Calico 대신 eBPF 기반의 고성능 네트워크 처리가 가능한 Cilium으로 변경하여 배포.
클러스터 자동 배포: ansible-playbook 명령어를 통해 원클릭으로 K8s 클러스터 전체 배포 및 검증.

Phase 4: K8s 필수 공사 및 데브옵스(DevOps) 플랫폼 구축

K8s 클러스터 위에 트래픽 진입점과 영구 스토리지를 구성하고, 그 기반 위에 소스코드 관리, CI/CD, 사내 위키 등 자체 데브옵스 생태계를 올리는 최종 단계.

트래픽 및 스토리지 기반 공사 (필수 Add-on):
- MetalLB & Ingress Nginx: 클러스터 외부 트래픽을 내부 서비스로 연결하기 위한 로드밸런서 및 인그레스 컨트롤러 설치.
- 스토리지 클래스 (Longhorn / NFS CSI / openEBS): GitLab이나 DB처럼 데이터 영구 저장이 필요한 앱을 위해, 워커 노드나 42 Core VM을 활용한 분산/공유 스토리지 구축.
GitLab 구축 (소스코드 및 CI/CD): Helm Chart를 이용하여 K8s 클러스터 내부에 자체 GitLab 인스턴스와 GitLab Runner 배포. 향후 개인 프로젝트 소스 관리 및 컨테이너 빌드 파이프라인으로 활용.
Wiki.js 구축 (사내 지식 관리): 인프라 아키텍처, K8s 매뉴얼, 트러블슈팅 기록 등을 체계적으로 문서화하기 위한 Wiki.js (및 PostgreSQL) 배포.
ArgoCD 도입 (GitOps 자동화 - 선택 사항): GitLab에 푸시된 Kubernetes 매니페스트(YAML/Helm) 변경 사항을 감지하여 K8s 클러스터에 자동으로 동기화하는 GitOps 배포 환경 구축.
Mac Studio (LLM) 연동: 쿠버네티스 외부(External)에 있는 Mac Studio의 LLM API 서버를 K8s 내부 서비스처럼 호출할 수 있도록 ExternalName Service로 연결. (추후 GitLab CI 코드 리뷰 자동화나 사내 챗봇 등에 활용 예정)

실제로 아는 후배와 형 덕분에, 여러 경험을 진행해 본다. 고 가용성 구성 및 여러가지의 고려를 진행한 뒤에 위 내용을 구성해 볼 생각이다.

좋은 의견이 있으면 댓글을 주시면 감사 하겠습니다.