Bộ sưu tập Ansible

Tự động hóa hạ tầng VergeOS bằng bộ sưu tập Ansible vergeio.vergeos — các mô-đun cho snapshot VM, gắn thẻ và nhập khẩu, cùng plugin inventory động cho môi trường nhiều site.

Ansible mang đến tự động hóa không cần agent, theo cơ chế đẩy cho quản lý hạ tầng. Bộ vergeio.vergeos Bộ sưu tập Ansible mở rộng Ansible với các mô-đun được xây dựng chuyên biệt và một plugin inventory cho VergeOS, cho phép bạn quản lý snapshot VM, tổ chức tài nguyên bằng thẻ, nhập ảnh VM và tự động khám phá hạ tầng trên nhiều site — tất cả thông qua các playbook YAML quen thuộc.

Tổng quan bộ sưu tập

Bộ sưu tập VergeOS Ansible được phát hành trên Ansible Galaxy và tích hợp trực tiếp với API REST VergeOS thông qua pyvergeos SDK Python.

Chi tiết	Giá trị
Không gian tên	vergeio
Bộ sưu tập	vergeos
Tham chiếu đầy đủ	vergeio.vergeos
Python	>= 3.9
Ansible	>= 2.14.0
Phụ thuộc SDK	pyvergeos >= 1.0.1
Nguồn	GitHub

Cài đặt

Cài đặt bộ sưu tập từ Ansible Galaxy:

# Cài đặt từ Galaxy (khuyến nghị)
ansible-galaxy collection install vergeio.vergeos

# Cài đặt SDK Python cần thiết
pip install pyvergeos

Đối với môi trường phát triển hoặc ngoại tuyến, hãy build và cài đặt từ mã nguồn:

git clone https://github.com/verge-io/ansible-collection-vergeos.git
cd ansible-collection-vergeos
ansible-galaxy collection build
ansible-galaxy collection install vergeio-vergeos-*.tar.gz --force

Xác thực

Bộ sưu tập sử dụng các biến môi trường để xác thực API, giữ thông tin xác thực ra khỏi playbook và các tệp inventory của bạn:

export VERGEOS_HOST="https://vergeos.example.com"
export VERGEOS_USERNAME="admin"
export VERGEOS_PASSWORD="your-password"
export VERGEOS_INSECURE="true"   # Đặt true cho chứng chỉ SSL tự ký

Ngoài ra, bạn có thể dùng xác thực bằng khóa API cho các kịch bản không tương tác như pipeline CI/CD. Khóa API được tạo trong System > Users > [select user] > API Keys trong giao diện VergeOS và cung cấp xác thực bằng Bearer token mà không cần thông tin xác thực username/password.

Các mô-đun

Bộ sưu tập cung cấp các mô-đun cho các thao tác vòng đời VM, gắn thẻ và quản lý ảnh. Mỗi mô-đun giao tiếp với API VergeOS thông qua SDK pyvergeos.

Mô-đun Snapshot VM

Tính năng vergeio.vergeos.vm_snapshot mô-đun tạo và quản lý snapshot VM theo chương trình — hữu ích cho tự động hóa sao lưu, các điểm kiểm tra trước thay đổi và quy trình khôi phục sau thảm họa.

- name: Tạo snapshot của máy chủ cơ sở dữ liệu
  vergeio.vergeos.vm_snapshot:
    vm_name: "db-server-01"
    description: "Snapshot trước nâng cấp"
    retention: 86400 # Giữ lại trong 24 giờ (giây)
    quiesce: true # Đóng băng hệ thống tệp của máy khách

Mô-đun quản lý thẻ

Thẻ cung cấp một hệ thống phân loại linh hoạt để tổ chức các tài nguyên VergeOS. Bộ sưu tập bao gồm hai mô-đun cho quản lý thẻ:

Mô-đun	Mục đích
vergeio.vergeos.tag_category	Tạo và quản lý các danh mục thẻ (ví dụ: "Environment", "Department")
vergeio.vergeos.tag	Áp dụng và quản lý các thẻ riêng lẻ trong từng danh mục

- name: Tạo danh mục thẻ môi trường
  vergeio.vergeos.tag_category:
    name: "Environment"
    description: "Phân loại môi trường triển khai"

- name: Gắn thẻ VM là production
  vergeio.vergeos.tag:
    category: "Environment"
    name: "Production"
    resource_type: "vm"
    resource_name: "web-server-01"

Khả năng nhập VM

Bộ sưu tập này triển khai VM từ các mẫu OVA đã được tải lên VergeOS — mô-đun vm_import tham chiếu một OVA hiện có theo tên hoặc ID, và CPU cùng RAM được lấy từ chính OVA đó. Hãy tải OVA lên trước (UI hoặc API), sau đó chạy playbook để tạo VM.

Plugin Inventory động

Tính năng vergeos_vms plugin inventory truy vấn API VergeOS để tự động khám phá VM và xây dựng inventory Ansible — loại bỏ nhu cầu phải duy trì các tệp host tĩnh.

Inventory chỉ API

Plugin inventory truy xuất siêu dữ liệu VM từ API VergeOS. Nó không không thiết lập ansible_host và không hỗ trợ kết nối SSH trực tiếp ngay từ đầu. Bạn phải cấu hình ansible_host thông qua các biến host, quy tắc compose hoặc một chiến lược kết nối riêng cho việc thực thi playbook dựa trên SSH.

Cấu hình Inventory

Tạo một tệp inventory (ví dụ, vergeos_inventory.yml):

plugin: vergeio.vergeos.vergeos_vms
sites:
  - name: "datacenter-east"
    host: "https://east.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

  - name: "datacenter-west"
    host: "https://west.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

# Bộ lọc tùy chọn
filters:
  status: "running"
  name_pattern: "prod-*"

# Bật bộ nhớ đệm cho môi trường lớn
cache: true
cache_plugin: jsonfile
cache_connection: /tmp/vergeos_inventory_cache
cache_timeout: 300

Nhóm tự động

Plugin tự động tổ chức các VM được khám phá thành các nhóm dựa trên nhiều chiều:

Chiều nhóm	Nhóm ví dụ	Trường hợp sử dụng
Site	datacenter_east, datacenter_west	Nhắm playbook tới các vị trí cụ thể
Trạng thái	status_running, status_stopped	Chỉ chạy tác vụ trên các VM đang hoạt động
Thẻ	tag_Production, tag_Development	Cấu hình theo môi trường
Tenant	tenant_acme, tenant_globex	Tự động hóa đa tenant
Họ hệ điều hành	os_linux, os_windows	Playbook theo hệ điều hành
Cụm	cluster_compute01, cluster_compute02	Bảo trì nhận biết cụm
Nút	node_node1, node_node2	Thao tác cấp nút

Biến host

Mỗi VM được khám phá sẽ hiển thị hơn 20 biến host, bao gồm ID VM, tên, số lõi CPU, RAM, họ hệ điều hành, trạng thái nguồn, gán cụm, vị trí nút, cấu hình mạng, thẻ và toàn bộ từ điển dữ liệu VM để sử dụng trong các trường hợp nâng cao.

Mẫu playbook

Điều phối snapshot đa site

Dùng lọc theo thẻ với inventory động để điều phối snapshot trên nhiều site:

---
- name: Chụp snapshot cho tất cả cơ sở dữ liệu production trên các site
  hosts: tag_Production:&os_linux
  gather_facts: false

  tasks:
    - name: Tạo snapshot trước bảo trì
      vergeio.vergeos.vm_snapshot:
        vm_name: "{{ inventory_hostname }}"
        description: "Snapshot bảo trì theo lịch - {{ ansible_date_time.date }}"
        retention: 172800 # Giữ lại 48 giờ
        quiesce: true
      delegate_to: localhost

Thiết lập hạ tầng thẻ

Thiết lập một hệ thống phân loại thẻ nhất quán trên toàn bộ môi trường VergeOS của bạn:

---
- name: Cấu hình hạ tầng thẻ
  hosts: localhost
  connection: local

  tasks:
    - name: Tạo các danh mục thẻ
      vergeio.vergeos.tag_category:
        name: "{{ item.name }}"
        description: "{{ item.description }}"
      loop:
        - { name: "Environment", description: "Môi trường triển khai" }
        - { name: "Department", description: "Đơn vị kinh doanh sở hữu" }
        - { name: "Compliance", description: "Khung pháp lý" }
        - { name: "Backup", description: "Tầng chính sách sao lưu" }

    - name: Áp dụng thẻ môi trường cho VM
      vergeio.vergeos.tag:
        category: "Environment"
        name: "Production"
        resource_type: "vm"
        resource_name: "{{ item }}"
      loop:
        - "db-server-01"
        - "web-server-01"
        - "app-server-01"

Quy trình nhập VM Windows

Tự động hóa việc nhập các mẫu VM Windows từ tệp OVA:

---
- name: Nhập mẫu Windows Server
  hosts: localhost
  connection: local

  tasks:
    # Tải win2022-standard.ova lên VergeOS trước (UI hoặc API);
    # vm_import tham chiếu OVA hiện có theo tên tệp hoặc ID.
    - name: Nhập Windows Server 2022 từ OVA
      vergeio.vergeos.vm_import:
        name: "win2022-template"
        ova_file_name: "win2022-standard.ova"
        preferred_tier: "4"
        override_drive_interface: virtio
        override_nic_interface: virtio

    - name: Gắn thẻ cho mẫu đã nhập
      vergeio.vergeos.tag:
        category: "Environment"
        name: "Template"
        resource_type: "vm"
        resource_name: "win2022-template"

Mẫu tích hợp

Pipeline Terraform + Ansible

Một mẫu phổ biến kết hợp Terraform để cấp phát với Ansible để cấu hình: Terraform khai báo hạ tầng, Ansible cấu hình những gì chạy bên trong nó.

Giai đoạn	Công cụ	Trách nhiệm
Cấp phát	Terraform	Tạo VM, mạng, người dùng, ổ đĩa
Khám phá	Inventory	Truy vấn API VergeOS để lấy các VM mới được tạo
Cấu hình	Ansible	Cài đặt gói, cấu hình dịch vụ, áp dụng các chuẩn bảo mật cơ bản
Xác thực	Ansible	Chạy kiểm tra nhanh, xác minh kết nối, kiểm tra tuân thủ

SDK Python + Ansible

Đối với các quy trình làm việc phức tạp cần logic chương trình vượt ra ngoài những gì playbook YAML cung cấp, hãy kết hợp pyvergeos SDK Python với Ansible:

- name: Tự động hóa VergeOS tùy chỉnh bằng Python
  hosts: localhost
  tasks:
    - name: Thực thi các thao tác VM nâng cao qua pyvergeos
      ansible.builtin.script:
        cmd: scripts/bulk_snapshot.py
      environment:
        VERGEOS_HOST: "{{ vergeos_host }}"
        VERGEOS_USERNAME: "{{ vergeos_user }}"
        VERGEOS_PASSWORD: "{{ vergeos_password }}"

Tích hợp CI/CD

Các playbook Ansible tích hợp tự nhiên vào pipeline CI/CD cho tự động hóa hạ tầng:

GitLab CI

Kích hoạt playbook Ansible từ .gitlab-ci.yml các giai đoạn để tự động cấp phát và cấu hình VM khi gộp vào nhánh main.

Jenkins

Dùng plugin Ansible cho Jenkins để chạy playbook như các bước build, với thông tin xác thực được quản lý qua Jenkins Credential Store.

GitHub Actions

Chạy playbook Ansible trong các workflow GitHub Actions bằng ansible-playbook action cho các thay đổi hạ tầng được kích hoạt bởi pull request.

AWX / Tower

Triển khai Ansible AWX cho giao diện web, RBAC và thực thi playbook theo lịch trên các môi trường VergeOS.

Thực hành tốt nhất

Quản lý thông tin xác thực

• Không bao giờ mã hóa cứng thông tin xác thực trong playbook hoặc tệp inventory — hãy dùng biến môi trường hoặc Ansible Vault
• Dùng khóa API cho các tài khoản dịch vụ trong môi trường sản xuất — chúng hỗ trợ danh sách IP cho phép và ngày hết hạn
• Luân chuyển thông tin xác thực thường xuyên và kiểm tra việc sử dụng khóa API qua giao diện VergeOS

Chiến lược Inventory

• Bật bộ nhớ đệm cho môi trường lớn để giảm số lần gọi API và tăng tốc chạy playbook
• Dùng bộ lọc để giới hạn inventory vào các VM liên quan — tránh kéo toàn bộ môi trường
• Tách inventory theo từng môi trường (dev, staging, production) để an toàn

Thiết kế playbook

• Sử dụng delegate_to: localhost cho các lời gọi API VergeOS — các mô-đun giao tiếp với API, không phải với VM khách qua SSH
• Tận dụng thẻ để nhắm mục tiêu — chúng cung cấp một hệ thống phân nhóm linh hoạt, đa chiều
• Triển khai tính idempotent — thiết kế playbook có thể chạy lại an toàn mà không có tác dụng phụ

Đến từ VMware?

Tính năng vergeio.vergeos Bộ sưu tập này tuân theo mẫu Ansible tiêu chuẩn mà bạn đã biết: các mô-đun điều khiển bằng API cho thao tác tài nguyên cộng với một plugin inventory động để khám phá host. Một cấu hình inventory duy nhất có thể truy vấn nhiều site VergeOS cùng lúc — không cần xoay vòng kết nối theo từng site.

Đến từ Nutanix?

Tính năng vergeio.vergeos Bộ sưu tập này tuân theo mẫu Ansible tiêu chuẩn: các mô-đun điều khiển bằng API cộng với một plugin inventory động. Một cấu hình inventory có thể nhắm tới nhiều site VergeOS đồng thời, mà không cần một nền tảng quản lý tập trung.

Đọc thêm

• Ansible Collection — GitHub
• Ansible Galaxy — vergeio.vergeos
• pyvergeos Python SDK — PyPI
• Tài liệu VergeOS — Python SDK
• Tài liệu Ansible