[작성 중] API 활용

API 규격

Proxmox API는 Restful API로 http 메서드 기반으로 통신합니다. API를 통해 가상 머신, 컨테이너, 네트워크, 스토리지, 노드 등의 관리를 자동화할 수 있습니다.

자세한 정보는 아래 경로에서 확인 가능합니다.

API 정보 확인

API 규격 확인

특별한 작업 없이 Proxmox VE를 설치하면 API가 활성화되어 있습니다. Endpoint 주소가 URL 또는 IP:8006이기 때문에 8006 포트가 활성화되어 있는지 확인이 필요합니다.

API 인증 토큰 생성

인증방식

인증 방식에는 운영체제 단에서 처리하는 pam과 Proxmox Manager에서 처리하는 pve 방식이 있습니다.

계정명@pve 또는 계정명@pam

API를 위한 계정은 pve 방식을 사용하는 것이 시스템 보안성에 도움이 됩니다.

API 인증 토큰 획득

API를 사용하기 위해서 가장 먼저 해야하는 작업은 인증 토큰을 획득하는 것입니다. 토큰 획득 방법은 두 가지가 있습니다. 특징은 아래 표를 통해 비교 가능합니다.

특징	curl 방식(Ticket/CSRF)	API Token 방식
보안성	세션 토큰은 유출되더라도 일정 시간 후 만료됨	API Token 유출 시 큰 보안 위협
유효 기간	기본적으로 세션이 만료되기 전까지만 유효	수동으로 만료 설정 가능 (기본 무기한)
복잡도	초기 인증 및 토큰 관리 필요	간단한 토큰 관리만으로 작동
사용 용도	주기적인 세션 인증이 필요한 작업	장기간 고정적으로 사용하는 스크립트나 앱
CSRF 보호	필요(POST, PUT, DELETE에서 CSRF 토큰 사용)	불필요

---

① 세션 기반 인증

사용자 ID와 비밀번호를 Proxmox API의 /api2/json/access/ticket 엔드포인트에 전송하면 올바른 계정 정보일 경우 PVEAuthCookie(세션 토큰)와 CSRF 토큰을 반환받는 구조입니다.

세션 기반 인증 토큰을 획득하기 위해서는 아래 과정이 필요합니다.

티켓 내부 데이터로 사용자 인증 정보를 대체

로그인 작업 없이 토큰을 이용하여 작업 가능

토큰 획득 시 URL 인코딩 과정이 필요하니 bash script로 작성하였습니다.

#!/bin/bash

# auth 정보
non_url_auth=(
        "호스트 도메인 또는 IP"	# host
        "계정명@pve"		# user
        "패스워드"			# pass
        )

# url 인코딩 fuction
url_encode() {
    local raw="$1"
    local encoded=""
    local length="${#raw}"
    for (( i = 0; i < length; i++ )); do
        char="${raw:i:1}"
        case "$char" in
            [a-zA-Z0-9.~_-]) encoded+="$char" ;; # 허용된 문자
            ' ') encoded+="%20" ;;               # 공백은 %20으로
            *) encoded+="$(printf '%%%02X' "'$char")" ;; # 나머지는 %HH 형식
        esac
    done
    echo "$encoded"
}


# url 인코딩 함수 실행
for auth_item in "${non_url_auth[@]}"; do
        enc_url_auth+=("$(url_encode "$auth_item")")
done

# get auth ticket
auth_response=`curl -s -k -X POST https://${enc_url_auth[0]}:8006/api2/json/access/ticket \
        -d "username=${enc_url_auth[1]}" \
        -d "password=${enc_url_auth[2]}"`

# CSRF Token, ticket 변수 저장
ticket=$(echo $auth_response | jq -r '.data.ticket')
csrf_t=$(echo $auth_response | jq -r '.data.CSRFPreventionToken')

echo "$ticket"
echo "==="
echo "$csrf_t"

ticket과 CSRF token 반환 값을 별도로 기록하거나 기억해둡니다.

이 값을 활용하여 cluster node 정보를 확인해보려면 아래와 같이 입력하거나 bash script 하단에 추가합니다.

curl -s -k -X GET https://${enc_url_auth[0]}:8006/api2/json/nodes \
       -H "Authorization: PVEAuthCookie=${ticket}" \
       -H "CSRFPreventionToken: ${csrf_t}" | jq .

리눅스 명령어 | jq . 를 통해 JSON 데이터를 자동으로 파싱하여 출력할 수 있습니다.

---

② 서버에 생성한 API Key 이용

Proxmox WEB UI [Datacenter -> Permissions -> API Tokens]에서 API를 생성해둡니다. 생성 직후에 나오는 팝업에서만 Token 비밀번호를 알 수 있으니 잘 기재해두어야 합니다.

생성된 Token은 User의 Role을 기반으로 권한이 주어지기 때문에 api_auth의 Role이 무엇인지 체크해보아야 합니다. Web UI [Datacenter -> Permissions -> Add -> User Permission]에서 추가 가능합니다.

API Token 권한으로 PVEAdmin을 생성하며, 경로는 최상위로 설정하였습니다. 비슷한 권한으로 PVEAdmin과 Administrator가 있는데 두 권한의 차이는 PVEAdmin은 민감정보 즉, 사용자 계정이나 권한과 관련된 작업은 불가합니다.
API Token 으로 기능 구현하는데에 권한이나 사용자 정보 등은 필요하지 않기 때문에 보안 취약점을 조금이라도 낮추기 위해 PVEAdmin으로 설정하였습니다.

토큰을 사용하여 노드 조회 테스트를 해보겠습니다. Token은 ID정보'!'API Token이름=토큰 값이 기본 형식입니다. 단, bash 터미널에서 '!' 기호를 일반 문자열로 처리하려면 앞에 역슬래시’\'를 붙여서 명령어를 실행해야 합니다. bash script로 만들어서 실행하는 경우에는 역슬래시 기호가 필요하지 않습니다.

# 터미널 직접 입력 시 
curl -s -k -X GET "https://호스트 도메인 또는 IP:8006/api2/json/nodes" \
-H "Authorization: PVEAPIToken=계정명@pve\!API_이름=Token_Value" | jq .

# 스크립트 구현 시
===
#!/bin/bash

Host="호스트 도메인 또는 IP"
ID="계정명@pve"
API_Name="test_api"
Token="토큰 값"

curl -s -k -X GET "https://${Host}:8006/api2/json/nodes" \
-H "Authorization: PVEAPIToken=${ID}!${API_Name}=${Token}" | jq .
===

이후 본 게시글에서는 API Token으로 테스트를 진행할 것이기 때문에 엔드포인트는 뒤에가 조금씩 달라질 수 있겠지만 기본적으로 이 양식을 띄고 밑에 전달 값만 늘려가는 방식입니다.

Proxmox User Role

PVEAdmin 권한

• PVEAdmin은 시스템 관리 작업을 수행할 수 있는 고급 관리자 역할입니다. 일반적인 API 이용 작업은 모두 가능하지만 일부 민감한 작업(특히 사용자 및 권한 관리)에는 접근할 수 없습니다.

• PVEAdmin 권한 범위
  ◦ VM 및 컨테이너 생성, 삭제, 관리
  ◦ 노드 관리(스토리지 추가/삭제 등)
  ◦ 네트워크 설정 및 모니터링
  ◦ 백업 및 복원 작업
  ◦ API를 통한 대부분의 관리 작업 수행

• 주요 제한
  ◦ 사용자 관리 불가: 새로운 사용자 생성/삭제 또는 사용자의 권한 변경 불가
  ◦ 권한 관리 불가: 역할(Role)이나 권한을 설정하는 작업 불가

---

Administrator 권한

Administrator는 Proxmox에서 제공하는 최상위 관리자 권한입니다. 모든 작업 수행이 가능하며, 제한이 없습니다.

• Administrator 권한 범위
  PVEAdmin의 모든 권한 포함

• 추가 권한:
  ◦ 사용자 및 권한 관리: 새로운 사용자 생성, 삭제 및 권한 할당
  ◦ 모든 클러스터 설정 수정
  ◦ 전체 시스템에 대한 설정 변경
  ◦ 데이터센터 전역 권한 관리

API 활용

cluster node 연결 및 해제

storage 연결

이미지 storage에 다운로드

LXC 컨테이너 생성 및 삭제

VM 생성 및 삭제

VM 사양 변경