> 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/zh/mo-kuai-8-kai-fa-zhe-yu-devops/05-ansible.md).

# Ansible 集合

使用 vergeio.vergeos Ansible 集合自动化 VergeOS 基础设施——包括虚拟机快照、标记和导入模块，以及面向多站点环境的动态清单插件。

Ansible 为基础设施管理带来无代理、基于推送的自动化。 **vergeio.vergeos** Ansible 集合通过专为 VergeOS 构建的模块和清单插件扩展 Ansible，使您能够管理 VM 快照、使用标签组织资源、导入 VM 映像，并跨多个站点动态发现基础设施——全部通过熟悉的 YAML playbook 完成。

## 集合概述

VergeOS Ansible 集合发布在 Ansible Galaxy 上，并通过 **pyvergeos** Python SDK 直接与 VergeOS REST API 集成。

| 详情          | 值                                                                |
| ----------- | ---------------------------------------------------------------- |
| **命名空间**    | `vergeio`                                                        |
| **集合**      | `vergeos`                                                        |
| **完整参考**    | `vergeio.vergeos`                                                |
| **Python**  | >= 3.9                                                           |
| **Ansible** | >= 2.14.0                                                        |
| **SDK 依赖项** | `pyvergeos` >= 1.0.1                                             |
| **源代码**     | [GitHub](https://github.com/verge-io/ansible-collection-vergeos) |

### 安装

从 Ansible Galaxy 安装该集合：

```bash
# 从 Galaxy 安装（推荐）
ansible-galaxy collection install vergeio.vergeos

# 安装所需的 Python SDK
pip install pyvergeos
```

对于开发或离线环境，请从源代码构建并安装：

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

### 身份验证

该集合使用环境变量进行 API 身份验证，将凭据保留在 playbook 和清单文件之外：

```bash
export VERGEOS_HOST="https://vergeos.example.com"
export VERGEOS_USERNAME="admin"
export VERGEOS_PASSWORD="your-password"
export VERGEOS_INSECURE="true"   # 对于自签名 SSL 证书，设为 true
```

或者，您也可以对 CI/CD 管道等非交互式场景使用 API 密钥身份验证。API 密钥在以下位置创建： **系统 > 用户 > \[选择用户] > API 密钥** 在 VergeOS UI 中，并提供 Bearer 令牌身份验证，无需用户名/密码凭据。

## 模块

该集合提供用于 VM 生命周期操作、标签和映像管理的模块。每个模块均通过 pyvergeos SDK 与 VergeOS API 通信。

### VM 快照模块

该 `vergeio.vergeos.vm_snapshot` 模块以编程方式创建和管理 VM 快照——适用于备份自动化、变更前检查点和灾难恢复工作流。

```yaml
- name: 创建数据库服务器的快照
  vergeio.vergeos.vm_snapshot:
    vm_name: "db-server-01"
    description: "升级前快照"
    retention: 86400 # 保留 24 小时（秒）
    quiesce: true # 静默处理客户机文件系统
```

### 标签管理模块

标签提供了用于组织 VergeOS 资源的灵活分类系统。该集合包含两个标签管理模块：

| 模块                                 | 用途                     |
| ---------------------------------- | ---------------------- |
| **`vergeio.vergeos.tag_category`** | 创建和管理标签类别（例如“环境”、“部门”） |
| **`vergeio.vergeos.tag`**          | 在类别中应用和管理单个标签          |

```yaml
- name: 创建环境标签类别
  vergeio.vergeos.tag_category:
    name: "环境"
    description: "部署环境分类"

- name: 将 VM 标记为生产环境
  vergeio.vergeos.tag:
    category: "环境"
    name: "生产环境"
    resource_type: "vm"
    resource_name: "web-server-01"
```

### VM 导入功能

该集合从已上传至 VergeOS 的 OVA 模板部署 VM—— `vm_import` 模块通过名称或 ID 引用现有 OVA，CPU 和 RAM 均取自 OVA 本身。请先上传 OVA（通过 UI 或 API），然后运行 playbook 创建 VM。

## 动态清单插件

该 `vergeos_vms` 清单插件查询 VergeOS API，以动态发现 VM 并构建 Ansible 清单——无需维护静态主机文件。

{% hint style="warning" %}
**仅 API 清单**

清单插件从 VergeOS API 检索 VM 元数据。它 **不会** 设置 `ansible_host` ，并且开箱即不支持直接 SSH 连接。您必须配置 `ansible_host` ，可通过主机变量、compose 规则或单独的连接策略来执行基于 SSH 的 playbook。
{% endhint %}

### 清单配置

创建清单文件（例如， `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

# 可选过滤器
filters:
  status: "running"
  name_pattern: "prod-*"

# 为大型环境启用缓存
cache: true
cache_plugin: jsonfile
cache_connection: /tmp/vergeos_inventory_cache
cache_timeout: 300
```

### 自动分组

该插件会根据多个维度自动将发现的 VM 组织到各个组中：

```mermaid
flowchart TD
    A["VergeOS API"] --> B["vergeos_vms 插件"]
    B --> C["按站点"]
    B --> D["按状态"]
    B --> E["按标签"]
    B --> F["按租户"]
    B --> G["按操作系统系列"]
    B --> H["按集群"]
    B --> I["按节点"]

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

| 分组维度       | 示例组                                      | 使用场景               |
| ---------- | ---------------------------------------- | ------------------ |
| **站点**     | `datacenter_east`, `datacenter_west`     | 将 playbook 定向到特定位置 |
| **状态**     | `status_running`, `status_stopped`       | 仅在活动 VM 上运行任务      |
| **标签**     | `tag_Production`, `tag_Development`      | 特定于环境的配置           |
| **租户**     | `tenant_acme`, `tenant_globex`           | 多租户自动化             |
| **操作系统系列** | `os_linux`, `os_windows`                 | 特定于操作系统的 playbook  |
| **集群**     | `cluster_compute01`, `cluster_compute02` | 感知集群的维护            |
| **节点**     | `node_node1`, `node_node2`               | 节点级操作              |

### 主机变量

每个发现的 VM 都会公开超过 20 个主机变量，包括 VM ID、名称、CPU 核心数、RAM、操作系统系列、电源状态、集群分配、节点位置、网络配置、标签以及用于高级用例的完整 VM 数据字典。

## Playbook 模式

### 多站点快照编排

使用基于标签的过滤与动态清单，在各站点间编排快照：

```yaml
---
- name: 为所有站点中的全部生产数据库创建快照
  hosts: tag_Production:&os_linux
  gather_facts: false

  tasks:
    - name: 创建维护前快照
      vergeio.vergeos.vm_snapshot:
        vm_name: "{{ inventory_hostname }}"
        description: "计划维护快照 - {{ ansible_date_time.date }}"
        retention: 172800 # 保留 48 小时
        quiesce: true
      delegate_to: localhost
```

### 标签基础设施设置

在整个 VergeOS 环境中建立一致的标签分类体系：

```yaml
---
- name: 配置标签基础设施
  hosts: localhost
  connection: local

  tasks:
    - name: 创建标签类别
      vergeio.vergeos.tag_category:
        name: "{{ item.name }}"
        description: "{{ item.description }}"
      loop:
        - { name: "环境", description: "部署环境" }
        - { name: "部门", description: "业务单元所有者" }
        - { name: "合规", description: "监管框架" }
        - { name: "备份", description: "备份策略层级" }

    - name: 向 VM 应用环境标签
      vergeio.vergeos.tag:
        category: "环境"
        name: "生产环境"
        resource_type: "vm"
        resource_name: "{{ item }}"
      loop:
        - "db-server-01"
        - "web-server-01"
        - "app-server-01"
```

### Windows VM 导入工作流

自动从 OVA 文件导入 Windows VM 模板：

```yaml
---
- name: 导入 Windows Server 模板
  hosts: localhost
  connection: local

  tasks:
    # 请先将 win2022-standard.ova 上传至 VergeOS（通过 UI 或 API）；
    # vm_import 通过文件名或 ID 引用现有 OVA。
    - name: 从 OVA 导入 Windows Server 2022
      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: 为导入的模板添加标签
      vergeio.vergeos.tag:
        category: "环境"
        name: "模板"
        resource_type: "vm"
        resource_name: "win2022-template"
```

## 集成模式

### Terraform + Ansible 管道

一种常见模式是将 Terraform 用于预配，并将 Ansible 用于配置：Terraform 声明基础设施，Ansible 配置其中运行的内容。

```mermaid
flowchart LR
    A["Terraform"] --> B["预配 VM<br/>和网络"]
    B --> C["动态清单"]
    C --> D["Ansible"]
    D --> E["配置操作系统<br/>安装软件<br/>应用策略"]

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

| 阶段     | 工具        | 职责                        |
| ------ | --------- | ------------------------- |
| **预配** | Terraform | 创建 VM、网络、用户和驱动器           |
| **发现** | 清单        | 查询 VergeOS API 以获取新创建的 VM |
| **配置** | Ansible   | 安装软件包、配置服务、应用安全基线         |
| **验证** | Ansible   | 运行冒烟测试、验证连接性、检查合规性        |

### Python SDK + Ansible

对于需要超出 YAML playbook 所提供功能的编程逻辑的复杂工作流，请结合使用 **pyvergeos** Python SDK 与 Ansible：

```yaml
- name: 使用 Python 的自定义 VergeOS 自动化
  hosts: localhost
  tasks:
    - name: 通过 pyvergeos 运行高级 VM 操作
      ansible.builtin.script:
        cmd: scripts/bulk_snapshot.py
      environment:
        VERGEOS_HOST: "{{ vergeos_host }}"
        VERGEOS_USERNAME: "{{ vergeos_user }}"
        VERGEOS_PASSWORD: "{{ vergeos_password }}"
```

### CI/CD 集成

Ansible playbook 可自然集成到 CI/CD 管道中，以实现基础设施自动化：

### GitLab CI

从以下位置触发 Ansible playbook： `.gitlab-ci.yml` 阶段，在合并到 main 时自动执行 VM 预配和配置。

### Jenkins

使用 Jenkins 的 Ansible 插件将 playbook 作为构建步骤运行，并通过 Jenkins 凭据存储管理凭据。

### GitHub Actions

在 GitHub Actions 工作流中使用 `ansible-playbook` 操作来执行 Ansible playbook，以支持由拉取请求驱动的基础设施变更。

### AWX / Tower

部署 Ansible AWX，以获得基于 Web 的 UI、RBAC，以及针对 VergeOS 环境的计划 playbook 执行。

## 最佳实践

### 凭据管理

* **绝不硬编码凭据** 到 playbook 或清单文件中——请使用环境变量或 Ansible Vault
* **使用 API 密钥** 用于生产环境中的服务帐户——它们支持 IP 允许列表和到期日期
* **轮换凭据** 定期进行，并通过 VergeOS UI 审核 API 密钥的使用情况

### 清单策略

* **启用缓存** 以便在大型环境中减少 API 调用并加快 playbook 运行速度
* **使用过滤器** 将清单范围限定到相关 VM——避免拉取整个环境
* **分离清单** 按环境（开发、预发布、生产）分开，以提高安全性

### Playbook 设计

* **使用 `delegate_to: localhost`** 用于 VergeOS API 调用——模块与 API 通信，而不是通过 SSH 与客户机 VM 通信
* **利用标签** 进行目标选择——它们提供灵活的多维分组系统
* **实现幂等性** ——设计可安全重复运行且不会产生副作用的 playbook

{% hint style="info" %}
**从 VMware 迁移？**

该 `vergeio.vergeos` 该集合遵循您已熟悉的标准 Ansible 模式：用于资源操作的 API 驱动模块，以及用于主机发现的动态清单插件。单个清单配置可同时查询多个 VergeOS 站点——无需处理每站点连接。
{% endhint %}

{% hint style="info" %}
**从 Nutanix 迁移？**

该 `vergeio.vergeos` 该集合遵循标准 Ansible 模式：API 驱动模块加动态清单插件。一个清单配置可同时面向多个 VergeOS 站点，无需中央管理平面。
{% endhint %}

## 延伸阅读

* [Ansible 集合 — 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/)
* [VergeOS 文档 — Python SDK](https://docs.verge.io/automate-protect-and-extend/zh/ji-cheng-yu-api/python-sdk.md)
* [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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/learn-the-platform/zh/mo-kuai-8-kai-fa-zhe-yu-devops/05-ansible.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
