VMware REST Ansible 内容集合简介

当前 community.vmware 集合中的 VMware Ansible 模块非常受欢迎。根据 GitHub 数据，它是仅次于 community.general 的第二大被分叉的集合。Ansible 的 VMware 模块和插件得益于数十位用户的贡献。许多 IT 基础设施工程师依靠简单的 Ansible Playbook 来管理其 VMware 基础设施。当前大多数 VMware 模块都是基于名为 pyVmomi（也称为 vSphere Automation SDK for Python）的依赖 Python 库构建的。

为什么要创建新的 VMware Ansible 内容集合？

VMware 最近推出了适用于 vSphere 6.0 及更高版本的 vSphere REST API，它可能会取代 community.vmware 集合中使用的现有 SOAP SDK。

自 REST API 首次发布以来，vSphere 对 REST API 的支持一直在不断改进。此外，不再需要任何依赖的 Python 包。为了维护 community.vmware 集合中现有的 VMware 模块，现在新创建的 vmware.vmware_rest 集合中提供了一组专门用于与 VMware REST API 交互的模块。

如果您将使用 VMware vSphere API（SOAP）的模块与使用 REST API 的模块进行比较，您会注意到 REST API 模块的功能尚未完整，因为这是该集合的早期版本。例如，目前无法使用 vmware.vmware_rest 集合中的模块创建集群或文件夹，但 API 提供了您需要的全部功能，以便将来启用 VMware 虚拟机并提供更多功能。

使用 VMware REST API

为了理解新模块如何在新的 REST API 上运行，让我们首先了解一下 REST API 本身。例如，com.vmware.vcenter.vm.power API 端点会更改虚拟机的电源状态。它等效于以下示例 URL

https://vcenter.test/rest/vcenter/vm/\$vm/power

在 vCenter 7.0 版本中，公开了 723 个 REST 端点，可以使用以下 curl 命令发现这些端点

$ curl -k https://vcenter.test/rest/com/vmware/vapi/metadata/cli/command|jq -r ".[][].path"|uniq|wc -l
723

VMware REST API 以 Swagger 2.0 格式记录。您可以在 vCenter 节点的以下目录路径中找到 JSON 文件

root@vcenter [ /etc/vmware-vapi/apiexplorer/json ]# ls -lh
total 3.3M
-rw-r--r-- 1 vapiEndpoint users  145 Aug 31 15:37 api.json
-rw-r--r-- 1 vapiEndpoint users 396K Aug 31 15:36 appliance.json
-rw-r--r-- 1 vapiEndpoint users 153K Aug 31 15:36 cis.json
-rw-r--r-- 1 vapiEndpoint users 272K Aug 31 15:37 content.json
-rw-r--r-- 1 vapiEndpoint users 395K Aug 31 15:36 esx.json
-rw-r--r-- 1 vapiEndpoint users 153K Aug 31 15:36 stats.json
-rw-r--r-- 1 vapiEndpoint users 176K Aug 31 15:37 vapi.json
-rw-r--r-- 1 vapiEndpoint users 1.8M Aug 31 15:36 vcenter.json

总而言之，vmware.vmware_rest 集合已准备好使用所有这些 REST 端点，并以格式良好的文档中提供了描述。

构建 vmware_rest 集合

此集合中包含的模块是使用名为 vmware_rest_code_generator 的工具生成的，该工具由 Ansible 团队开发并开源。它加载 Swagger 文件，然后为每个资源自动生成一个模块，以此方式生成 300 多个模块。您会注意到，并非所有模块都已发布到集合中。为了从小处着手，我们仅针对公开的端点子集生成模块，仅那些与虚拟机管理用例相关的模块。我们可能会随着时间的推移扩展和扩展模块数量。

使用 vmware_rest 集合

以下任务检索虚拟机的列表，将其关闭，然后将其删除

- name: Collect the list of the existing VM
  vcenter_vm_info:
  register: existing_vms
  until: existing_vms is not failed

- name: Turn off the VM
  vcenter_vm_power:
    state: stop
    vm: '{{ item.vm }}'
  with_items: "{{ existing_vms.value }}"
  ignore_errors: yes

- name: Delete some VM
  vcenter_vm:
    state: absent
    vm: '{{ item.vm }}'
  with_items: "{{ existing_vms.value }}"

有关更多信息，请参阅以下 gist 文件：https://gist.github.com/goneri/6afd05397390cf5a0976f3611814949a

下载 vmware_rest 集合

此早期版本的目的是获得尽可能多的社区反馈。

该集合可在 Ansible Galaxy 上获取，并且需要以下内容

Ansible 2.9 或更高版本
Python 3.6 或更高版本
aiohttp 包

使用 ansible-galaxy 命令检索集合

# ansible-galaxy collection install vmware.vmware_rest

如果您使用 virtualenv，则可以使用以下命令安装 aiohttp

# pip install aiohttp

否则，您需要下载并安装 python3-aiohttp 包。

要阅读模块文档，请使用 ansible-doc 命令。例如，要阅读 vcenter_cluster_info 模块的文档，请参阅以下命令

# ansible-doc -t module vmware.vmware_rest.vcenter_cluster_info

vCenter 托管对象引用 ID

如果您已经在使用 community.vmware 集合，主要区别在于较新的模块依赖于 MORef ID 来识别元素，而不是对象的名称。例如，如果用户创建了一个名为 dc1 的数据中心，则使用新模块的 MORef ID 将为 datacenter-2。community.vmware 集合使用名称和文件夹。

通过直接使用 MORef ID，模块能够在没有任何耗时的初步查找的情况下与资源进行交互。

如何贡献？

由于模块是自动生成的，因此应针对代码生成器本身提出 GitHub 拉取请求，而不是针对生成的集合内容。

请随时在 GitHub 项目上报告任何问题：https://github.com/ansible-collections/vmware_rest/issues。

参考

可以通过访问 Github API 以编程方式找到每个集合的分叉数：https://api.github.com/orgs/ansible-collections/repos

例如，可以对它进行排序

method: curl -s https://api.github.com/orgs/ansible-collections/repos|jq -r -c --sort-keys '.|sort_by(.forks)|reverse|.[]|[.name, .forks]'