부산대학교 클라우드 플랫폼(Pickle)의 인프라 계층이 어떻게 구성돼 있는지 보여주는 공개 예시본입니다. 실제 인프라 레포지토리는 비공개이며, 여기에는 프로비저닝·배포·검증 스크립트와 호스트 설정을 옮겨 담고 민감한 값을 치환해 두었습니다.
여기 적힌 IP 주소와 관리 포트, 볼트 경로는 실제 값이 아닙니다. 아래 무엇을 바꿨나에 치환 목록이 있습니다. 도메인 이름은 치환하지 않았습니다 — 이 플랫폼이 서비스하는 이름이라 공개돼 있고, 가려 두면 스크립트가 무엇을 하는지 읽을 수 없게 됩니다.
플랫폼 전체는 PNUops 프로필에서, 애플리케이션 코드는 pickle-api와 pickle-console 같은 공개 레포지토리에서 볼 수 있습니다.
캠퍼스 방화벽이 인바운드를 막기 때문에 오프캠퍼스 SSH는 외부 릴레이가 받아, 캠퍼스가 아웃바운드로 개통한 WireGuard 터널로 넘깁니다.
pickle.example.ac.kr ──┐ 외부 릴레이 (오프캠퍼스 SSH)
*.example.dev ──┤ :80/:443 HAProxy(send-proxy-v2)
▼ │ 캠퍼스발 아웃바운드 WireGuard
pve-node (Proxmox VE) ────────────────────────────┘
├─ vmbr1 (인프라)
│ ├─ LXC 100 reverse-proxy nginx(HTTP vhost·SNI 스트림) + proxy-agent + certbot
│ ├─ LXC 101 pickle-app PostgreSQL + pickle-api + nginx(콘솔 정적·/api 프록시)
│ └─ LXC 102 pickle-sshgw proxyfront + sshpiperd + 터미널 브리지 + WireGuard 종단
└─ vmbr2 (사용자, 격리) 사용자 VM (Ubuntu cloud-init 템플릿에서 클론)
비Proxmox 노드:
├─ gpu-node aarch64 GPU 노드 캠퍼스망 192.0.2.20 — vLLM 서빙 :8000 (pickle-vllm)
└─ dept-node x86 서버(Ubuntu) dept-node.example.ac.kr:22 — 학과 공유 서버
Proxmox 운영 후보 (클러스터 구성, 플랫폼 미등록):
├─ pve-node-2 x86 서버 캠퍼스망 192.0.2.30, pve-node와 같은 L2
└─ pve-node-3 x86 서버, GPU 1장 캠퍼스망 192.0.2.31, GPU는 vfio-pci 부팅 시 바인딩, 패스스루 실측 완료 2026-09-08, 플랫폼 미등록
vmbr1은 인프라 전용, vmbr2는 사용자 전용이고 둘 사이에 직접 경로가 없습니다. 산출물은
전부 셸과 마크다운입니다. 주 대상은 Proxmox 호스트이고, 플랫폼에 편입된 비Proxmox
노드의 편입 절차도 함께 다룹니다. dept-node의 기존 Ubuntu와 Docker를 유지하는 PBS VM,
qnetd 설치와 복구 절차를 제공합니다. pve-node-2와 pve-node-3은 NetBird에 등록된 빈
example-prod 클러스터입니다. 순차 재부팅 후 관리 SSH와 HTTPS, 정족수 복귀를 확인했습니다.
GPU 노드는 호스트 GPU 시험의 NVIDIA와 CUDA 실행 패키지를 제거하고 VFIO 바인딩과
nouveau/nova 차단을 유지합니다. 두 Proxmox 노드는 플랫폼 배치 대상으로 등록하지 않았습니다.
플랫폼은 VM 신청·승인·생성, SSH와 웹 터미널 접속, 도메인 공개, 만료와 삭제까지를 다룹니다. 이 레포지토리가 맡는 부분은 아래와 같습니다.
- 프로비저닝: 호스트 위의 컨테이너와 사용자 VM 템플릿을 스크립트로 만듭니다.
- 배포: 각 서비스를 올리고, 헬스 체크를 통과하지 못하면 직전 상태로 되돌립니다.
- 정책 적용: TLS 암호군, 로그 보존, 인그레스 설정 같은 호스트 정책을 한 번에 맞춥니다.
- 점검: 살아 있는 시스템에 실제 요청을 보내는 스모크와 읽기 전용 헬스 스냅샷으로 상태를 확인합니다.
- 예약 작업: 백업과 헬스체크를 타이머로 돌리고, 실패가 조용히 묻히지 않게 기록과 알림을 붙입니다.
- 파괴적 변경 전에 백업합니다. 설정 파일을 덮어쓰는 스크립트는 손대는 파일을 타임스탬프 폴더에 먼저 복사합니다.
- 배포는 readiness 게이트를 통과해야 끝납니다.
deploy-api.sh는 새 jar로 서비스를 올린 뒤 readiness가 통과하지 못하면 직전 아티팩트로 되돌립니다. 되돌리기 전에 api 저널 마지막 150줄을 찍습니다. 기동 실패는 유닛이failed로 눕지 않고 재시작을 반복하므로, 그 출력이 원인을 볼 수 있는 자리입니다. SMTP 같은 외부 dependency는 별도 전체 health가 감시합니다.deploy-sshgw.sh는 바이너리 세 개를 한 세트로 원자 교체해, 절반만 새 버전인 상태를 만들지 않습니다. - 소스에서 빌드하는 배포 스크립트는 체크아웃을 갱신하지 않습니다. 빌드는
PICKLE_ROOT아래에 지금 있는 트리로 돕니다. 배포 전에 그 레포의 HEAD를 올리려는 커밋으로 맞추지 않으면 옛 트리가 빌드되고 배포는 그대로 성공하므로, readiness 게이트도 롤백도 이 상황을 잡지 못합니다. 둘 다 올라간 것이 건강한지만 보지 무엇이 올라갔는지는 보지 않기 때문입니다. 유닛과 설정을 반영하는 스크립트도 빌드만 안 할 뿐 같은 트리에서 읽습니다. - 정제 검사에 셀프테스트가 붙어 있습니다.
sanitization-check.sh는 매 실행마다 합성 위반 케이스로 자기 검사 로직이 살아 있는지 먼저 확인한 뒤 본 검사를 수행합니다. - 주기 작업의 실패가 남습니다.
cron-wrap.sh가 성공과 실패 마커를 기록하고, systemdOnFailure가ops-unit-failed.sh로 알림을 띄웁니다.
hosts/pve-node/ 호스트 네트워크 설정, systemd 유닛과 타이머 // 백업·헬스체크·실패 알림
lightsail/ 외부 릴레이 설정: HAProxy, nftables, WireGuard, sysctl, 커널 모듈
scripts/ 프로비저닝·배포·정책 적용·검증·스모크
runbooks/ 운영 절차 // 이 예시본에는 일부만 포함
호스트별 설정 파일은 hosts/<이름>/ 아래에 둡니다. 새 노드의 디렉터리는 첫 설정
산출물이 생길 때 만들고, 편입 자체는 runbooks/node-intake.md(비Proxmox 노드)나
runbooks/proxmox-node-intake.md(기존 플랫폼에 더하는 Proxmox 노드)를 따릅니다.
| 분류 | 스크립트 |
|---|---|
| 프로비저닝 | create-app-lxc.sh, create-sshgw-lxc.sh, bootstrap-backup-host.sh, create-pbs-vm.sh, install-pbs-guest.sh, bootstrap-isolated-core.sh, bootstrap-isolated-services.sh |
| 노드 등록 | register-node.py (실측, 기본 dry-run, 신규 MAINTENANCE, 기존 IP pool 연결과 예약 용량 기록) |
| 전용 관리 계정 | provision-operator-access.py, revoke-operator-access.py (기본 사전 검사, 새 pickle 계정에 비밀번호 없는 전체 root sudo 권한 등록 및 회수) |
| 배포 | deploy-api.sh, deploy-console.sh, deploy-proxy-agent.sh, deploy-relay.sh, deploy-sshgw.sh, sync-systemd-units.sh, apply-gpu-node-vllm.sh |
| 정책 적용 | apply-tls-ciphers.sh, apply-terminal-ingress.sh, apply-log-retention.sh, apply-main-domain-vhost.sh, apply-ops-timers.sh, apply-platform-inventory.sh, apply-settings.sh, apply-terms.sh, apply-os-catalog.sh, register-image.py, apply-relay-token.sh, apply-production-sdn.sh, apply-production-network.sh |
| 운영 | db-backup.sh, db-pbs-backup.sh, health-check.sh, cron-wrap.sh, ops-unit-failed.sh, enroll-backup-peer.sh, configure-qnetd.sh, check-backup-host.py, check-backup-storage.py, activate-qdevice.py |
| 검증 | verify.sh, sanitization-check.sh, hook-verify.sh, verify-production-network.py |
| 스모크 | smoke-provisioning.sh, smoke-llm-key-lifecycle.sh, smoke-http-publish.sh, smoke-ssh-gateway.sh, smoke-web-terminal.sh, smoke-account-ops.sh, smoke-dashboards-notify.sh, smoke-prod.sh |
create-pbs-vm.sh는 명시한 UEFI loader와 vars template을 host capability 및 firmware
descriptor와 대조합니다. cloud-init seed는 read-only virtio block으로 연결합니다.
apply-settings.sh는 누락된 런타임 설정 키를 추가하고 기존 값은 유지합니다. GPU 미연결
검토 시간과 저사용 판단 기간, 유지 결정 후 재검토 유예의 초기값은 12시간입니다.
관리자 콘솔의 플랫폼 설정에서 변경하면 이후 판정이 변경값을 읽습니다. GPU 임대 기간은
신청과 승인에서 직접 입력합니다.
PBS 준비 도구는 Ubuntu 22.04 amd64의 libvirt와 네트워크를 유지하며 Debian 13 전용 VM을
만듭니다. 새 boot 64 GiB/data 1 TiB와 4 vCPU/8 GiB를 사용하고, NetBird peer와 host qnetd를
별도로 구성합니다. 기본 실행은 사전 검사이며 --apply를 지정해야 변경합니다.
검증한 cloud image SHA256과 운영자 SSH 공개키, 실제 hostname과 보호 backup 경로가 필요합니다.
설치 기준은 PBS 4.2.5-1, NetBird 0.78.2, qnetd 3.0.1-1입니다.
절차와 복구 범위는 백업 호스트 런북에 있습니다.
첫 root 실행은 bootstrap-backup-host.sh --expected-host <hostname> --check입니다.
check-backup-storage.py는 hash로 고정한 portable SMART/PERC 도구를 읽기 진단에 사용합니다. 패키지나 서비스를 설치하지 않습니다.
전용 관리 계정의 준비·등록·철회는 운영자 접근 런북을 따릅니다. 기존 도구로 disk/RAID 상태만 수집하며, 확인하지 못한 RAID 상태를 정상으로 표시하지 않습니다. 인증서 등록을 마친 PVE 두 노드에서는 qdevice 활성화 런북에 따라 설정 잠금과 TLS 및 정족수 확인을 진행합니다.
운영 SDN 도구는 hosts/production/network.json을 입력으로 사용합니다. 예시 운영망은
100.65.0.0/16과 100.66.0.0/16이며 기존 개발망 198.18.0.0/16·198.19.0.0/16과
mesh 100.64.0.* 예시를 구분합니다. 실제 배포 전에는 이 예약 주소를 해당 환경에 맞게 교체합니다.
PVE와 NetBird의 기존 firewall을 유지하며, guest 정책을 우회하는 mark와 VLAN frame을
별도 guard로 처리합니다.
기본 실행은 사전 검사이고 실제 적용은 아직 수행하지 않았습니다. 생성된 SDN 파일을 수동으로
편집하지 않는 부팅·rollback 절차는 운영 네트워크 런북에 있습니다.
격리 core 도구는 Debian 13 템플릿으로 PostgreSQL 18과 Java 25 실행 환경을 준비합니다.
새 게스트의 eth0 MTU는 소유권 확인 직후 /etc/network/if-pre-up.d/isolated-core-mtu
hook으로 지속 적용하고, APT 전에 ip -j link readback으로 검증합니다.
대상 노드와 CTID, private 주소, 검증한 패키지 버전 및 새 자격증명 파일을 명시합니다.
API는 isolated profile, 시작을 막는 marker와 비활성 job/정책/vendor 설정을 적용한 상태로
남습니다. 별도 --bootstrap-admin one-shot은 host/CT/machine/DB identity와 빈 DB를 확인한
뒤 SYS_ADMIN과 PERSONAL workspace만 만들며, postcheck 뒤 marker를 만들고 서비스를
disabled 상태로 둡니다. 카탈로그, 기존 데이터 이관과 공개 진입은 후속 작업입니다. 실제 설치와 전체 서비스 복구 검증은
격리 core 런북의 순서와 소유권 확인을 따릅니다.
DB/PBS 도구는 Python 3와 proxmox-backup-client, source의 PostgreSQL 18 client를
사용합니다. 기본 실행은 계획 출력이며 실제 백업은 --run으로 시작합니다. DB dump를
암호화하여 업로드하고 실제 복원한 파일의 hash를 대조한 뒤 별도 검증 receipt를 게시합니다.
다른 호스트의 monitor는 현재 PBS 증거로 10분 경고와 15분 실패를 판단합니다. timer와
메일은 별도 설치 및 활성화가 필요합니다. 키 보관, 보존 정책과 전체 서비스 복원 시험은
DB/PBS 런북에 있습니다. 사용자 VM 정기 백업은 이 도구의 대상이 아닙니다.
스모크는 목이 아니라 살아 있는 시스템에 실제 요청을 보냅니다. smoke-provisioning.sh는
회원가입부터 인증, 워크스페이스 생성, VM 신청, 관리자 승인, 프로비저닝 완료 대기, SSH 도달 확인,
전원 왕복, 삭제, DB 정합 검증까지 한 번에 통과시킵니다.
smoke-llm-key-lifecycle.sh는 LLM gateway까지 배포한 뒤 평문 키를 출력하지 않고 실제
1-token 호출과 snapshot 기반 정지·재개·폐기 반영을 확인합니다. 이 일반 lifecycle은
OpenRouter 사업 account가 없어도 실행할 수 있도록 금액 한도를 0으로 둔 TOKEN 축 smoke입니다.
호출 모델은 기본 pickle-general이며 다른 TOKEN 모델을 검증할 때만 LLM_SMOKE_MODEL로
바꿉니다. 지정한 모델이 gateway /models에 없으면 호출 전에 실패합니다.
양수 CREDIT 최초 binding과 cross-org account isolation은 실제 account 준비·binding ON 뒤 별도
smoke를 구현해 검증해야 하며 현재 이 script의 coverage가 아닙니다.
사용자 VM 템플릿을 만드는 빌드 레시피는 이 레포지토리에 없습니다. 공개 레포지토리 pickle-image-builder가 그 역할을 맡습니다.
node-registration.md는 Proxmox 노드 단독 등록과 core·복구 용량 예약,
활성화 전 검증을 설명합니다.
이 예시본에는 proxmox-api-principal.md(Proxmox API 서비스 principal 권한 분리와 token custody), new-environment.md(신규 환경 관통 구축 순서 — 환경별로 바꿀 값 표와
사람만 할 수 있는 단계·절차가 없는 지점 명시), node-intake.md(비Proxmox 노드 편입 절차 —
실측 체크리스트, 운영자 접속 키 설치, 대역외 관리 평면 점검), drift-resolution.md(DB와
하이퍼바이저 상태가 어긋났을 때의 판정 절차), db-restore.md(백업 복원),
inventory-readiness.md(IP pool 한 건 등록과 MAINTENANCE 노드의 VM 방화벽 opt-in 준비),
template-replication.md(중지 VM template의 검증된 VMA archive 복제와 실패 정리),
isolated-core-bootstrap.md(새 API/콘솔과 별도 DB LXC의 private TLS 연결 및 기동 제한),
isolated-service-core.md(새 후보 proxy/SSH gateway LXC의 방화벽 우선 준비와 서비스 정지 인계), pbs-egress.md(DB LXC의 PBS TCP 8007 egress와 state-guarded 재적용),
db-pbs-backup.md(플랫폼 DB의 암호화 PBS 백업, 독립 복구점 감시 및 같은 서비스의 수동 복원),
gpu-node-vllm.md(GPU 노드 vLLM 서빙 운영 — 시작·종료, 모델·플래그 교체와 롤백, 장애
복구, 재부팅), proxmox-node-intake.md(Proxmox 노드 후보 인수 절차 초안 — 초기화 전
실측, 설치 전 결정 항목, standalone 설치, 등록 전에 실행하면 안 되는 스크립트),
gpu-passthrough.md(GPU 패스스루 — Resource Mapping 생성, 토큰 최소 권한, VM 모양(rombar=0),
붙이기·떼기·인계, 카드 상태 확인과 손실 대응, 시험 게스트 정리)를 담았습니다. 나머지 재구축과 복구 절차는 비공개 레포지토리에 둡니다.
scripts/verify.sh # shellcheck, 설정 초기화, core, DB 백업, SDN, qdevice와 인벤토리 등록 테스트, 정제와 스케줄 유닛 검사verify.sh는 커밋 전 필수입니다. shellcheck 위반이 하나라도 있으면 실패하고, 이어서 도는
정제 검사는 이 샘플에 실제 주소나 실제 값이 섞이지 않았는지 확인합니다.
기본 검증은 설정 초기화, disk 진단 수집기, 격리 core, DB/PBS 백업, 운영 SDN, qdevice 활성화와 노드 등록의
일곱 테스트 묶음을 실행합니다. 호스트 설정이나 운영 DB를 변경하지 않습니다. 노드 등록의
실제 SQL 검증 두 건은 별도 선택 사항이며, 로컬 Docker에 있는 PostgreSQL image digest를
PICKLE_TEST_POSTGRES_IMAGE에 지정하고 python3 -B scripts/tests/test_node_registration.py로
실행합니다. 이 시험은 네트워크가 차단된 임시 컨테이너를 만들고 종료 후 정리합니다.
설정 초기화 테스트는 Python 3와 jq를 사용합니다. 호스트에 연결하지 않고 로컬 SQL 픽스처로 스크립트를 두 번 실행해 기존 설정값과 수정 시각이 유지되는지 검사합니다. PostgreSQL의 타입 검사와 실제 컨테이너 연결은 이 테스트의 범위에 포함하지 않습니다. 격리 core 테스트는 Python 3 표준 라이브러리로 입력 검증과 기존 자원 보호, TLS 및 서비스 기동 조건을 확인합니다. 후보 서비스 core 테스트는 candidate token 분리, 닫힌 포트, onboot 0, artifact checksum readback, package endpoint 사전 검사와 guest transient unit의 process-group timeout, firewall/network/service 순서를 확인합니다. 둘 다 실제 PVE 호스트에 접속하거나 컨테이너를 만들지 않습니다. DB 백업 테스트는 PBS 응답을 대신하는 메모리 객체로 snapshot 누락, 복원 대조 실패, 조회 지연과 알림 재시도를 확인합니다. 실제 DB/PBS/SMTP 접속과 서비스 복구는 별도 시험입니다.
원본에서 이 레포지토리로 옮기며 치환한 값입니다. 아래는 전부 실제 값이 아닙니다. 도메인 이름은 이 목록에 없습니다: 플랫폼이 실제로 서비스하는 이름이 그대로 들어 있습니다.
| 항목 | 이 레포지토리의 값 |
|---|---|
| 호스트 LAN 주소·게이트웨이 | 192.0.2.10/24, 192.0.2.1 |
| 리버스 프록시 공인 IP | 203.0.113.10 |
| 패스스루 대상 IP | 203.0.113.20 |
| 외부 릴레이 공인 IP | 198.51.100.10 |
| 관리 SSH 포트 | 22 |
| 시크릿 볼트 경로 | $VAULT/ |
| 플랫폼 브리지 대역 | 198.18.0.0/16 |
| 게스트 대역 | 198.19.0.0/16 |
개발용 임시 NAT 브리지 대역(시험 게스트, 런북 gpu-passthrough.md. 원본은 별도 사설 대역이라 위 두 공인 IP와 겹치지 않는 하위 대역을 골랐다) |
203.0.113.224/27 |
| 릴레이 터널 대역 | 100.64.0.0/30 |
| 호스트 이름 | pve-node, gpu-node, dept-node, pve-node-2, pve-node-3 |
| 비Proxmox 노드 주소·접속명 | 192.0.2.20, dept-node.example.ac.kr |
| Proxmox 노드 후보 주소 | 192.0.2.30, 192.0.2.31 |
| 비Proxmox 노드 하드웨어 모델 | 아키텍처만 남기고 제조사·모델명 생략 |
192.0.2.0/24와 198.51.100.0/24, 203.0.113.0/24는 RFC 5737이 문서화 용도로 예약한
대역이라 실제 인터넷에 존재하지 않습니다. 관리 SSH 포트도 한눈에 자리표시자로 보이도록
표준값을 적었습니다.
내부 대역도 치환했습니다. 사설 대역은 인터넷에서 도달할 수 없지만, 어떤 컨테이너가 어느
주소를 쓰고 터널이 어디로 이어지는지는 그 자체로 내부 지도입니다. 구조는 그대로 두고 숫자만
바꿨으므로(3·4번째 옥텟 유지) 스크립트가 무슨 일을 하는지는 그대로 읽힙니다.
198.18.0.0/15는 RFC 2544가 성능 시험용으로, 100.64.0.0/10은 RFC 6598이 사업자 설비용으로
예약한 대역이라 실제 서비스 주소로 쓰이지 않습니다. LXC 번호와 서비스 포트는 그대로입니다.
검사기(scripts/sanitization-check.sh)는 허용 목록으로 동작합니다 — 위 자리표시자
대역만 통과하고 사설 대역을 포함한 나머지는 거부합니다. 원본에서 값을 옮겨 오다 실제 주소가
섞이면 그 자리에서 걸립니다.
자격증명 값은 원본에도 없습니다. 인프라 레포지토리는 자격증명을 담지 않고, 볼트 구성은 pickle-secrets-example에서 따로 설명합니다.
flowchart LR
subgraph ext [외부]
B[콘솔 접속]
V[VM 도메인 접속]
S[VM SSH 접속]
PC[VM 포트 접속]
L[LLM API 호출]
end
subgraph relay [오프캠퍼스 릴레이]
HA[HAProxy :22]
NFT[nftables DNAT]
RA[pickle-relay-agent]
end
subgraph campus [부산대학교 서버팜]
PN[Pickle nginx]
VN[VM nginx]
C[pickle-console]
A[pickle-api]
J[JobRunr]
G[pickle-sshgw]
P[pickle-proxy-agent]
DB[(PostgreSQL)]
PVE[Proxmox VE]
VM[사용자 VM]
IB[pickle-image-builder]
LG[pickle-llm-gateway]
UP[업스트림 모델 서버]
end
B --> PN
V --> VN
S --> HA
PC --> NFT
L --> LG
HA -->|WireGuard| G
NFT -->|WireGuard| VM
NFT -. 규칙 적용 .- RA
RA -->|sync| A
PN -->|/| C
PN -->|/api| A
PN -->|/terminal| G
G -->|인가 질의| A
LG -->|키·모델 동기화| A
LG --> UP
G --> VM
VN --> VM
A --> DB
A -->|작업 등록| J
J -->|Proxmox API| PVE
A -->|도메인 설정| P
P -.->|vhost 적용| VN
PVE -.->|생성/제어| VM
IB -.->|템플릿 빌드| PVE
| 레포지토리 | 역할 |
|---|---|
| pickle-api | REST API와 프로비저닝 워커 (Spring Boot 4, Java 25, PostgreSQL 18, JobRunr) |
| pickle-console | 사용자·관리자 웹 콘솔 (React 19, TypeScript) |
| pickle-sshgw | SSH 게이트웨이와 웹 터미널 브리지 (sshpiperd, Go) |
| pickle-proxy-agent | nginx 리버스 프록시 제어 에이전트 (Go) |
| pickle-relay-agent | 오프캠퍼스 릴레이의 nftables DNAT 에이전트 (Go) |
| pickle-llm-gateway | 교내 LLM API 게이트웨이 (Go) |
| pickle-image-builder | 사용자 VM OS 이미지 빌드 레시피 (shell, virt-customize) |
| pickle-infra (비공개) | 인프라 프로비저닝 스크립트와 운영 런북 (shell) |
| pickle-infra-example | 프로비저닝·배포 스크립트와 런북 샘플 |
| pickle-secrets (비공개) | 호스트 시크릿 볼트 (git-crypt) |
| pickle-secrets-example | 볼트 레이아웃과 git-crypt 운용 절차 |