community.general.xenserver_guest 模块 – 管理 Citrix Hypervisor/XenServer 主机或池上运行的虚拟机
注意
此模块是 community.general 集合 (版本 10.1.0) 的一部分。
如果您正在使用 ansible 包，则您可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。
要在剧本中使用它，请指定：community.general.xenserver_guest。
概要
此模块可用于从模板或其他虚拟机创建新的虚拟机，修改各种虚拟机组件（如网络和磁盘），重命名虚拟机以及删除虚拟机及其关联组件。
要求
执行此模块的主机需要以下要求。
XenAPI
参数
参数 |
注释 |
|---|---|
虚拟机的 CD-ROM 配置。 所有参数都区分大小写。 |
|
来自 XenServer ISO 库之一的 ISO 映像的文件名（暗示 如果 |
|
CD-ROM 的类型。使用 选项
|
|
定义要在虚拟机上设置的自定义虚拟机参数列表。 对于熟悉通过 xe CLI 管理虚拟机参数的高级用户很有用。 自定义值对象包含两个字段 |
|
虚拟机参数名称。 |
|
虚拟机参数值。 |
|
要添加到虚拟机的磁盘列表。 所有参数都区分大小写。 不支持删除或分离虚拟机的现有磁盘。 新的磁盘需要指定 需要关闭虚拟机才能重新配置磁盘大小。 |
|
磁盘名称。 |
|
磁盘描述。 |
|
带单位的磁盘大小。单位必须是： 如果未指定单位，则假定大小为字节。 |
|
以字节为单位的磁盘大小。 |
|
以千兆字节为单位的磁盘大小。 |
|
以千字节为单位的磁盘大小。 |
|
以兆字节为单位的磁盘大小。 |
|
以太字节为单位的磁盘大小。 |
|
用于创建磁盘的存储库。如果未指定，将使用默认 SR。不能用于将磁盘移动到其他 SR。 |
|
用于创建磁盘的 SR 的 UUID。如果 SR 名称不唯一，则使用此参数。 |
|
虚拟机的目标文件夹。 此参数区分大小写。 示例 folder: /folder1/folder2 |
|
忽略警告并完成操作。 此参数对于删除运行状态下的虚拟机或重新配置需要关闭虚拟机的虚拟机参数很有用。 选项
|
|
管理虚拟机的硬件参数。重新配置这些参数需要关闭虚拟机。 |
|
内存大小（MB）。 |
|
每个插槽的核心数。 |
|
CPU数量。 |
|
将作为虚拟机主服务器的 XenServer 主机的名称。 此参数区分大小写。 |
|
XenServer 主机或 XenServer 集群主机的 hostname 或 IP 地址。 如果任务中未指定此值，则将使用环境变量 默认值： |
|
将虚拟机转换为模板。 选项
|
|
是否从模板、现有虚拟机或快照创建链接克隆。如果否，则会创建完整副本。 这等效于 XenCenter 中的 选项
|
|
要操作的虚拟机的名称。 在 XenServer 上运行的虚拟机不一定具有唯一的名称。如果找到多个具有相同名称的虚拟机，则模块将失败。 如果有多个虚拟机具有相同的名称，请使用 此参数区分大小写。 |
|
虚拟机描述。 |
|
网络列表（按网卡顺序）。 所有参数都区分大小写。 新网卡需要名称。在所有情况下，其他参数都是可选的。 |
|
静态 IPv4 网关。 |
|
静态 IPv6 网关。 |
|
静态 IPv4 地址（暗示 |
|
静态 IPv6 地址（暗示 |
|
自定义接口的 MAC 地址。 |
|
要将网络接口连接到的 XenServer 网络的名称。 |
|
如果未指定前缀，则 |
|
IPv4 分配类型。值 在某些操作系统上，它可能是 DHCP 配置的（例如 Windows）或未配置的接口（例如 Linux）。 选项
|
|
IPv6 分配类型。值 选项
|
|
用于连接到 XenServer 的密码。 如果任务中未指定此值，则将使用环境变量 |
|
默认情况下，如果 如果此参数设置为正值，则模块将等待指定秒数的状态更改。 如果超时，模块将生成错误消息。 默认值： |
|
应使用以创建虚拟机的模板、现有虚拟机（必须关闭）或快照的名称。 XenServer 上的模板/虚拟机/快照不一定具有唯一的名称。如果找到多个具有相同名称的模板，则模块将失败。 如果有多个模板/虚拟机/快照具有相同的名称，请使用 如果虚拟机已存在，则此设置将被忽略。 此参数区分大小写。 |
|
应使用以创建虚拟机的模板、现有虚拟机或快照的 UUID。 如果模板名称不唯一，则需要此参数。 |
|
用于连接到 XenServer 的用户名。 如果任务中未指定此值，则将使用环境变量 默认值： |
|
要管理的虚拟机的 UUID（如果已知）。这是 XenServer 的唯一标识符。 如果名称不唯一，则需要此参数。 请注意，在创建虚拟机时，提供的 UUID 将被忽略，因为 XenServer 在内部创建 UUID。 |
|
允许在 SSL 证书无效时连接。当证书不受信任时，设置为 如果任务中未指定此值，则将使用环境变量 选项
|
|
等待 XenServer 检测虚拟机的 IP 地址。如果 这需要在虚拟机上预安装 XenServer 工具才能正常工作。 选项
|
属性
属性 |
支持 |
描述 |
|---|---|---|
支持：完全支持 |
可以在 |
|
支持：无 |
在差异模式下，将返回关于已更改内容（或可能需要在 |
备注
注意
XenServer 的最低支持版本为 5.6。
模块已在 XenServer 6.5、7.1、7.2、7.6、Citrix Hypervisor 8.0、XCP-ng 7.6 和 8.0 上进行了测试。
要获取 XenAPI Python 库，只需在 Ansible 控制节点上运行
pip install XenAPI。该库也可以在 Citrix Hypervisor/XenServer SDK 中找到（可从 Citrix 网站下载）。将 SDK 中的 XenAPI.py 文件复制到 Ansible 控制节点上的 Python site-packages 目录中即可使用它。最新的库版本也可以从 GitHub 获取：https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py如果在
hostname中未指定方案，则模块默认为http://，因为在大多数设置中https://存在问题。确保您在受信任的环境中访问 XenServer 主机，或者显式使用https://方案。要对
hostname使用https://方案，您必须将主机证书导入到您的操作系统证书存储区，或者使用validate_certs=false，这需要 XenServer 7.2 SDK 或更高版本的 XenAPI 库以及 Python 2.7.9 或更高版本。通过使用
networks[].type、networks[].ip、networks[].gateway等参数在客户机操作系统内进行网络配置，在 XenServer 7.0 或更高版本上受支持（针对 Windows 客户机），通过使用官方 XenServer 客户机代理支持进行网络配置。模块将尝试检测此类支持是否可用并利用它，否则将使用通过 xenstore 进行配置的自定义方法。由于 XenServer 客户机代理仅支持无和静态类型的网络配置（其中无表示 DHCP 配置的接口），因此networks[].type和networks[].type6的值none和dhcp具有相同的效果。更多信息请参见：https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html在没有官方支持在客户机操作系统内进行网络配置的平台上，网络参数将写入 xenstore
vm-data/networks/<vif_device>键。可以使用xenstore ls和xenstore read工具在 \*nix 客户机上或在 Windows 客户机上通过 WMI 接口检查参数。它们也可以在模块返回的 VM 事实instance.xenstore_data键中找到。用户需要实现启动时脚本或自定义代理来读取 xenstore 中的参数并使用给定参数配置网络。请注意，要使 xenstore 数据在客户机内部可用，需要重新启动虚拟机，因此如果更改任何参数，模块将需要重新启动虚拟机。这是 XenAPI 和 xenstore 的一个限制。考虑到这些限制，通过 xenstore 进行网络配置最适用于引导新部署的虚拟机，而不太适用于重新配置现有虚拟机。更多信息请参见：https://support.citrix.com/article/CTX226713
示例
- name: Create a VM from a template
community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
folder: /testvms
name: testvm_2
state: poweredon
template: CentOS 7
disks:
- size_gb: 10
sr: my_sr
hardware:
num_cpus: 6
num_cpu_cores_per_socket: 3
memory_mb: 512
cdrom:
type: iso
iso_name: guest-tools.iso
networks:
- name: VM Network
mac: aa:bb:dd:aa:00:14
wait_for_ip_address: true
delegate_to: localhost
register: deploy
- name: Create a VM template
community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
folder: /testvms
name: testvm_6
is_template: true
disk:
- size_gb: 10
sr: my_sr
hardware:
memory_mb: 512
num_cpus: 1
delegate_to: localhost
register: deploy
- name: Rename a VM (requires the VM's UUID)
community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
uuid: 421e4592-c069-924d-ce20-7e7533fab926
name: new_name
state: present
delegate_to: localhost
- name: Remove a VM by UUID
community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
uuid: 421e4592-c069-924d-ce20-7e7533fab926
state: absent
delegate_to: localhost
- name: Modify custom params (boot order)
community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
name: testvm_8
state: present
custom_params:
- key: HVM_boot_params
value: { "order": "ndc" }
delegate_to: localhost
- name: Customize network parameters
community.general.xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
name: testvm_10
networks:
- name: VM Network
ip: 192.168.1.100/24
gateway: 192.168.1.1
- type: dhcp
delegate_to: localhost
返回值
常见的返回值已在此处记录，以下是此模块特有的字段
键 |
描述 |
|---|---|
检测到的或对虚拟机进行的更改 返回：始终 示例： |
|
关于虚拟机的元数据 返回：始终 示例： |