Initial commit: Vultr API v2 Python wrapper with FastAPI server
- vultr_api/: Python library wrapping Vultr API v2 - 17 resource modules (instances, dns, firewall, vpc, etc.) - Pagination support, error handling - server/: FastAPI REST server - All API endpoints exposed via HTTP - X-API-Key header authentication - Swagger docs at /docs - Podman quadlet config for systemd deployment Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
HWANG BYUNGHA
256
README.md
Normal file
256
README.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Vultr API v2 Python Wrapper
|
||||
|
||||
Vultr API v2를 위한 Python 클라이언트 라이브러리입니다.
|
||||
|
||||
## 설치
|
||||
|
||||
```bash
|
||||
cd ~/vultr-api
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
또는 requests가 설치되어 있다면 직접 import 가능:
|
||||
|
||||
```bash
|
||||
export PYTHONPATH=~/vultr-api:$PYTHONPATH
|
||||
```
|
||||
|
||||
## 사용법
|
||||
|
||||
### 기본 설정
|
||||
|
||||
```python
|
||||
from vultr_api import VultrClient
|
||||
|
||||
# API 키로 클라이언트 생성
|
||||
client = VultrClient(api_key="your-api-key")
|
||||
```
|
||||
|
||||
### 계정 정보
|
||||
|
||||
```python
|
||||
# 계정 정보 조회
|
||||
account = client.account.get()
|
||||
print(f"잔액: ${account['balance']}")
|
||||
print(f"이메일: {account['email']}")
|
||||
```
|
||||
|
||||
### ACL (IP 접근 제어) - 중요!
|
||||
|
||||
```python
|
||||
# 현재 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()
|
||||
```
|
||||
|
||||
### 인스턴스 관리
|
||||
|
||||
```python
|
||||
# 인스턴스 목록 조회
|
||||
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 관리
|
||||
|
||||
```python
|
||||
# 도메인 목록
|
||||
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")
|
||||
```
|
||||
|
||||
### 방화벽 관리
|
||||
|
||||
```python
|
||||
# 방화벽 그룹 생성
|
||||
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 키 관리
|
||||
|
||||
```python
|
||||
# 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 관리
|
||||
|
||||
```python
|
||||
# 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")
|
||||
```
|
||||
|
||||
### 스냅샷 관리
|
||||
|
||||
```python
|
||||
# 스냅샷 생성
|
||||
snapshot = client.snapshots.create(
|
||||
instance_id="instance-id",
|
||||
description="Before upgrade"
|
||||
)
|
||||
|
||||
# 스냅샷 목록
|
||||
snapshots = client.snapshots.list()
|
||||
|
||||
# 스냅샷으로 복원
|
||||
client.instances.restore_snapshot("instance-id", "snapshot-id")
|
||||
```
|
||||
|
||||
### 플랜 및 리전 조회
|
||||
|
||||
```python
|
||||
# 사용 가능한 플랜
|
||||
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 목록 |
|
||||
|
||||
## 에러 처리
|
||||
|
||||
```python
|
||||
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 문서](https://www.vultr.com/api/)
|
||||
- [Vultr API Postman Collection](https://www.postman.com/vultr-api/vultr-api-v2/documentation/soddyfe/vultr-api-v2)
|
||||
Reference in New Issue
Block a user