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。您需要进一步的要求才能使用此模块，请参阅 要求 获取详细信息。
要在 playbook 中使用它，请指定：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 池主机的的主机名或 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 工具才能正常工作。 选择
|
属性
属性 |
支持 |
描述 |
|---|---|---|
支持: 完全 |
可以在 |
|
支持: 无 |
当处于 diff 模式时，将返回有关已更改内容（或可能需要在 |
备注
注意
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中未指定 scheme，模块默认使用http://，因为https://在大多数设置中存在问题。请确保在受信任的环境中访问 XenServer 主机，或显式使用https://scheme。要为
hostname使用https://scheme，您必须将主机证书导入到您的操作系统证书存储中，或者使用validate_certs=false，这需要 XenServer 7.2 SDK 或更高版本的 XenAPI 库以及 Python 2.7.9 或更高版本。在客户操作系统内部进行网络配置，通过使用
networks[].type,networks[].ip,networks[].gateway等参数，在 XenServer 7.0 或更高版本上，对于 Windows 客户机，通过使用官方的 XenServer Guest agent 支持网络配置来实现。该模块将尝试检测是否提供此类支持并加以利用，否则它将使用通过 xenstore 进行配置的自定义方法。由于 XenServer Guest agent 仅支持 None 和 Static 类型的网络配置，其中 None 表示 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>键。可以使用 \*nix 客户机上的xenstore ls和xenstore read工具或通过 Windows 客户机上的 WMI 接口来检查这些参数。它们也可以在模块返回的 VM factsinstance.xenstore_data键中找到。用户需要自行实现启动时脚本或自定义代理，以便从 xenstore 读取参数并使用给定的参数配置网络。请注意，为了使 xenstore 数据在客户机内部可用，需要重新启动 VM，因此如果任何参数发生更改，模块将需要重新启动 VM。这是 XenAPI 和 xenstore 的限制。考虑到这些限制，通过 xenstore 进行网络配置对于引导新部署的 VM 最有用，而对于重新配置现有 VM 的作用要小得多。更多信息请参考：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
返回值
常见的返回值记录在这里，以下是此模块独有的字段
键 |
描述 |
|---|---|
检测到或对 VM 所做的更改 返回: 总是 示例: |
|
关于 VM 的元数据 返回: 总是 示例: |