vultr-api/README.md

Vultr API v2 Python Wrapper

Vultr API v2를 위한 Python 클라이언트 라이브러리입니다.

설치

cd ~/vultr-api
pip install -e .

또는 requests가 설치되어 있다면 직접 import 가능:

export PYTHONPATH=~/vultr-api:$PYTHONPATH

사용법

기본 설정

from vultr_api import VultrClient

# API 키로 클라이언트 생성
client = VultrClient(api_key="your-api-key")

계정 정보

# 계정 정보 조회
account = client.account.get()
print(f"잔액: ${account['balance']}")
print(f"이메일: {account['email']}")

ACL (IP 접근 제어) - 중요!

# 현재 ACL 조회
acl = client.account.get_acl()
print(f"ACL 활성화: {acl.get('acl_enabled')}")
print(f"허용된 IP: {acl.get('acls', [])}")

# IP 추가
client.account.add_acl("203.0.113.50/32")

# IP 목록으로 설정
client.account.set_acl([
    "203.0.113.50/32",
    "10.0.0.0/8",
    "192.168.1.0/24"
])

# IP 제거
client.account.remove_acl("10.0.0.0/8")

# ACL 비활성화 (모든 IP 허용)
client.account.clear_acl()

인스턴스 관리

# 인스턴스 목록 조회
instances = client.instances.list()
for instance in instances.get("instances", []):
    print(f"{instance['label']}: {instance['main_ip']}")

# 인스턴스 생성
new_instance = client.instances.create(
    region="nrt",           # 도쿄
    plan="vc2-1c-1gb",      # 1 vCPU, 1GB RAM
    os_id=1743,             # Ubuntu 22.04
    label="my-server",
    enable_ipv6=True,
    sshkey_id=["ssh-key-id"],
    tags=["web", "production"]
)
print(f"인스턴스 생성됨: {new_instance['id']}")

# 인스턴스 상세 조회
instance = client.instances.get("instance-id")

# 인스턴스 제어
client.instances.start("instance-id")
client.instances.stop("instance-id")
client.instances.reboot("instance-id")

# 인스턴스 삭제
client.instances.delete("instance-id")

DNS 관리

# 도메인 목록
domains = client.dns.list_domains()

# 도메인 생성
domain = client.dns.create_domain("example.com", ip="203.0.113.50")

# 레코드 추가
client.dns.create_a_record("example.com", "www", "203.0.113.50")
client.dns.create_aaaa_record("example.com", "www", "2001:db8::1")
client.dns.create_cname_record("example.com", "blog", "www.example.com")
client.dns.create_mx_record("example.com", "@", "mail.example.com", priority=10)
client.dns.create_txt_record("example.com", "@", "v=spf1 include:_spf.example.com ~all")

# 레코드 목록
records = client.dns.list_records("example.com")

# 레코드 삭제
client.dns.delete_record("example.com", "record-id")

방화벽 관리

# 방화벽 그룹 생성
group = client.firewall.create_group(description="Web Servers")
group_id = group["id"]

# 규칙 추가
client.firewall.allow_ssh(group_id)       # SSH (22)
client.firewall.allow_http(group_id)      # HTTP (80)
client.firewall.allow_https(group_id)     # HTTPS (443)
client.firewall.allow_ping(group_id)      # ICMP

# 커스텀 규칙
client.firewall.create_rule(
    firewall_group_id=group_id,
    ip_type="v4",
    protocol="tcp",
    port="3000:3999",          # 포트 범위
    subnet="10.0.0.0",
    subnet_size=8,
    notes="Internal services"
)

# 인스턴스에 방화벽 적용
client.instances.update("instance-id", firewall_group_id=group_id)

SSH 키 관리

# SSH 키 목록
keys = client.ssh_keys.list()

# SSH 키 추가
key = client.ssh_keys.create(
    name="my-laptop",
    ssh_key="ssh-rsa AAAAB3NzaC1yc2EAAAA..."
)

# SSH 키 삭제
client.ssh_keys.delete("key-id")

VPC 관리

# VPC 생성
vpc = client.vpc.create(
    region="nrt",
    description="Private Network",
    v4_subnet="10.10.0.0",
    v4_subnet_mask=24
)

# VPC 2.0 생성
vpc2 = client.vpc.create_vpc2(
    region="nrt",
    description="VPC 2.0 Network",
    ip_block="10.20.0.0",
    prefix_length=24
)

# 인스턴스에 VPC 연결
client.instances.attach_vpc("instance-id", "vpc-id")

스냅샷 관리

# 스냅샷 생성
snapshot = client.snapshots.create(
    instance_id="instance-id",
    description="Before upgrade"
)

# 스냅샷 목록
snapshots = client.snapshots.list()

# 스냅샷으로 복원
client.instances.restore_snapshot("instance-id", "snapshot-id")

플랜 및 리전 조회

# 사용 가능한 플랜
plans = client.plans.list()
for plan in plans.get("plans", []):
    print(f"{plan['id']}: {plan['vcpu_count']}vCPU, {plan['ram']}MB, ${plan['monthly_cost']}/월")

# 리전 목록
regions = client.regions.list()
for region in regions.get("regions", []):
    print(f"{region['id']}: {region['city']}, {region['country']}")

# OS 목록
os_list = client.os.list()
for os_info in os_list.get("os", []):
    print(f"{os_info['id']}: {os_info['name']}")

지원하는 리소스

리소스	설명
account	계정 정보, ACL 관리
instances	클라우드 인스턴스
bare_metal	베어메탈 서버
dns	DNS 도메인/레코드
firewall	방화벽 그룹/규칙
ssh_keys	SSH 키
startup_scripts	시작 스크립트
snapshots	스냅샷
backups	백업
block_storage	블록 스토리지
reserved_ips	예약 IP
vpc	VPC, VPC 2.0
load_balancers	로드 밸런서
plans	플랜 목록
regions	리전 목록
os	OS 목록

에러 처리

from vultr_api.client import VultrAPIError

try:
    client.instances.get("invalid-id")
except VultrAPIError as e:
    print(f"API 오류: {e.message}")
    print(f"상태 코드: {e.status_code}")

API 참고

• Vultr API v2 문서
• Vultr API Postman Collection