Proxmox VE

관리자 위치: Infrastructure › Cloud provider › Providers (/infra/providers), 그런 다음 Overview, Clusters, VMs, Servers 및 Credentials 탭이 있는 공급자 페이지 (/infra/providers/<id>). 플랜은 Services › Virtual Machines › Plans & pricing (/vm/catalog)에서 설정합니다.

작동 내용

NexCMP는 CloudStack과 함께 또는 대신하여 하나 이상의 Proxmox VE 클러스터에서 실행되는 가상 머신을 판매할 수 있습니다. VM은 전체 복제(full clone)로 OS 템플릿을 복제한 다음 크기, 정의한 풀의 IP 주소, 루트 비밀번호 및 SSH 키 등 cloud-init을 통해 구성됩니다. 고객은 포털에서 전원 제어, 콘솔, 스냅샷, 재설치, 비밀번호 재설정 및 메트릭을 사용할 수 있습니다. 고객은 클러스터, 노드 또는 소스 이름을 볼 수 없습니다.

이미 Proxmox VE를 운영 중이거나 가격이 다른 두 번째 VM 풀을 제공하고자 할 때 사용합니다.

요구 사항

항목	요구 사항
Proxmox VE	PVE 9.x. 9.2 버전에서 검증되었습니다. import 스토리지 콘텐츠 및 import-from 디스크 옵션이 필요합니다 (PVE 8.2 이상).
패널의 네트워크	클러스터 API에 대한 HTTPS https://<host or IP>:8006. 경로, 사용자 이름 또는 쿼리는 없어야 합니다. 패널과 작업자(worker)가 모두 연결되며, 브라우저 콘솔은 패널을 통해 프록시됩니다.
계정	API 토큰 및 아래 나열된 권한을 가진 사용자 정의 역할을 사용하는 전용 PVE 사용자. root@pam은 절대 사용하지 마세요.
스토리지	클론을 지원하는 VM 디스크용 스토리지(예: local-lvm). 내장 템플릿 빌더의 경우, local(이)라는 이름의 스토리지(콘텐츠 유형: import 및 snippets).
네트워크	고객 IP가 속한 네트워크에 도달할 수 있는 Linux 브리지 (예: vmbr0). VLAN 태그를 입력하는 경우 VLAN 인식(VLAN-aware) 브리지를 사용하세요.
IP	게이트웨이가 포함되어 해당 브리지로 라우팅되는 IPv4 블록 (/16 ~ /30). NexCMP가 직접 주소를 할당하며 Proxmox에는 IP 관리 기능이 없습니다.
템플릿	QEMU 게스트 에이전트가 포함된, 배포하는 모든 노드의 OS당 하나의 cloud-init 템플릿 VM.
영역	클러스터를 연결할 기존 영역. Zones을 참조하세요.
종속성	없음.

인프라 준비

클러스터 노드에서 루트 권한으로 명령을 실행합니다.

1. 최소 권한 역할, 사용자 및 API 토큰 생성

1. 역할을 생성합니다. 권한 목록은 NexCMP가 사용하는 것과 정확히 일치하며 사용자, 스토리지 정의 또는 데이터센터를 편집하는 내용은 포함되어 있지 않습니다.

   pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use"

   클라우드 이미지 다운로드에는 Sys.AccessNetwork이(가) 필요합니다. PVE 9에는 VM.Monitor 권한이 없으므로 추가하지 마세요.

2. 사용자와 토큰을 생성합니다. --privsep 1은(는) 토큰의 권한이 사용자 권한과 토큰 자체 권한의 교집합임을 의미합니다.

   pveum user add nexcmp@pve --comment "NexCMP"
   pveum user token add nexcmp@pve api --privsep 1

   명령을 실행하면 토큰 secret이 1회만 출력됩니다(UUID 형식). 지금 복사해 두십시오. 토큰 ID는 nexcmp@pve!api입니다.

3. 사용자와 토큰 모두에 해당 역할을 부여하십시오. 이 단계를 놓치기 쉬우며, 권한 분리가 적용된 상태에서 사용자에게 권한이 없으면 토큰만 Datastore.Audit과 같은 403 오류를 받게 됩니다.

   pveum acl modify / --roles NexCMP --users nexcmp@pve
   pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api'

4. 패널 서버에서 테스트:

   curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=<secret>' https://192.0.2.10:8006/api2/json/version

   version이 포함된 JSON 문서가 반환되면 토큰이 정상 작동하는 것입니다. (-k은 이 빠른 확인에만 사용되며, NexCMP는 자체적으로 인증서를 고정합니다. 아래 참조.)

2. 브리지 및 스토리지 확인

pvesm status          # storages, type, content and free space
ip -br link show type bridge

• 고객 VM은 NexCMP에 입력한 브리지에 virtio 네트워크 인터페이스를 할당받습니다. VLAN을 설정한 경우 해당 브리지는 VLAN-aware 상태여야 합니다.
• 고객 VM을 노드의 관리 주소와 분리된 브리지 또는 VLAN에 배치하십시오. 동일한 네트워크를 공유할 경우 Proxmox 방화벽의 자동 관리 IP 세트로 인해 노드의 22, 8006, 3128, 5900-5999, 60000-60050 포트가 해당 네트워크의 모든 VM에 개방됩니다. 분리할 수 없는 경우 관리 ACCEPT 규칙 위에 VM 서브넷에서 해당 포트로의 명시적 DROP 규칙을 추가하십시오.

3. 스토리지 참고 사항 (LVM-thin)

• 씬 풀의 zeroing 설정을 기본값으로 유지하십시오. 이를 비활성화(lvchange -Zn)하면 새로 할당된 청크에 기존 데이터가 남아 클론된 VM의 파티션 테이블이나 파일 시스템이 손상될 수 있습니다.
• "write cache: disabled"로 표시되는 디스크는 몇 MB/s 속도로만 복제될 수 있습니다. hdparm -W /dev/sdX을(를) 통해 확인하고 디스크에 전원 손실 방지 기능이 있는 경우 쓰기 캐시를 활성화하세요.

4. import 콘텐츠 활성화 (내장 템플릿 빌더 전용)

내장 빌더는 local(이)라는 이름의 스토리지로 클라우드 이미지를 다운로드하고 그로부터 템플릿을 생성합니다. 해당 스토리지의 콘텐츠 목록에 import(과)과 snippets을(를) 추가하세요. 기존에 사용 중인 유형은 유지하고, --content이(가) 전체 목록을 교체합니다:

pvesm status --storage local     # note the current content
pvesm set local --content iso,vztmpl,backup,import,snippets

5. 클라우드 이미지로 OS 템플릿 빌드

템플릿은 NexCMP가 복제하는 cloud-init VM입니다. 각 템플릿은 VM ID와 함께 OS key(예: ubuntu-24.04) 단축키 아래에 등록됩니다. 복제가 선택된 노드에서 실행되므로 VM을 수신할 모든 노드에 OS당 하나의 템플릿을 빌드하세요.

옵션 A (권장): 직접 빌드. 기본 Ubuntu 및 Debian 클라우드 이미지에는 게스트 에이전트가 포함되어 있지 않고 루트 로그인을 허용하지 않으며, NexCMP는 cloud-init을 통해 루트 비밀번호를 설정합니다. 먼저 이미지를 준비하세요:

apt install -y libguestfs-tools
wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
virt-customize -a noble.qcow2 --install qemu-guest-agent \
  --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \
  --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n'

그런 다음 템플릿 VM을 생성합니다 (ID 9000은 예시이며, 템플릿 ID는 vmid from 값(기본값 1000) 미만으로 유지하세요):

qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \
  --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0
qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1
qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0
qm template 9000

옵션 B: 내장 빌더. 클러스터 탭(아래 참조)의 Create OS template from cloud image 카드는 qcow2 이미지를 다운로드하고 템플릿을 빌드하여 등록합니다. 이 카드는 cloud-init 및 게스트 에이전트 플래그가 포함된 VM을 생성하지만 이미지 내부의 내용은 변경하지 않습니다. 루트 로그인을 이미 허용하고 게스트 에이전트를 실행하는 이미지와 함께 사용하거나, cloud-init vendor-data 스니펫을 함께 제공하는 경우에만 사용하세요.

게스트 에이전트는 Reset password 기능과 VM의 IP 주소 표시를 위해 필요합니다.

6. 인증서 지문 확인 (선택 사항)

NexCMP는 TLS 인증서의 SHA-256 지문을 고정(pinning)하여 클러스터를 신뢰하므로 자체 서명된 인증서도 무방합니다. NexCMP가 고정할 값을 확인하려면 다음을 수행하세요:

openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256

NexCMP에서 연결

1. Infrastructure › Cloud provider › Providers을(를) 열고 Add cloud provider을(를) 클릭합니다. Proxmox VE을(를) 선택하고 입력하세요:

   필드	Example value
   Name	Proxmox cluster 1
   Endpoint	https://192.0.2.10:8006
   Token id	nexcmp@pve!api
   Token secret	XXXX (1단계에서 출력된 UUID)
   Slug	pve-1 (a-z, 0-9, 하이픈, 2-32자)
   Default node	pve1 (비워 둠: 여유 RAM이 가장 많은 온라인 노드)
   스토리지	local-lvm
   Bridge	vmbr0

   

2. Save & open provider를 클릭하고 요청 시 사유를 입력합니다. 토큰은 암호화되어 저장됩니다.

3. Overview 탭에서 Test connection을 클릭합니다. 첫 번째 성공적인 테스트는 클러스터의 TLS 지문을 고정하며, 그 이후부터는 다른 인증서가 거부됩니다.

4. Clusters 탭을 엽니다. Node · storage · bridge 카드에는 API가 감지한 항목이 표시되고, Cluster configuration 카드에는 설정이 포함됩니다.

   필드	의미
   Default node	새 VM에 사용되는 노드. 비워 두면 여유 RAM이 가장 많은 온라인 노드를 의미합니다.
   Storage, Bridge, VLAN	디스크 스토리지, NIC 브리지 및 선택적 VLAN 태그 (0은 없음).
   CPU type	기본값은 host입니다. 노드의 CPU 세대가 다른 경우 x86-64-v2-AES을 사용하세요.
   vmid from	고객 VM에 부여되는 첫 번째 VM ID (기본값 1000).
   Storage ISO, Storage backup	사용하지 않는 경우 비워 둡니다. 비워 두면 ISO 및 백업 기능이 제공되지 않습니다.
   Template OS	줄당 하나, os-key=vmid, 예: ubuntu-24.04=9000.
   Pinned TLS fingerprint (SHA-256)	첫 번째 테스트로 채워집니다. 클러스터 인증서를 교체한 후 지우고 다시 테스트하세요.

   

5. 선택 사항: 위의 옵션 B를 사용한 경우, Create OS template from cloud image(OS 키 ubuntu-24.04, vmid 9000, 노드 pve1, qcow2 이미지 URL)를 채우고 Create template을 클릭합니다. 백그라운드에서 몇 분간 실행되며, 결과는 감사 로그(Audit log)에서 확인하실 수 있습니다.

   

6. Add pool을 Cluster IP pool에서 클릭하고 VM이 주소를 할당받을 풀을 생성합니다:

   필드	Example value
   Name	customers-1
   CIDR	198.51.100.0/24
   Gateway	198.51.100.1 (VM에 할당되지 않음)
   DNS	1.1.1.1,8.8.8.8 (1~4개의 IPv4 주소)
   Bridge, VLAN	vmbr0, 0
   Already used IPs	줄당 하나, ip note, 예: 198.51.100.10 monitoring

   NexCMP는 네트워크 주소, 브로드캐스트 주소, 게이트웨이 또는 예약된 주소를 절대 할당하지 않습니다. 동일한 클러스터의 풀은 겹칠 수 없습니다. 풀은 주소가 전혀 사용되지 않을 때만 삭제할 수 있습니다.

   

7. Attach cluster to zone에서 영역과 선택적으로 노드 이름을 선택한 다음 Attach to zone을 클릭합니다. 클러스터는 이미 VM을 판매 중인 영역에 합류하므로 하나의 영역에 CloudStack과 Proxmox를 함께 구성할 수 있습니다. 새 소스는 기본적으로 판매되지 않으며 기존 플랜의 동작 방식을 변경하지 않습니다.

   

8. Services › Virtual Machines › Plans & pricing을 열고 Add plan을 클릭합니다. Infrastructure source에서 Proxmox 클러스터를 선택한 다음 CPU, RAM, 디스크 및 가격을 설정합니다. Proxmox 플랜에는 CloudStack 오퍼링이 필요하지 않습니다. 두 소스에서 동일한 구성을 판매하려면 플랜에서 Clone을 사용하고 다른 소스를 선택하세요. 플랜의 디스크는 템플릿의 디스크 이상이어야 합니다. Proxmox는 디스크를 축소할 수 없습니다.

기존에 존재하는 VM 가져오기

클러스터의 VM 목록을 보려면 Servers 탭을 엽니다. Import은(는) 시간, 전원 꺼짐 시간 또는 트래픽에 대한 과금 없이 기존 VM을 고객 계정에 무료로 할당합니다. 고객은 시작, 중지, 재부팅 및 콘솔 열기를 할 수 있지만 삭제할 수는 없으며 오직 관리자만 가능합니다. NexCMP는 가져오는 동안 클러스터에서 읽기만 수행합니다.

• 클러스터는 해당 VM의 노드 이름이 있는 영역에 연결되어어야 합니다(노드를 비워두면 가져오기가 리전이 설정되지 않았다고 보고합니다).

• VM을 보호 상태로 만들려면(중지, 재부팅, 재설치, 스냅샷 복원, 삭제 및 요금제 변경이 거부됨) 명령줄에서 다음으로 가져옵니다 --protect:

  sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect

Proxmox에서 지원되는 기능과 지원되지 않는 기능

기능	Proxmox VE
생성, 전원 켜기/끄기/재부팅, 삭제	예
CPU 및 RAM 크기 조정, 디스크 확장	예, 단 VM이 중지되고 변경된 후 다시 시작됨 (라이브 크기 조정 불가)
Snapshots	예, VM당 최대 5개: 생성, 목록 조회, 복원, 삭제
Reinstall	예: VM이 템플릿에서 다시 빌드되며 새 비밀번호와 함께 ID, IP 및 설정이 유지됨
비밀번호 초기화	예, 게스트 에이전트를 통해
콘솔	예, 패널을 통해 프록시되는 브라우저 콘솔
지표	예: CPU, 메모리, 네트워크 및 디스크
ISO 마운트, 백업, 방화벽, IPv6, 포트 포워딩, IP 변경, 추가 볼륨, Auto Scaling, DDoS Shield, VPC, 대역폭 측정	사용 불가. 고객 VM 페이지는 소스가 지원하지 않는 기능을 숨깁니다.

확인

1. Test connection이(가) OK를 표시하고 공급자 상태가 활성 상태입니다.
2. Clusters에 스토리지 및 브리지와 함께 노드가 온라인 상태로 나열됩니다.
3. Cluster IP pool에 여유, 사용 중 및 보류 중인 개수가 표시됩니다.
4. 클러스터가 연결된 후 OS 키가 Services › Virtual Machines › Template의 영역 템플릿 아래에 표시됩니다.
5. 클러스터를 사용하는 요금제에서 테스트 VM을 주문합니다. 풀에서 주소, 루트 비밀번호 및 작동하는 콘솔을 할당받아야 하며, 풀에는 1개의 주소가 사용 중인 것으로 표시됩니다.

제한 사항 및 참고 사항

혼합 소스 영역

NexCMP 1.4.0부터는 CloudStack과 Proxmox VE가 영역을 공유하는 경우에도 공개 Cloud Server 가격표가 정상 작동합니다. 각 요금제는 자체 Infrastructure source를 사용합니다. 클러스터를 연결한 후 공개 가격표를 확인하고 각 소스별로 테스트 주문을 진행해 보십시오.

• 여러 Proxmox 클러스터를 추가할 수 있습니다. 각각은 하나의 공급자입니다.
• 영역은 하나의 기본 소스를 제공하며, 자체 Infrastructure source가 있는 요금제는 해당 클러스터가 활성 상태이고 요금제의 영역에 있는 한 정확히 그 클러스터에 배포됩니다.
• CloudStack과 동일한 영역 뒤에 있는 클러스터는 CloudStack에 레거시 요금제를 유지합니다. 출시 전에 엔드투엔드 주문을 테스트하세요.
• API 토큰은 볼 수 없고 교체만 가능합니다. Credentials 탭에서 교체하세요. Proxmox에서 새 토큰을 먼저 생성하고 입력한 후 Test connection을 실행한 다음 이전 토큰을 해지합니다.
• Test, Sync 및 cluster-info 작업은 관리자당 분당 6회 호출로 제한됩니다.
• NexCMP는 고객에게 청구하며, 클러스터의 하드웨어 및 라이선스 비용은 귀하의 부담입니다.

Troubleshooting

증상	원인	해결 방법
테스트: "Key rejected (wrong access key / secret, or revoked)" 또는 HTTP 401/403	토큰 ID 또는 시크릿이 잘못되었거나 ACL이 토큰에만 부여됨	두 pveum acl modify 명령어(사용자 및 토큰)를 다시 실행하고 토큰 ID가 user@realm!tokenid인지 확인합니다.
테스트: "공급자에 연결할 수 없음(Could not connect to the provider)" 또는 "시간 초과(Timed out)"	방화벽, 잘못된 호스트 또는 포트	패널 서버에서 https://host:8006을(를) 확인합니다.
테스트: "잘못된 엔드포인트이거나 허용 목록에 없음(Invalid endpoint or not on the allowlist)"	엔드포인트에 경로, 사용자, 쿼리가 포함되어 있거나 HTTPS가 아님	정확히 https://host:8006을(를) 사용합니다.
"클러스터 TLS 인증서가 고정된 지문과 일치하지 않음(cluster TLS certificate DOES NOT match pinned fingerprint)"	클러스터 인증서가 교체됨	Clusters 탭에서 Pinned TLS fingerprint를 지우고 저장한 후, Test connection을(를) 다시 실행합니다.
슬러그 거부됨	a-z, 0-9, 하이픈이 아니거나 2-32자가 아님	pve-1과(와) 유사한 형식을 사용합니다.
"토큰 ID 형식: user@realm!tokenid 및 secret이 필요함(Token id format: user@realm!tokenid and secret is required)"	토큰 ID 또는 secret 누락	둘 다 입력하세요. secret은 토큰 생성 시 출력된 UUID입니다.
"잘못된 템플릿 라인: …(Invalid template line: …)"	Template OS의 라인이 key=vmid이(가) 아님	키에는 문자, 숫자, ., _, -를 사용하고 vmid는 100 이상으로 지정합니다.
"OS 키: a-z 0-9 . _ - 및 vmid ≥ 100"	Create template의 키 또는 ID가 잘못됨	OS 키를 수정하고 사용 가능한 vmid를 사용합니다.
템플릿 생성 시 "vmid … 이미 존재함(vmid … already exists)"	vmid가 이미 사용 중임	다른 ID를 선택합니다.
"URL이 내부 주소를 가리킴(url points to internal address)"	이미지 URL이 내부 IP임	공개 URL을 사용하세요. 이름은 Proxmox에서 해결됩니다.
다운로드 중 템플릿 작업 실패	스토리지 local에 import 콘텐츠가 없음	pvesm set local --content …,import,snippets한 후 다시 시도합니다. 파일 이름은 .qcow2, .raw, .vmdk, .ova 또는 .ovf로 끝나야 합니다.
"클러스터에 온라인 노드가 없음(cluster has no online nodes)" 또는 "노드 …이(가) 온라인이 아님(node … is not online)"	기본 노드가 다운되었거나 오타가 있음	Default node을(를) 수정하거나 비워 둡니다.
"이미지가 클러스터에 속하지 않음(image does not belong to cluster)"	플랜의 OS가 Template OS에 없음	목록에 키를 추가하고 저장합니다.
배포가 대기 상태를 거친 후 복제 단계에서 실패함	템플릿 VM이 선택한 노드에 없음	해당 노드에 템플릿을 생성하거나, Default node을(를) 템플릿이 있는 노드로 설정합니다.
고객이 루트 계정으로 로그인할 수 없음	이미지가 루트 로그인을 차단함	옵션 A와 같이 템플릿을 다시 빌드합니다.
비밀번호 재설정이 작동하지 않음	게스트 내에 게스트 에이전트가 없음	템플릿에 qemu-guest-agent을(를) 설치하고 활성화합니다.
"이름, CIDR, 게이트웨이는 필수 항목입니다"	풀 필드 누락	세 항목 모두 입력합니다.
Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" 또는 "cidr: network address must be …"	풀 중복, 잘못된 게이트웨이 또는 네트워크 경계에 있지 않은 CIDR	사용 가능한 대역, 그 내부의 게이트웨이, 그리고 네트워크 주소 형식으로 작성된 CIDR을 사용합니다(예: 198.51.100.0/24).
가져오기: "리전이 설정되지 않았습니다"	VM의 노드 이름 없이 클러스터가 연결됨	노드 이름과 함께 클러스터를 영역에 연결합니다.