Python SDK (pyvergeos)

Tự động hóa hạ tầng VergeOS với Python SDK pyvergeos — vòng đời VM, mạng, đa tenant, lưu trữ và khôi phục sau thảm họa từ các script Python.

Tính năng pyvergeos SDK cung cấp một giao diện kiểu Python, có chú thích kiểu cho toàn bộ VergeOS REST API. Thay vì tạo các yêu cầu HTTP thô, bạn làm việc với các trình quản lý tài nguyên — client.vms, client.networks, client.tenants — ánh xạ trực tiếp đến các đối tượng VergeOS. SDK xử lý xác thực, phân trang, thử lại và thăm dò tác vụ bất đồng bộ để các script tự động hóa của bạn luôn gọn gàng và tập trung vào logic nghiệp vụ.

Yêu cầu & Cài đặt

Điều kiện tiên quyết:

• Python 3.9 hoặc mới hơn
• VergeOS 26.0 hoặc mới hơn
• Hoạt động trên Windows, macOS và Linux

Cài đặt từ PyPI (khuyến nghị):

pip install pyvergeos

Hoặc với uv (lựa chọn nhanh hơn):

uv add pyvergeos

Từ mã nguồn (phát triển):

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

Xác thực

SDK hỗ trợ ba phương thức xác thực, mỗi phương thức phù hợp với các môi trường khác nhau.

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

Cách đơn giản nhất cho script tương tác và phát triển:

from pyvergeos import VergeClient

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

API Token

Cho tự động hóa sản xuất khi bạn có sẵn một API key đã tạo trước:

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

Biến môi trường

Cách được khuyến nghị cho môi trường sản xuất — giữ thông tin xác thực ngoài mã nguồn:

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
export VERGE_VERIFY_SSL=false      # Tùy chọn
export VERGE_TIMEOUT=30            # Tùy chọn
export VERGE_RETRY_TOTAL=3         # Tùy chọn
export VERGE_RETRY_BACKOFF=1       # Tùy chọn

client = VergeClient.from_env()

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

Luôn dùng trình quản lý ngữ cảnh trong mã sản xuất để đảm bảo kết nối được đóng đúng cách, ngay cả khi có ngoại lệ xảy ra:

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
    for vm in vms:
        print(f"{vm.name}: {vm.ram}MB RAM")
# Kết nối sẽ tự động đóng ở đây

Trình quản lý tài nguyên

Mỗi loại tài nguyên VergeOS đều được hiển thị thông qua một trình quản lý tài nguyên trên đối tượng client. Mỗi trình quản lý cung cấp list(), get(), create()và các phương thức hành động.

Máy ảo

client.vms — Tạo, cấu hình, điều khiển nguồn, nhân bản, snapshot và quản lý ổ đĩa/NIC cho VM.

Mạng

client.networks — Mạng ảo, quy tắc tường lửa, DHCP, DNS và quản lý nguồn mạng.

Tenants

client.tenants — Cấp phát đa thuê bao, cô lập tài nguyên, snapshot, khối lưu trữ và khối mạng.

NAS & Lưu trữ

client.nas — Dịch vụ NAS, volume, chia sẻ CIFS/NFS và đồng bộ volume.

Khôi phục sau thảm họa

client.dr — Snapshot đám mây, đồng bộ site và quy trình khôi phục.

Người dùng & Nhóm

client.users — Tài khoản người dùng, nhóm, quyền và quản lý khóa API.

Tác vụ & Giám sát

client.tasks — Theo dõi tác vụ bất đồng bộ, chờ đợi, thời gian chờ. Ngoài ra: cảnh báo và nhật ký.

Hệ thống & GPU

client.clusters, client.nodes, client.gpu — Thông tin cụm/nút, các tầng lưu trữ, quản lý thiết bị GPU.

Bảng tài nguyên đầy đủ

Danh mục	Tài nguyên khả dụng
Máy ảo	VM, ổ đĩa, NIC, snapshot
Mạng	Mạng, quy tắc tường lửa, 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ụ NAS, volume, chia sẻ CIFS/NFS, đồng bộ volume
Tenants	Quản lý tenant, snapshot, khối 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, các 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

Lọc tài nguyên

SDK cung cấp ba cách để lọc tài nguyên, từ các tham số từ khóa đơn giản đến một trình tạo bộ lọc OData đầy đủ.

Tham số từ khóa

Cách đơn giản nhất cho các bộ lọc cơ bản — truyền trực tiếp tên trường:

# Tìm tất cả VM Linux đang chạy
vms = client.vms.list(status="running", os_family="linux")

# Khớp ký tự đại diện
vms = client.vms.list(name="prod-*")

Chuỗi lọc OData

Đối với các truy vấn phức tạp, hãy truyền trực tiếp biểu thức lọc OData:

# Kết hợp điều kiện bằng toán tử
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Trình tạo bộ lọc (Fluent API)

Xây dựng bộ lọc bằng lập trình với an toàn kiểu và tự động hoàn thành:

from pyvergeos import Filter

# Chuỗi fluent với các phương thức toán tử
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Các toán tử lọc khả dụng:

Phương thức	Toán tử OData	Ví dụ
.eq()	eq	Filter().eq("status", "running")
.ne()	ne	Filter().ne("os_family", "windows")
.gt()	gt	Filter().gt("ram", 4096)
.lt()	lt	Filter().lt("cpu_cores", 8)
.ge()	ge	Filter().ge("ram", 2048)
.le()	le	Filter().le("ram", 8192)
.and_()	và	Nối nhiều điều kiện
.or_()	hoặc	Kết hợp các điều kiện thay thế

Xử lý tác vụ bất đồng bộ

Nhiều thao tác VergeOS — snapshot, nhân bản, di chuyển — chạy bất đồng bộ và trả về ngay một task ID. SDK cung cấp trình quản lý tác vụ để thăm dò trạng thái hoàn thành:

# Snapshot trả về một tham chiếu tác vụ
result = vm.snapshot(retention=86400, quiesce=True)

# Chờ snapshot hoàn tất (chặn tối đa 300 giây)
task = client.tasks.wait(result["task"], timeout=300)
print(f"Snapshot hoàn tất: {task}")

Nếu tác vụ không hoàn thành trong thời gian chờ, TaskTimeoutError sẽ được ném ra cùng với thuộc tính task_id để bạn có thể kiểm tra trạng thái sau:

from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Tác vụ {e.task_id} vẫn đang chạy — hãy kiểm tra lại sau")

Xử lý lỗi

SDK cung cấp một hệ thống ngoại lệ có cấu trúc để bạn có thể bắt các chế độ lỗi cụ thể:

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 thành trong thời gian chờ
TaskError	Tác vụ thất bại trong quá trình thực thi

from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("Không tìm thấy VM — hãy kiểm tra tên")
except AuthenticationError:
    print("Xác thực thất bại — hãy kiểm tra thông tin đăng nhập")

Cấu hình thử lại

SDK tự động thử lại các lỗi tạm thời (HTTP 429, 500, 502, 503, 504) với cơ chế backoff lũy tiến:

client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # Số lần thử lại tối đa (mặc định: 3)
    retry_backoff_factor=2,   # Hệ số backoff (mặc định: 1)
)

Đặt retry_total=0 để tắt hoàn toàn việc thử lại cho các thao tác nhạy cảm về thời gian.

Chuyển đổi ngữ cảnh Tenant

pyvergeos có thể kết nối vào các ngữ cảnh tenant từ hệ thống host, cho phép các script tự động hóa tập trung quản lý tài nguyên trên nhiều tenant:

# Lấy một tenant từ hệ thống host
tenant = client.tenants.get(name="customer-a")

# Kết nối vào ngữ cảnh của tenant
tenant_client = tenant.connect()

# Bây giờ quản lý tài nguyên BÊN TRONG tenant
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"VM của tenant: {vm.name}")

# Tạo một mạng bên trong tenant
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)

Điều này đặc biệt hữu ích cho Các MSP và nhà cung cấp dịch vụ cần tự động hóa việc cấp phát trên hàng chục hoặc hàng trăm môi trường tenant từ một script duy nhất.

Ví dụ thực tế

Quản lý vòng đời VM

with VergeClient.from_env() as client:
    # Tạo một VM mới
    vm = client.vms.create(
        name="web-server-01",
        ram=4096,
        cpu_cores=2,
        os_family="linux"
    )

    # Thêm một ổ dữ liệu 50 GB
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # Gắn vào một mạng
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # Bật nguồn
    vm.power_on()
    print(f"VM {vm.name} đang chạy")

Mạng với quy tắc tường lửa

with VergeClient.from_env() as client:
    # Tạo một mạng
    network = client.networks.create(
        name="web-tier",
        network_address="10.20.1.0/24",
        ip_address="10.20.1.1",
        dhcp_enabled=True
    )
    network.power_on()

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

Thao tác hàng loạt với lọc

with VergeClient.from_env() as client:
    # Snapshot tất cả VM sản xuất đang chạy
    prod_vms = client.vms.list(name="prod-*", status="running")

    for vm in prod_vms:
        result = vm.snapshot(retention=86400, quiesce=True)
        task = client.tasks.wait(result["task"], timeout=300)
        print(f"Đã tạo snapshot cho {vm.name}")

Báo cáo kiểm kê đa tenant

with VergeClient.from_env() as client:
    for tenant in client.tenants.list():
        tenant_client = tenant.connect()
        vms = tenant_client.vms.list()
        print(f"\n--- {tenant.name} ---")
        for vm in vms:
            print(f"  {vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} lõi")

Ghi chú quan trọng

An toàn luồng

Client pyvergeos không an toàn luồng. Nếu bạn cần các thao tác đồng thời, hãy tạo các VergeClient riêng biệt cho từng luồng. Với các khối lượng công việc thực sự song song, hãy cân nhắc govergeos Go SDK được thiết kế để sử dụng đồng thời với goroutine.

Bạn đang chuyển từ VMware hay Nutanix?

pyvergeos cung cấp ba mẫu sử dụng đáng biết ngay từ đầu:

• Lọc — một Filter() fluent tạo ra các biểu thức kiểu OData (.eq(), .gt(), .and_(), .or_()), hoặc bạn có thể truyền một chuỗi OData thô vào list(filter=...).
• Thăm dò tác vụ — các thao tác bất đồng bộ trả về một tham chiếu tác vụ; client.tasks.wait(task_id, timeout=...) chặn cho đến khi hoàn tất và ném TaskTimeoutError khi hết thời gian chờ.
• Ngữ cảnh tenant — tenant.connect() trả về một client nằm trong phạm vi tenant, vì vậy cùng một script có thể điều khiển hệ thống host và bất kỳ tenant con nào mà không cần kết nối lại tới một endpoint khác.

Tài nguyên bổ sung

• Kho lưu trữ GitHub — Mã nguồn, vấn đề và đóng góp
• Gói PyPI — Bản phát hành mới nhất và lịch sử phiên bản
• Tài liệu VergeOS API