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’])
有关 Linux 中不同版本的受支持时区的列表，请参阅 https://kb.vmware.com/kb/2145518。 如果未设置，则不会修改客户机操作系统中的时区。
脚本的最大大小为 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 系列中，必须按 pciSlotNumber 的升序指定 MAC 地址，否则将报告 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: {}
返回值
常见的返回值已在 此处 记录，以下是此模块特有的字段
键 |
描述 |
|---|---|
自定义虚拟机 返回：成功时 示例： |