vultr-api/README.md

# 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)