VergeOS Python SDK (pyvergeos)

pyvergeos là một Python SDK để quản lý VergeOS thông qua REST API, cung cấp giao diện kiểu Python có chú thích kiểu để tự động hóa VM, mạng, lưu trữ, tenant và khôi phục thảm họa.

Tổng quan

pyvergeos là một SDK Python để quản lý hạ tầng VergeOS thông qua REST API. Nó cung cấp một giao diện theo phong cách Python, có chú thích kiểu, để tự động hóa vòng đời VM, mạng, lưu trữ, thao tác đa thuê bao và quy trình khôi phục sau thảm họa, khiến nó lý tưởng cho các script tự động hóa, phát triển công cụ và tích hợp.

Tính năng chính

• Quản lý VM: Tạo, cấu hình, điều khiển nguồn, sao chép và snapshot
• Mạng nâng cao: Mạng ảo, quy tắc tường lửa, DHCP, DNS, VPN IPSec và WireGuard
• NAS & Lưu trữ: Quản lý volume, chia sẻ CIFS/NFS và đồng bộ hóa
• Đa thuê bao: Cấp phát tenant với cách ly tài nguyên
• Khôi phục sau thảm họa: Snapshot đám mây, đồng bộ hóa site và quy trình khôi phục
• Lọc: Hỗ trợ bộ lọc OData với API xây dựng bộ lọc linh hoạt
• Chú thích kiểu: Đầy đủ gợi ý kiểu cho tự động hoàn thành IDE và phân tích tĩnh
• Đa nền tảng: Hỗ trợ Windows, macOS và Linux

Yêu cầu

• Python 3.9 trở lên
• VergeOS 26.0 trở lên

Cài đặt

Từ PyPI (Khuyến nghị)

pip install pyvergeos

Sử dụng uv

uv add pyvergeos

Từ mã nguồn

git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .

Xác thực

SDK hỗ trợ nhiều phương thức xác thực:

Tên người dùng/Mật khẩu

from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Dành cho chứng chỉ tự ký
)

Xác minh chứng chỉ SSL

Đặt verify_ssl=False chỉ cho các môi trường có chứng chỉ tự ký. Với môi trường sản xuất có chứng chỉ hợp lệ, hãy bỏ qua tham số này hoặc đặt nó thành True.

Mã thông báo API

client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)

Biến môi trường

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret

client = VergeClient.from_env()

Khuyến nghị cho môi trường sản xuất

Sử dụng biến môi trường giúp giữ thông tin xác thực ra khỏi mã nguồn của bạn và dễ dàng dùng các thông tin xác thực khác nhau giữa các môi trường.

Trình quản lý ngữ cảnh

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()

Dọn dẹp tự động

Sử dụng trình quản lý ngữ cảnh (with câu lệnh) đảm bảo kết nối được đóng đúng cách, ngay cả khi xảy ra ngoại lệ.

Tài nguyên có sẵn

SDK cung cấp quyền truy cập vào các tài nguyên VergeOS sau:

Danh mục	Tài nguyên
Máy ảo	VM, ổ đĩa, NIC, snapshot
Mạng	Mạng, quy tắc, DNS, DHCP, bí danh, máy chủ
VPN	Kết nối IPSec, giao diện và peer WireGuard
NAS/Lưu trữ	Dịch vụ, volume, chia sẻ CIFS/NFS, đồng bộ volume
Tenant	Quản lý tenant, snapshot, lưu trữ, khối mạng
Người dùng & Nhóm	Người dùng, nhóm, quyền, khóa API
Hệ thống	Cụm, nút, tầng lưu trữ, chứng chỉ
Giám sát	Cảnh báo, nhật ký, tác vụ
Sao lưu & DR	Hồ sơ snapshot, snapshot đám mây, site, đồng bộ site

Ví dụ sử dụng

Quản lý máy ảo

from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# Liệt kê tất cả VM
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} nhân")

# Lấy một VM cụ thể
vm = client.vms.get(name="web-server")

# Tạo một VM
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# Thao tác nguồn
vm.power_on()
vm.power_off()
vm.reset()

# Snapshot
vm.snapshot(retention=86400, quiesce=True)

# Nhân bản VM
clone = vm.clone(name="test-clone")

# Thêm ổ đĩa và NIC
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()

Tạo và quản lý mạng

# Tạo mạng ảo
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

# Thêm quy tắc tường lửa
network.rules.create(
    name="Cho phép SSH",
    action="accept",
    protocol="tcp",
    dest_port=22
)

Lọc tài nguyên

SDK hỗ trợ nhiều cách tiếp cận lọc:

Tham số từ khóa

# Đơn giản và dễ đọc cho các bộ lọc cơ bản
vms = client.vms.list(status="running", name="prod-*")

Chuỗi bộ lọc OData

# Cú pháp bộ lọc OData đầy đủ cho các truy vấn phức tạp
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Trình xây dựng bộ lọc

# API linh hoạt để xây dựng bộ lọc bằng chương trình
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Chờ tác vụ

Nhiều thao tác trong VergeOS chạy không đồng bộ. Hãy dùng trình quản lý tác vụ để chờ hoàn tất:

result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)

Thao tác không đồng bộ

Các thao tác như snapshot, nhân bản và di chuyển sẽ trả về ngay với một task ID. Hãy dùng client.tasks.wait() để chặn cho đến khi thao tác hoàn tất.

Xử lý lỗi

SDK cung cấp các loại ngoại lệ cụ thể cho các điều kiện lỗi khác nhau:

from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("Không tìm thấy VM")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Tác vụ {e.task_id} đã hết thời gian chờ")

Các loại ngoại lệ có sẵn

Ngoại lệ	Mô tả
VergeError	Ngoại lệ cơ sở cho mọi lỗi của SDK
AuthenticationError	Thông tin xác thực không hợp lệ hoặc token đã hết hạn
NotFoundError	Tài nguyên được yêu cầu không tồn tại
ConflictError	Xung đột trạng thái tài nguyên (ví dụ: VM đã chạy)
ValidationError	Giá trị tham số không hợp lệ
TaskTimeoutError	Tác vụ không hoàn tất trong thời gian chờ
TaskError	Tác vụ thất bại trong khi thực thi

Các trường hợp sử dụng phổ biến

• Tự động hóa hạ tầng: Cấp phát VM, mạng và lưu trữ bằng chương trình
• Tích hợp CI/CD: Tạo và hủy môi trường thử nghiệm trong pipeline
• Giám sát và báo cáo: Truy vấn trạng thái tài nguyên và tạo báo cáo kiểm kê
• Tự động hóa sao lưu: Lên lịch và quản lý snapshot cùng bản sao lưu đám mây
• Cấp phát đa thuê bao: Tự động hóa việc tạo tenant và phân bổ tài nguyên

Tài liệu và tài nguyên

Để có tài liệu đầy đủ, bao gồm tất cả các phương thức có sẵn và ví dụ sử dụng chi tiết, hãy truy cập kho lưu trữ chính thức:

• Kho lưu trữ GitHub
• Gói PyPI

Hỗ trợ

Nếu bạn gặp sự cố hoặc có yêu cầu tính năng, vui lòng mở một issue trên kho lưu trữ GitHub:

https://github.com/verge-io/pyvergeos/issues

Tài nguyên bổ sung

• Tài liệu Python
• Tài liệu API VergeOS
• Mô-đun PowerShell PSVergeOS - Giải pháp thay thế PowerShell
• Nhà cung cấp Terraform - Hạ tầng dưới dạng mã