03. Proxmox Management Architecture

VMware에 vCenter가 있다면, Proxmox에는 각 노드에 내장된 분산 관리 시스템이 있음

📌 이 글의 목적

Proxmox VE는 별도의 중앙 관리 서버가 없음. 모든 노드가 자체적으로 관리 기능을 갖고 있으며, 클러스터 구성 시 분산 파일시스템(pmxcfs)을 통해 설정이 동기화됨. 이 구조는 VMware의 vCenter 모델과 근본적으로 다름.

이 글을 읽고 나면:

Proxmox의 API 중심 아키텍처를 이해할 수 있음
웹 UI, CLI, API의 관계와 내부 동작 경로를 설명할 수 있음
인증 Realm과 RBAC 권한 모델을 이해할 수 있음
pmxcfs(Proxmox Cluster File System)의 동작 원리와 Corosync과의 관계를 이해할 수 있음
VMware vCenter 아키텍처와의 구조적 차이를 비교할 수 있음

1. 관리 레이어 개요

1.1 API 중심 아키텍처

Proxmox VE의 모든 기능은 REST API로 노출됨. 웹 UI와 CLI는 모두 이 API의 클라이언트임.

flowchart TB
    subgraph Clients["클라이언트"]
        WebUI["웹 UI<br/>(JavaScript)"]
        CLI["CLI<br/>(pvesh, qm, pct, pvecm)"]
        Terraform["Terraform<br/>(bpg/proxmox)"]
        Ansible["Ansible<br/>(community.general.proxmox)"]
        Custom["커스텀 스크립트<br/>(curl, Python proxmoxer)"]
    end

    subgraph Node["Proxmox 노드"]
        PVEProxy["pveproxy<br/>(HTTPS :8006)"]
        PVEDaemon["pvedaemon<br/>(권한 있는 API 핸들러)"]
        PVEStatd["pvestatd<br/>(상태/통계 수집)"]
        
        subgraph Services["서비스"]
            QM["qm (VM 관리)"]
            PCT["pct (LXC 관리)"]
            PVESM["pvesm (스토리지)"]
            PVECM["pvecm (클러스터)"]
            PVEHA["pve-ha-manager"]
            PVEFirewall["pve-firewall"]
        end
    end

    Clients --> PVEProxy
    PVEProxy --> PVEDaemon
    PVEDaemon --> Services

데몬	포트	역할
pveproxy	8006 (HTTPS)	외부 API 요청을 수신하는 리버스 프록시. 인증, TLS 처리
pvedaemon	— (내부)	실제 API 핸들러. root 권한으로 시스템 작업 수행
pvestatd	—	노드/VM/CT 상태 정보 수집 (CPU, 메모리, 디스크, 네트워크)
pve-ha-manager	—	HA 리소스 관리 (LRM + CRM)
pve-ha-lrm	—	Local Resource Manager — 로컬 HA 리소스 상태 관리
pve-firewall	—	방화벽 규칙 적용 (iptables/nftables 기반)

1.2 요청 처리 흐름

웹 UI에서 VM을 시작하는 경우의 내부 흐름:

sequenceDiagram
    participant User as 사용자 (브라우저)
    participant Proxy as pveproxy (:8006)
    participant Daemon as pvedaemon
    participant QM as qm (VM 관리)
    participant KVM as QEMU/KVM

    User ->> Proxy: POST /api2/json/nodes/{node}/qemu/{vmid}/status/start
    Proxy ->> Proxy: 인증 토큰 검증
    Proxy ->> Daemon: API 요청 전달
    Daemon ->> Daemon: 권한(ACL) 확인
    Daemon ->> QM: VM 시작 명령
    QM ->> KVM: QEMU 프로세스 생성
    KVM -->> Daemon: 성공/실패
    Daemon -->> Proxy: JSON 응답
    Proxy -->> User: HTTP 200 + UPID(Task ID)

💡 모든 장시간 작업(VM 시작, 마이그레이션, 백업 등)은 Task로 관리됨. API 응답으로 UPID(Unique Process ID)가 반환되고, 이후 Task 상태를 폴링하여 진행 상황을 확인할 수 있음.

2. API 구조

2.1 API 경로 체계

Proxmox API는 리소스 기반 URL 구조를 사용함.

/api2/json/                          # 루트
├── /cluster/                        # 클러스터 전체
│   ├── /cluster/status              # 클러스터 상태
│   ├── /cluster/resources           # 전체 리소스 목록
│   ├── /cluster/ha/                 # HA 설정
│   ├── /cluster/firewall/           # 클러스터 방화벽
│   └── /cluster/backup/             # 백업 스케줄
├── /nodes/{node}/                   # 특정 노드
│   ├── /nodes/{node}/qemu/          # VM 목록
│   │   └── /nodes/{node}/qemu/{vmid}/  # 특정 VM
│   │       ├── /status/             # 상태 (start, stop, reset)
│   │       ├── /config              # 설정
│   │       ├── /snapshot/           # 스냅샷
│   │       ├── /migrate             # 마이그레이션
│   │       └── /monitor             # QEMU Monitor
│   ├── /nodes/{node}/lxc/           # LXC 컨테이너
│   ├── /nodes/{node}/storage/       # 스토리지
│   ├── /nodes/{node}/network/       # 네트워크
│   └── /nodes/{node}/tasks/         # 작업 내역
├── /access/                         # 인증/권한
│   ├── /access/users/               # 사용자
│   ├── /access/groups/              # 그룹
│   ├── /access/roles/               # 역할
│   ├── /access/acl                  # ACL
│   └── /access/domains/             # 인증 Realm
└── /storage/                        # 스토리지 정의

2.2 API 인증 방식

방식	용도	특징
Ticket (쿠키)	웹 UI	사용자 로그인 시 발급, 2시간 유효, CSRF 토큰 동반
API Token	자동화/스크립트	만료 없음, 사용자에 종속, 별도 권한 제한 가능

API Token 구조:

# 토큰 ID
user@realm!tokenname

# 예시
admin@pve!terraform

API Token은 사용자의 권한을 상속하거나 제한할 수 있음. privilege separation 옵션으로 토큰에 별도 ACL을 적용하여 최소 권한 원칙을 적용 가능.

2.3 CLI 도구

도구	용도	내부 동작
`pvesh`	API를 CLI에서 직접 호출	REST API 클라이언트
`qm`	VM(KVM) 관리	QEMU/KVM 직접 제어
`pct`	LXC 컨테이너 관리	LXC 직접 제어
`pvecm`	클러스터 관리	Corosync 설정 관리
`pvesm`	스토리지 관리	스토리지 플러그인 호출
`pveam`	어플라이언스(템플릿) 관리	템플릿 다운로드/관리
`vzdump`	백업 수행	VM/CT 백업 엔진
`qmrestore` / `pct restore`	복원	백업에서 VM/CT 복원
`ha-manager`	HA 리소스 관리	HA Manager 제어

3. 인증과 권한

3.1 인증 Realm

Proxmox는 다중 인증 소스(Realm) 를 지원함.

Realm	타입	설명
pam	Linux PAM	호스트 OS의 Linux 사용자. `root@pam`이 기본 관리자
pve	Proxmox 자체	Proxmox 자체 사용자 DB. 시스템 계정 불필요
ldap	LDAP	외부 LDAP/AD 서버 연동
ad	Active Directory	AD 전용 Realm (LDAP보다 간편)
openid	OpenID Connect	SSO 연동 (Keycloak, Azure AD 등)

flowchart LR
    User["사용자 로그인<br/>admin@pve"] --> PVEAuth["Proxmox 인증"]
    
    PVEAuth --> PAM["PAM<br/>(Linux 사용자)"]
    PVEAuth --> PVERealm["PVE Realm<br/>(자체 DB)"]
    PVEAuth --> LDAP_AD["LDAP / AD<br/>(외부 디렉토리)"]
    PVEAuth --> OpenID["OpenID Connect<br/>(SSO)"]
    
    PAM --> Ticket["Ticket + CSRF Token 발급"]
    PVERealm --> Ticket
    LDAP_AD --> Ticket
    OpenID --> Ticket

💡 root@pam은 항상 전체 관리자 권한을 가짐 (ACL 무시). 이는 긴급 상황에서 접근을 보장하기 위한 설계임. 일상 관리는 별도 사용자를 만들어 사용하는 것이 권장됨.

3.2 RBAC — 역할 기반 접근제어

Proxmox의 권한 모델은 경로(Path) + 사용자/그룹 + 역할(Role) 의 3요소로 구성됨.

flowchart LR
    subgraph ACL["ACL 규칙"]
        Path["경로<br/>/vms/100"]
        Subject["주체<br/>user@realm 또는 @group"]
        Role["역할<br/>PVEVMAdmin"]
    end
    
    Path --> Permission["권한 결정"]
    Subject --> Permission
    Role --> Permission

경로(Path) 계층:

/                            # 루트 (전체)
├── /access/                 # 인증/권한 관리 자체
├── /nodes/{node}            # 특정 노드
├── /vms/{vmid}              # 특정 VM/CT
├── /storage/{storage}       # 특정 스토리지
├── /pool/{pool}             # 리소스 풀
└── /sdn/                    # SDN

기본 제공 역할:

역할	설명	주요 권한
Administrator	전체 권한	모든 권한
PVEAdmin	Proxmox 관리 (시스템 설정 제외)	VM/CT/스토리지/네트워크 관리
PVEVMAdmin	VM/CT 전체 관리	생성, 삭제, 설정 변경, 콘솔
PVEVMUser	VM/CT 사용	콘솔 접속, 시작/중지만
PVEDatastoreAdmin	스토리지 관리	스토리지 추가/삭제/설정
PVEDatastoreUser	스토리지 사용	이미지/ISO 업로드, 할당
PVEAuditor	읽기 전용	상태 조회만
PVEPoolAdmin	리소스 풀 관리	풀 내 리소스 관리
PVEPoolUser	풀 사용	풀 내 리소스 사용
NoAccess	접근 차단	명시적 접근 거부

권한 상속: ACL은 경로 계층을 따라 상속됨. / 에 설정된 권한은 모든 하위 경로에 적용됨. propagate=0 으로 상속을 차단할 수 있음.

3.3 2FA (Two-Factor Authentication)

방식	설명
TOTP	Google Authenticator 등 앱 기반 일회용 비밀번호
U2F	하드웨어 보안 키 (YubiKey 등, 레거시)
WebAuthn	FIDO2 기반 (U2F 후속, 현재 권장)
Recovery Keys	2FA 장치 분실 시 복구용 일회성 키

4. 클러스터 파일시스템 (pmxcfs)

4.1 pmxcfs란

pmxcfs(Proxmox Cluster File System) 는 Proxmox 클러스터의 설정 데이터를 전 노드에 실시간 동기화하는 FUSE 기반 파일시스템임.

flowchart TB
    subgraph Node1["Node 1"]
        ETC1["/etc/pve/<br/>(pmxcfs 마운트)"]
        DB1["SQLite DB<br/>(로컬)"]
    end
    
    subgraph Node2["Node 2"]
        ETC2["/etc/pve/<br/>(pmxcfs 마운트)"]
        DB2["SQLite DB<br/>(로컬)"]
    end
    
    subgraph Node3["Node 3"]
        ETC3["/etc/pve/<br/>(pmxcfs 마운트)"]
        DB3["SQLite DB<br/>(로컬)"]
    end
    
    subgraph Corosync_Layer["Corosync 통신"]
        Sync["설정 변경 실시간 동기화"]
    end
    
    ETC1 <-->|"Corosync"| Sync
    ETC2 <-->|"Corosync"| Sync
    ETC3 <-->|"Corosync"| Sync

항목	설명
마운트 포인트	`/etc/pve/`
백엔드	SQLite DB (각 노드 로컬)
동기화	Corosync 프로토콜을 통한 실시간 복제
크기 제한	최대 128MB (설정 데이터 전용)
내용	VM/CT 설정, 사용자/권한, 스토리지 정의, 방화벽 규칙, HA 설정 등

4.2 /etc/pve/ 디렉토리 구조

/etc/pve/
├── authkey.pub                      # 클러스터 인증 키
├── corosync.conf                    # Corosync 설정
├── datacenter.cfg                   # 데이터센터 수준 설정
├── storage.cfg                      # 스토리지 정의
├── user.cfg                         # 사용자/그룹/역할/ACL
├── firewall/                        # 클러스터/호스트/VM 방화벽 규칙
│   ├── cluster.fw
│   └── <vmid>.fw
├── ha/                              # HA 설정
│   ├── manager_status
│   └── resources.cfg
├── lxc/                             # LXC 설정
│   └── <vmid>.conf
├── qemu-server/                     # VM 설정
│   └── <vmid>.conf
├── nodes/<node>/                    # 노드별 설정
│   ├── qemu-server/<vmid>.conf      # 이 노드에서 실행 중인 VM 설정
│   ├── lxc/<vmid>.conf
│   └── network                      # 노드 네트워크 설정 (/etc/network/interfaces의 심볼릭 링크는 아님)
├── priv/                            # 비밀 키 (노드별 격리)
│   ├── authkey.key
│   └── known_hosts
└── sdn/                             # SDN 설정

💡 모든 VM/CT 설정은 /etc/pve/에 텍스트 파일로 저장됨. 이는 vim으로 직접 편집할 수도 있다는 뜻이지만, API나 CLI를 통해 수정하는 것이 안전함.

4.3 Corosync과의 관계

pmxcfs는 Corosync의 통신 채널 위에서 동작함. Corosync이 제공하는 기능:

기능	설명
멤버십 관리	어떤 노드가 클러스터에 참여 중인지 추적
메시징	노드 간 메시지 전달 (설정 변경 동기화)
쿼럼	과반수 투표를 통한 의사결정 (Split-brain 방지)
하트비트	노드 생존 여부 확인

flowchart TB
    subgraph Stack["Proxmox 클러스터 스택"]
        direction TB
        HA["HA Manager<br/>(VM/CT 페일오버)"]
        PMXCFS["pmxcfs<br/>(설정 동기화)"]
        Corosync_S["Corosync<br/>(멤버십, 메시징, 쿼럼)"]
        Network_S["네트워크<br/>(Dedicated Link 권장)"]
        
        HA --> PMXCFS
        PMXCFS --> Corosync_S
        Corosync_S --> Network_S
    end

⚠️ Corosync 네트워크가 끊기면 pmxcfs도 읽기 전용이 됨. 쿼럼을 잃은 노드에서는 설정 변경이 불가능해짐 (VM/CT는 계속 실행되지만 관리 작업 불가). 이것이 Corosync 전용 네트워크를 별도로 구성하는 이유임.

5. 태스크 시스템

5.1 UPID

모든 장시간 작업은 UPID(Unique Process ID) 로 추적됨.

UPID:pve1:000F4E5C:04F6C8A2:65E1A2B4:qmstart:100:root@pam:

구성 요소:
UPID:{node}:{pid}:{pstart}:{starttime}:{type}:{id}:{user}:

필드	설명
node	작업이 실행되는 노드
pid	프로세스 ID
pstart	프로세스 시작 블록
starttime	시작 시간 (epoch)
type	작업 유형 (qmstart, vzdump, vzmigrate 등)
id	대상 VMID 등
user	작업을 요청한 사용자

5.2 태스크 로그

# 최근 태스크 목록
pvesh get /cluster/tasks --limit 10
 
# 특정 태스크 로그
pvesh get /nodes/{node}/tasks/{upid}/log
 
# 태스크 상태
pvesh get /nodes/{node}/tasks/{upid}/status

6. VMware vCenter와의 비교

항목	Proxmox	VMware vCenter
관리 서버	없음 (각 노드 내장)	별도 VM (VCSA)
단일 장애점	없음	vCenter 장애 시 관리 불가
설정 저장	pmxcfs (분산 파일시스템)	PostgreSQL (VCSA 내장)
설정 동기화	Corosync (실시간)	vCenter DB 중앙 집중
API	REST API (JSON)	REST + SOAP + PowerCLI
웹 UI	각 노드에서 접속 가능	vCenter에만 접속
인증	PAM, PVE, LDAP, AD, OpenID	SSO, AD, LDAP, OpenID
RBAC	경로 기반 ACL	인벤토리 객체 기반
라이선스 관리	없음 (무료)	vCenter가 라이선스 관리
확장 한계	32 노드 (클러스터당)	2,500 호스트 (단일 vCenter)

구조적 차이:

flowchart TB
    subgraph PVE_Model["Proxmox 모델 (분산)"]
        N1_PVE["Node 1<br/>+ 관리 기능"]
        N2_PVE["Node 2<br/>+ 관리 기능"]
        N3_PVE["Node 3<br/>+ 관리 기능"]
        N1_PVE <-->|"Corosync<br/>pmxcfs"| N2_PVE
        N2_PVE <-->|"Corosync<br/>pmxcfs"| N3_PVE
        N1_PVE <-->|"Corosync<br/>pmxcfs"| N3_PVE
    end

    subgraph VMware_Model["VMware 모델 (중앙 집중)"]
        vCenter_VM["vCenter Server<br/>(중앙 관리 VM)"]
        E1["ESXi Host 1"]
        E2["ESXi Host 2"]
        E3["ESXi Host 3"]
        vCenter_VM --> E1
        vCenter_VM --> E2
        vCenter_VM --> E3
    end

Proxmox 모델의 장점:

단일 장애점이 없음 — 어떤 노드가 죽어도 다른 노드에서 전체 관리 가능
관리 서버를 위한 별도 리소스가 불필요함
구조가 단순함

Proxmox 모델의 한계:

대규모 확장에 제한이 있음 (32노드/클러스터 vs vCenter의 2,500호스트)
중앙 집중적 정책 관리(DRS 같은 글로벌 최적화)가 어려움
클러스터 전체 뷰가 vCenter 대비 제한적임

정리

Proxmox의 관리 아키텍처는 “모든 것이 API” 원칙 위에 세워져 있음.

pveproxy + pvedaemon: 웹 UI, CLI, Terraform, Ansible 모두 동일한 REST API를 사용함
pmxcfs: 클러스터 설정을 Corosync 위에서 실시간 동기화하는 분산 파일시스템
RBAC: 경로 + 사용자/그룹 + 역할의 3요소로 세밀한 권한 제어
분산 관리: 별도 관리 서버 없이 각 노드가 관리 기능을 내장

이 구조를 이해하면 자동화(API Token + Terraform/Ansible), 보안(RBAC + 2FA), 트러블슈팅(태스크 로그, pmxcfs 상태)의 기반이 됨.

→ #4 Compute — CPU, Memory, KVM VM & LXC — CPU 스케줄링, 메모리 관리, NUMA, VM/LXC 워크로드

🔗 관련 문서

Proxmox VE Overview — 시리즈 #1
KVM & QEMU Architecture — #2, KVM/QEMU 내부 동작
VMware vCenter Architecture — vCenter와의 비교
Proxmox VE Series Index — 시리즈 목차

0x2A Engineering

탐색기

03. Proxmox Management Architecture

03. Proxmox Management Architecture

📌 이 글의 목적

1. 관리 레이어 개요

1.1 API 중심 아키텍처

1.2 요청 처리 흐름

2. API 구조

2.1 API 경로 체계

2.2 API 인증 방식

2.3 CLI 도구

3. 인증과 권한

3.1 인증 Realm

3.2 RBAC — 역할 기반 접근제어

3.3 2FA (Two-Factor Authentication)

4. 클러스터 파일시스템 (pmxcfs)

4.1 pmxcfs란

4.2 /etc/pve/ 디렉토리 구조

4.3 Corosync과의 관계

5. 태스크 시스템

5.1 UPID

5.2 태스크 로그

6. VMware vCenter와의 비교

정리

다음 글

🔗 관련 문서

📝 참고 자료

그래프 뷰

목차

백링크