community.general.xenserver_guest_powerstate 模块 – 管理在 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_powerstate。

摘要

  • 此模块可用于启动、关闭、重启或挂起虚拟机，以及优雅地重启或关闭虚拟机的客户机操作系统。

要求

执行此模块的主机需要以下要求。

  • XenAPI

参数

参数

注释

hostname

别名：host，pool

字符串

XenServer 主机或 XenServer 池主机的 hostname 或 IP 地址。

如果任务中未指定此值，则将使用环境变量 XENSERVER_HOST 的值。

默认值： "localhost"

name

别名：name_label

字符串

要管理的虚拟机的名称。

在 XenServer 上运行的虚拟机不一定具有唯一的名称。如果找到多个同名虚拟机，则模块将失败。

如果有多个同名虚拟机，请使用 uuid 来唯一指定要管理的虚拟机。

此参数区分大小写。

password

别名：pass，pwd

字符串

用于连接到 XenServer 的密码。

如果任务中未指定此值，则将使用环境变量 XENSERVER_PASSWORD 的值。

state

字符串

指定虚拟机应处于的状态。

如果 state 设置为 present 以外的值，则虚拟机将转换到所需状态，并返回事实。

如果 state 设置为 present，则仅检查虚拟机的存在情况，并返回事实。

选项

  • "powered-on"

  • "powered-off"

  • "restarted"

  • "shutdown-guest"

  • "reboot-guest"

  • "suspended"

  • "present" ← (默认)

state_change_timeout

整数

默认情况下，如果 wait_for_ip_address=true，模块将无限期等待虚拟机更改状态或获取 IP 地址。

如果此参数设置为正值，则模块将改为等待指定秒数以进行状态更改。

超时情况下，模块将生成错误消息。

默认值： 0

用户名

别名: admin, user

字符串

连接 XenServer 时使用的用户名。

如果任务中未指定此值，则会改用环境变量 XENSERVER_USER 的值。

默认值: "root"

uuid

字符串

已知的要管理的虚拟机的 UUID。这是 XenServer 的唯一标识符。

如果名称不唯一，则需要此参数。

validate_certs

布尔值

允许在 SSL 证书无效时进行连接。当证书不受信任时，将其设置为 false。

如果任务中未指定此值，则会改用环境变量 XENSERVER_VALIDATE_CERTS 的值。

选项

  • false

  • true ← (默认)

wait_for_ip_address

布尔值

等待 XenServer 检测到虚拟机的 IP 地址。

这需要在虚拟机上预安装 XenServer Tools 才能正常工作。

选项

  • false ← (默认)

  • true

属性

属性

支持

描述

check_mode

支持: 完全支持

可以在 check_mode 下运行，并在不修改目标的情况下返回更改状态预测。

diff_mode

支持: 不支持

在差异模式下，将返回有关已更改内容（或可能需要在 check_mode 下更改的内容）的详细信息。

备注

注意

  • 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 网站下载）。将 XenAPI.py 文件从 SDK 复制到 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: no，这需要 XenServer 7.2 SDK 或更高版本以及 Python 2.7.9 或更高版本。

示例

- name: Power on VM
  community.general.xenserver_guest_powerstate:
    hostname: "{{ xenserver_hostname }}"
    username: "{{ xenserver_username }}"
    password: "{{ xenserver_password }}"
    name: testvm_11
    state: powered-on
  delegate_to: localhost
  register: facts

返回值

常用返回值已在 此处 记录，以下是此模块特有的字段

键

描述

instance

字典

关于虚拟机的元数据

返回: 始终

示例: {"cdrom": {"type": "none"}, "customization_agent": "native", "disks": [{"name": "windows-template-testing-0", "name_desc": "", "os_device": "xvda", "size": 42949672960, "sr": "Local storage", "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", "vbd_userdevice": "0"}, {"name": "windows-template-testing-1", "name_desc": "", "os_device": "xvdb", "size": 42949672960, "sr": "Local storage", "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", "vbd_userdevice": "1"}], "domid": "56", "folder": "", "hardware": {"memory_mb": 8192, "num_cpu_cores_per_socket": 2, "num_cpus": 4}, "home_server": "", "is_template": false, "name": "windows-template-testing", "name_desc": "", "networks": [{"gateway": "192.168.0.254", "gateway6": "fc00::fffe", "ip": "192.168.0.200", "ip6": ["fe80:0000:0000:0000:e9cb:625a:32c5:c291", "fc00:0000:0000:0000:0000:0000:0000:0001"], "mac": "ba:91:3a:48:20:76", "mtu": "1500", "name": "Pool-wide network associated with eth1", "netmask": "255.255.255.128", "prefix": "25", "prefix6": "64", "vif_device": "0"}], "other_config": {"base_template_name": "Windows Server 2016 (64-bit)", "import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5", "install-methods": "cdrom", "instant": "true", "mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e"}, "platform": {"acpi": "1", "apic": "true", "cores-per-socket": "2", "device_id": "0002", "hpet": "true", "nx": "true", "pae": "true", "timeoffset": "-25200", "vga": "std", "videoram": "8", "viridian": "true", "viridian_reference_tsc": "true", "viridian_time_ref_count": "true"}, "state": "poweredon", "uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda", "xenstore_data": {"vm-data": ""}}

作者

  • Bojan Vitnik (@bvitnik)