> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/05-ansible.md).

# Bộ sưu tập Ansible

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](https://github.com/verge-io/ansible-collection-vergeos) |

### Cài đặt

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

```bash
# 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:

```bash
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:

```bash
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.

```yaml
- 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              |

```yaml
- 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.

{% hint style="warning" %}
**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.
{% endhint %}

### Cấu hình Inventory

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

```yaml
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:

```mermaid
flowchart TD
    A["API VergeOS"] --> B["Plugin vergeos_vms"]
    B --> C["Theo site"]
    B --> D["Theo trạng thái"]
    B --> E["Theo thẻ"]
    B --> F["Theo tenant"]
    B --> G["Theo họ hệ điều hành"]
    B --> H["Theo cụm"]
    B --> I["Theo nút"]

    C --> J["datacenter_east<br/>datacenter_west"]
    D --> K["status_running<br/>status_stopped"]
    E --> L["tag_Production<br/>tag_Development"]
    F --> M["tenant_acme<br/>tenant_globex"]

    style B fill:#4a9eff,color:#fff
    style A fill:#2ecc71,color:#fff
```

| 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:

```yaml
---
- 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:

```yaml
---
- 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:

```yaml
---
- 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ó.

```mermaid
flowchart LR
    A["Terraform"] --> B["Cấp phát VM<br/>& Mạng"]
    B --> C["Inventory động"]
    C --> D["Ansible"]
    D --> E["Cấu hình OS<br/>Cài đặt phần mềm<br/>Áp dụng chính sách"]

    style A fill:#7b42f5,color:#fff
    style D fill:#ee4444,color:#fff
    style C fill:#4a9eff,color:#fff
```

| 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:

```yaml
- 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ụ

{% hint style="info" %}
**Đế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.
{% endhint %}

{% hint style="info" %}
**Đế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.
{% endhint %}

## Đọc thêm

* [Ansible Collection — GitHub](https://github.com/verge-io/ansible-collection-vergeos)
* [Ansible Galaxy — vergeio.vergeos](https://galaxy.ansible.com/vergeio/vergeos)
* [pyvergeos Python SDK — PyPI](https://pypi.org/project/pyvergeos/)
* [Tài liệu VergeOS — Python SDK](https://docs.verge.io/product-guide/tools-integrations/python-sdk/)
* [Tài liệu Ansible](https://docs.ansible.com/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/vi/module-8-nha-phat-trien-and-devops/05-ansible.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.