> 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-yu-devops/05-ansible.md).

# Ansible 集合

Ansible 将无代理、基于推送的自动化引入基础设施管理。该 **vergeio.vergeos** Ansible 集合通过专为 VergeOS 构建的模块和一个清单插件扩展了 Ansible，使您能够管理 VM 快照、使用标签组织资源、导入 VM 镜像，并在多个站点之间动态发现基础设施——ทั้งหมด都通过熟悉的 YAML playbook 完成。

## 集合概览

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

| 详细说明        | 值                                                                |
| ----------- | ---------------------------------------------------------------- |
| **命名空间**    | `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 Keys** 在 VergeOS UI 中，并提供 Bearer token 身份验证，无需用户名/密码凭据。

## 模块

该集合为 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`** | 创建和管理标签类别（例如，“Environment”、“Department”） |
| **`vergeio.vergeos.tag`**          | 在类别内应用和管理单个标签                            |

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

- name: 将 VM 标记为生产环境
  vergeio.vergeos.tag:
    category: "Environment"
    name: "Production"
    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["按 OS 家族"]
    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 家族** | `os_linux`, `os_windows`                 | 特定于 OS 的 playbook    |
| **集群**    | `cluster_compute01`, `cluster_compute02` | 感知集群的维护              |
| **节点**    | `node_node1`, `node_node2`               | 节点级操作                |

### 主机变量

每个发现的 VM 都会暴露 20 多个主机变量，包括 VM ID、名称、CPU 核心数、RAM、OS 家族、电源状态、集群分配、节点位置、网络配置、标签，以及用于高级用例的完整 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: "Environment", description: "部署环境" }
        - { name: "Department", description: "业务部门负责人" }
        - { name: "Compliance", description: "合规框架" }
        - { name: "Backup", description: "备份策略层级" }

    - name: 将环境标签应用到 VM
      vergeio.vergeos.tag:
        category: "Environment"
        name: "Production"
        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: "Environment"
        name: "Template"
        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["配置 OS<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 供应和配置的 stages。

### Jenkins

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

### GitHub Actions

在 GitHub Actions 工作流中使用 `ansible-playbook` action 来运行由 pull request 驱动的基础设施变更。

### AWX / Tower

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

## 最佳实践

### 凭据管理

* **绝不要** 在 playbook 或清单文件中硬编码凭据——请使用环境变量或 Ansible Vault
* **使用 API 密钥** 用于生产中的服务账户——它们支持 IP 白名单和过期日期
* **轮换凭据** 定期轮换，并通过 VergeOS UI 审计 API 密钥使用情况

### 清单策略

* **启用缓存** 以减少 API 调用并加快 playbook 运行速度
* **使用过滤器** 将清单范围限定到相关 VM——避免拉取整个环境
* **按环境分离清单** 每个环境（dev、staging、production）分别使用，以确保安全

### 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/product-guide/tools-integrations/python-sdk/)
* [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/zh/mo-kuai-8-kai-fa-yu-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.