vmware.vmware_rest.vcenter_vm_guest_customization 模块 – 在虚拟机上应用自定义规范
注意
此模块是 vmware.vmware_rest 集合（版本 4.3.0）的一部分。
如果您使用的是 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install vmware.vmware_rest。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。
要在 playbook 中使用它，请指定：vmware.vmware_rest.vcenter_vm_guest_customization。
vmware.vmware_rest 0.1.0 中的新功能
概要
在 {@param.name vm} 中的虚拟机上应用自定义规范。实际的自定义发生在虚拟机启动时。如果虚拟机有挂起的自定义，并且设置了一个新的自定义，则现有的自定义设置将被新的设置覆盖。
要求
以下要求需要在执行此模块的主机上满足。
vSphere 7.0.3 或更高版本
python >= 3.6
aiohttp
参数
参数 |
注释 |
|---|---|
在自定义期间应用于访客的设置。此参数是强制性的。 有效的属性是
如果未设置，则必须设置 ConfigurationSpec.linux-config 或 ConfigurationSpec.cloud-config。否则，将抛出相应的错误。 ([‘set’])
此字段的接受值
如果未设置，则 sysprep 设置将不会应用于 Windows 客户操作系统。
如果未设置，则 sysprep 设置将不会应用于 Windows 客户操作系统。
如果未设置，则必须设置 ConfigurationSpec.windows-config 或 ConfigurationSpec.cloud-config。否则，将抛出相应的错误。 ([‘set’])
请参阅 https://kb.vmware.com/kb/2145518，以了解 Linux 中不同版本支持的时区列表。 如果未设置，则不会在客户操作系统中修改时区。
脚本的最大大小为 65536 字节。只要脚本（shell、perl、python...）在头部具有正确的“#！”，它就受支持。调用者不应假设脚本运行时有任何环境变量。 自定义引擎使用命令行调用脚本：1）在自定义之前使用参数“precustomization”，2）在自定义之后使用参数“postcustomization”。脚本应解析此参数，并在相应的块中实现预自定义或后自定义任务代码详细信息。 一个 Linux shell 脚本示例 #!/bin/sh if [ x$1 == x”precustomization” ]; then echo “执行预自定义任务” #预自定义操作的代码... elif [ x$1 == x”postcustomization” ]; then echo “执行后自定义任务” #后自定义操作的代码... fi 如果未设置，则不会执行脚本。
如果未设置，则必须设置 ConfigurationSpec.windows-config 或 ConfigurationSpec.linux-config。否则，将抛出相应的错误。 ([‘set’])
此字段的接受值
此字段是可选的，只有在 CloudConfiguration.type 的值为 CLOUDINIT 时才相关。 |
|
全局 DNS 设置构成并非特定于特定虚拟网络适配器的 DNS 设置。此参数是强制性的。 有效的属性是
如果未设置，则不设置 DNS 后缀。 ([‘set’])
如果未设置，则不设置 DNS 服务器。 ([‘set’]) |
|
特定于特定虚拟网络适配器的 IP 设置。AdapterMapping 结构将网络适配器的 MAC 地址映射到其 IPSettings。如果没有网络适配器，则可能为空；否则，应与为虚拟机配置的网络适配器数量匹配。此参数是强制性的。 有效的属性是
在 vSphere 7.0 系列中，MAC 地址必须按照 pciSlotNumber 的升序指定，否则将报告 MAC 地址不匹配错误。有关详细信息，请参阅 https://kb.vmware.com/s/article/87648 如果未设置，则自定义过程会将 CustomizationSpec.interfaces 中 *i_p_settings* 列表中的设置按照 PCI 插槽顺序映射到虚拟机的网络适配器。PCI 总线上的第一个虚拟网络适配器分配 interfaces[0].IPSettings，第二个适配器分配 interfaces[1].IPSettings，依此类推。 ([‘set’])
此键在 [‘set’] 中是必需的。
如果未设置，则不设置 IPv4 地址。
如果未设置，则不设置 IPv6 地址。
如果未设置，则不设置特定的 Windows 设置。 |
|
客户端会话的超时设置。 整个操作（包括连接建立、请求发送和响应）的最大秒数。 默认值为 300 秒。 |
|
选项
|
|
vSphere vCenter 的主机名或 IP 地址 如果未在任务中指定该值，则将使用环境变量 |
|
vSphere vCenter 密码 如果未在任务中指定该值，则将使用环境变量 |
|
您可以使用此可选参数来设置日志文件的位置。 此文件将用于记录 HTTP REST 交互。 该文件将存储在运行该模块的主机上。 如果未在任务中指定该值，则将使用 环境变量 |
|
vSphere vCenter 用户名 如果未在任务中指定该值，则将使用环境变量 |
|
允许在 SSL 证书无效时进行连接。当证书不受信任时，设置为 如果未在任务中指定该值，则将使用环境变量 选项
|
|
需要自定义的虚拟机的唯一标识符。 该参数必须是由 vmware.vmware_rest.vcenter_vm_info 返回的资源的 ID。此参数是强制性的。 |
注意
注意
在 vSphere 7.0.3 上测试
示例
##########
#
# VM customization can be difficult to troubleshoot, since each environment is different. Here are some general tips:
#
# 1. Make sure perl is installed on the Linux systems. Make sure cloud-init is installed if using cloud-init
# 2. Custom script execution is disabled by default. To enable it, you can run as root: vmware-toolbox-cmd config set deployPkg enable-custom-scripts true
# 3. VMware tools must be installed and recognized by vCenter before you can apply customization. See the example below for one approach to this.
# 4. On Linux (RHEL specifically), customization script logs can be found at /var/log/vmware-imc/toolsDeployPkg.log
# 5. Once the VM is started, the pending customization is applied. Even if that fails, the customization is then cleared. Meaning, you need to re-apply
# the customization spec in order to try again. Simply rebooting the VM will not change anything.
#
##########
# Here is the basic workflow for creating a new VM and then customizing it
- name: Deploy a new VM based on a template
vmware.vmware_rest.vcenter_vmtemplate_libraryitems:
name: vm-from-template
library: "{{ library_id }}"
template_library_item: "{{ template_id }}"
placement:
cluster: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
state: deploy
register: my_new_vm
- name: Power on the VM to register VMware tools
vmware.vmware_rest.vcenter_vm_power:
state: start
vm: "{{ my_new_vm.id }}"
- name: Wait until my VMware tools are recognized
vmware.vmware_rest.vcenter_vm_tools_info:
vm: "{{ my_new_vm.id }}"
register: vm_tools_info
until:
- vm_tools_info is not failed
- vm_tools_info.value.run_state == "RUNNING"
retries: 60
delay: 5
- name: Power Off VM
vmware.vmware_rest.vcenter_vm_power:
state: stop
vm: "{{ my_new_vm.id }}"
- name: Customize the VM
vmware.vmware_rest.vcenter_vm_guest_customization:
vm: "{{ my_new_vm.id }}"
global_DNS_settings:
dns_suffix_list:
- lan
- foo.internal
dns_servers:
- "8.8.8.8"
interfaces:
- adapter:
ipv4:
type: DHCP
configuration_spec:
linux_config:
domain: test
hostname:
fixed_name: myhost
type: FIXED
# Here is an example using the Linux script text. The script shebang can be anything (bash, perl, python), so long as the script will actually run
# There is also size and length limitation on the script text, as described in the module documentation.
# Finally, note the script is run twice. Once before all of the other customization and once after.
- name: Customize the VM
vmware.vmware_rest.vcenter_vm_guest_customization:
vm: "{{ my_new_vm.id }}"
global_DNS_settings:
dns_suffix_list:
- lan
- foo.internal
dns_servers:
- "8.8.8.8"
interfaces:
- adapter:
ipv4:
type: DHCP
configuration_spec:
linux_config:
domain: test
hostname:
fixed_name: myhost
type: FIXED
script_text: |
#!/bin/sh
if [ x$1 == x"precustomization" ]; then
echo "PRE" >> /tmp/vmware_rest_init_script.log
# add any other pre-customization tasks here
fi
if [ x$1 == x"postcustomization" ]; then
echo "POST" >> /tmp/vmware_rest_init_script.log
# add any other post-customization tasks here
fi
# Here is a simple example using cloud-init
# See also:
# https://developer.broadcom.com/xapis/vsphere-automation-api/latest/vcenter/data-structures/Guest_CloudinitConfiguration/
# https://knowledge.broadcom.com/external/article/311895/how-to-customize-virtual-machine-using-c.html
# https://cloudinit.readthedocs.io/en/latest/reference/examples.html
# https://cloudinit.readthedocs.io/en/23.4.1/reference/datasources/vmware.html#walkthrough-of-guestinfo-keys-transport
#
# cloud-init required: metadata as plain-text JSON/YAML, maximum 512KB file size
# cloud-init optional: userdata as plain-text in raw cloud-init format with no compression / no base64 encoding, maximum 512KB file size
- name: Customize the VM
vmware.vmware_rest.vcenter_vm_guest_customization:
vm: "{{ my_new_vm.id }}"
global_DNS_settings:
dns_suffix_list: []
dns_servers:
- "8.8.8.8"
interfaces:
- adapter:
ipv4:
type: DHCP
configuration_spec:
cloud_config:
type: CLOUDINIT
cloudinit:
metadata: |
instance-id: cloud-vm-example-1
local-hostname: cloud-vm
network:
config: disabled
userdata: |
#cloud-config
disable_root: 0
write_files:
- content: |
This is a test
path: /root/cloud-init-example
# Here is a more complex cloud-init example
- name: Set cloud-init variables for customization specification
ansible.builtin.set_fact:
metadata_yaml:
instance-id: "{{ vm_name }}"
hostname: "{{ vm_name }}"
local-hostname: "{{ vm_name }}"
network:
version: 2
ethernets:
nics:
match:
name: e*
dhcp4: true
dhcp6: false
public_ssh_keys:
- "{{ lookup('ansible.builtin.file', vmware_vm_ssh_public_key_file_path) }}"
userdata_yaml_text: |
#cloud-config
hostname: {{ vm_name }}
fqdn: {{ vm_name }}.{{ vm_domain }}
disable_root: false
ssh_pwauth: false
ssh_deletekeys: true
ssh:
emit_keys_to_console: false
no_ssh_fingerprints: false
ssh_authorized_keys:
- {{ lookup('ansible.builtin.file', vmware_vm_ssh_public_key_file_path) }}
users:
- name: root
ssh_authorized_keys:
- {{ lookup('ansible.builtin.file', vmware_vm_ssh_public_key_file_path) }}
lock_passwd: false
write_files:
- path: /etc/cloud/cloud-init.disabled
permissions: "0644"
content: ""
- name: Apply customization specification to the VM in Powered Off state
vmware.vmware_rest.vcenter_vm_guest_customization:
vm: "{{ my_new_vm.id }}"
configuration_spec:
cloud_config:
type: CLOUDINIT
cloudinit:
metadata: "{{ metadata_yaml | to_json(ensure_ascii=true) }}"
userdata: "{{ userdata_yaml_text | trim }}" # remove last newline character
interfaces: []
global_DNS_settings: {}
返回值
常见返回值记录在此处，以下是此模块特有的字段
键 |
描述 |
|---|---|
自定义虚拟机 返回: 成功时 示例: |