модуль vmware.vmware_rest.vcenter_vm_guest_customization — применяет спецификацию настройки к виртуальной машине

Примечание

Этот модуль входит в коллекцию vmware.vmware_rest (версия 4.10.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install vmware.vmware_rest. Для использования этого модуля требуются дополнительные компоненты; подробности см. в разделе Требования.

Чтобы использовать модуль в сценарии, укажите: vmware.vmware_rest.vcenter_vm_guest_customization.

Добавлено в vmware.vmware_rest 0.1.0

УСТАРЕЛ
Краткое описание
Требования
Параметры
Примечания
Примеры
Возвращаемые значения
Статус

УСТАРЕЛ

Удалён в:: версии 5.0.0
Причина:: Этот модуль перенесён в новую коллекцию vmware.vmware
Альтернатива:: Вместо него используйте vmware.vmware.vm_apply_customization.

Краткое описание

Применяет спецификацию настройки к виртуальной машине {@param.name vm}. Фактическая настройка выполняется в гостевой системе при включении виртуальной машины. Если для виртуальной машины ожидает выполнения настройка и задана новая, существующие параметры настройки будут заменены новыми.

Требования

На хосте, выполняющем этот модуль, должны быть установлены следующие компоненты.

vSphere 7.0.3 или новее
python >= 3.6
aiohttp

Параметры

Параметр	Комментарии
configuration_spec dictionary / обязательный	Параметры, применяемые к гостевой системе при настройке. Этот параметр обязателен. Допустимые атрибуты: - `windows_config` (dict): спецификация настройки гостевой операционной системы Windows Если параметр не задан, необходимо задать ConfigurationSpec.linux-config или ConfigurationSpec.cloud-config. В противном случае будет выдана соответствующая ошибка. ([‘set’]) - Допустимые ключи: - reboot (string): определяет, что нужно сделать с гостевой системой после настройки. Допустимые значения для этого поля: - `NO_REBOOT` - `REBOOT` - `SHUTDOWN` - sysprep (object): параметры настройки, например сведения о пользователе и администраторе, для гостевой операционной системы Windows. Необходимо указать ровно один из параметров WindowsConfiguration.sysprep и WindowsConfiguration.sysprep-xml. Если параметр не задан, настройки sysprep не будут применены к гостевой операционной системе Windows. - sysprep_xml (string): все параметры в формате XML. Это содержимое типичного файла answer.xml, который системные администраторы используют при настройке образа Windows. См. https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/update-windows-settings-and-scripts-create-your-own-answer-file-sxs. Необходимо указать ровно один из параметров WindowsConfiguration.sysprep и WindowsConfiguration.sysprep-xml. Если параметр не задан, настройки sysprep не будут применены к гостевой операционной системе Windows. - `linux_config` (dict): спецификация настройки гостевой операционной системы Linux Если параметр не задан, необходимо задать ConfigurationSpec.windows-config или ConfigurationSpec.cloud-config. В противном случае будет выдана соответствующая ошибка. ([‘set’]) - Допустимые ключи: - hostname (object): имя компьютера виртуальной машины (Windows). Имя компьютера может содержать буквы (A-Z), цифры (0-9) и дефисы (-), но не пробелы и точки (.). Имя не может состоять только из цифр. Длина имени компьютера не должна превышать 15 символов. Если имя компьютера длиннее 15 символов, оно будет усечено до 15 символов. Различные варианты см. в HostnameGenerator. - domain (string): полное доменное имя. - time_zone (string): чувствительный к регистру часовой пояс, например Europe/Sofia. Допустимые значения часовых поясов основаны на базе данных tz (часовых поясов), используемой в Linux. Значения представляют собой строки в формате «Area/Location», где Area — название континента или океана, а Location — название города, острова или другой региональной единицы. Список поддерживаемых часовых поясов для разных версий Linux см. по адресу https://kb.vmware.com/kb/2145518. Если параметр не задан, часовой пояс гостевой операционной системы не изменяется. - script_text (string): сценарий, выполняемый до и после настройки гостевой системы Linux. Максимальный размер сценария — 65536 байт. Поддерживается любой сценарий (shell, perl, python…), если в его заголовке указано правильное «#!». Вызывающий код не должен рассчитывать на наличие каких-либо переменных среды при запуске сценария. Механизм настройки запускает сценарий из командной строки: 1) с аргументом «precustomization» до настройки; 2) с аргументом «postcustomization» после настройки. Сценарий должен анализировать этот аргумент и выполнять соответствующий блок кода задач до или после настройки. Пример сценария оболочки Linux: #!/bin/sh if [ x$1 == x”precustomization” ]; then echo “Do Precustomization tasks” #code for pre-customization actions… elif [ x$1 == x”postcustomization” ]; then echo “Do Postcustomization tasks” #code for post-customization actions… fi Если параметр не задан, сценарий не будет выполнен. - `cloud_config` (dict): спецификация настройки гостевой системы с конфигурацией cloud. Если параметр не задан, необходимо задать ConfigurationSpec.windows-config или ConfigurationSpec.linux-config. В противном случае будет выдана соответствующая ошибка. ([‘set’]) - Допустимые ключи: - type (string): задаёт тип конфигурации cloud. Допустимое значение для этого поля: - `CLOUDINIT` - cloudinit (object): конфигурация cloud-init Это поле необязательное и имеет значение только в том случае, если CloudConfiguration.type имеет значение CLOUDINIT.
global_DNS_settings dictionary / обязательный	Глобальные настройки DNS — это настройки DNS, не относящиеся к определённому виртуальному сетевому адаптеру. Этот параметр обязателен. Допустимые атрибуты: - `dns_suffix_list` (list): список суффиксов поиска имён для виртуального сетевого адаптера. Этот список применяется при настройке гостевых систем Windows и Linux. В Linux эта настройка является глобальной, тогда как в Windows она указывается отдельно для каждого адаптера. Если параметр не задан, суффиксы DNS не устанавливаются. ([‘set’]) - `dns_servers` (list): список DNS-серверов для виртуального сетевого адаптера со статическим IP-адресом. Если список пуст, предполагается, что гостевая операционная система получает настройки DNS-серверов с помощью DHCP-сервера. Эти настройки указывают виртуальной машине использовать заданные DNS-серверы. DNS-серверы перечисляются в порядке предпочтения. Если параметр не задан, DNS-серверы не устанавливаются. ([‘set’])
interfaces list / элементы=dictionary / обязательный	Параметры IP, относящиеся к определённому виртуальному сетевому адаптеру. Структура AdapterMapping сопоставляет MAC-адрес сетевого адаптера с его IPSettings. Список может быть пустым, если сетевых адаптеров нет; в противном случае количество элементов должно соответствовать количеству сетевых адаптеров, настроенных для виртуальной машины. Этот параметр обязателен. Допустимые атрибуты: - `mac_address` (str): MAC-адрес настраиваемого сетевого адаптера. В серии vSphere 7.0 MAC-адреса необходимо указывать в порядке возрастания pciSlotNumber, иначе будет выдана ошибка несоответствия MAC-адреса. Подробности см. по адресу https://kb.vmware.com/s/article/87648. Если параметр не задан, в процессе настройки параметры из списка i_p_settings в CustomizationSpec.interfaces сопоставляются с сетевыми адаптерами виртуальной машины в порядке слотов PCI. Первому виртуальному сетевому адаптеру на шине PCI назначается interfaces[0].IPSettings, второму — interfaces[1].IPSettings и так далее. ([‘set’]) - `adapter` (dict): параметры IP для соответствующего виртуального сетевого адаптера. ([‘set’]) Этот ключ обязателен при [‘set’]. - Допустимые ключи: - ipv4 (object): спецификация настройки IPv4-адреса, маски подсети и шлюза для этого виртуального сетевого адаптера. Если параметр не задан, IPv4-адреса не устанавливаются. - ipv6 (object): спецификация настройки IPv6-адреса, маски подсети и шлюза для этого виртуального сетевого адаптера. Если параметр не задан, IPv6-адреса не устанавливаются. - windows (object): параметры Windows для этого виртуального сетевого адаптера. Применимо только к гостевым операционным системам Windows. Если параметр не задан, специфичные для Windows настройки не устанавливаются.
session_timeout float добавлено в vmware.vmware_rest 2.1.0	Настройки времени ожидания сеанса клиента. Максимальное количество секунд для всей операции, включая установление соединения, отправку запроса и получение ответа. Значение по умолчанию — 300 с.
state string	Варианты: `"set"` ← (по умолчанию)
vcenter_hostname string / обязательный	Имя хоста или IP-адрес vSphere vCenter Если значение не указано в задаче, вместо него будет использовано значение переменной среды `VMWARE_HOST`.
vcenter_password string / обязательный	Пароль vSphere vCenter Если значение не указано в задаче, вместо него будет использовано значение переменной среды `VMWARE_PASSWORD`.
vcenter_rest_log_file string	Этот необязательный параметр позволяет задать расположение файла журнала. Этот файл будет использоваться для записи взаимодействия по HTTP REST. Файл будет сохранён на хосте, где выполняется модуль. Если значение не указано в задаче, будет использовано значение переменной среды `VMWARE_REST_LOG_FILE`.
vcenter_username string / обязательный	Имя пользователя vSphere vCenter Если значение не указано в задаче, вместо него будет использовано значение переменной среды `VMWARE_USER`.
vcenter_validate_certs boolean	Разрешает подключение, если SSL-сертификаты недействительны. Если сертификатам нельзя доверять, задайте `false`. Если значение не указано в задаче, вместо него будет использовано значение переменной среды `VMWARE_VALIDATE_CERTS`. Варианты: `false` `true` ← (по умолчанию)
vm string / обязательный	Уникальный идентификатор виртуальной машины, которую необходимо настроить. Параметр должен содержать идентификатор ресурса, возвращённого модулем vmware.vmware_rest.vcenter_vm_info. Этот параметр обязателен.

Примечания

Примечание

Проверено на 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

# If your template already has vmtools installed and vCenter recognizes the installation (you should be able to see the tools version when the template
# is cloned), then you can skip this block in your workflow.
- name: Register VMware Tools with vCenter
  block:
    - name: Power on the VM
      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

- name: Power on the VM
  vmware.vmware_rest.vcenter_vm_power:
    state: start
    vm: "{{ my_new_vm.id }}"

#
# 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: {}

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
value dictionary	Настройка виртуальной машины Возвращается: при успешном выполнении Пример: `{}`

Статус

Этот модуль будет удалён в версии 5.0.0. [устарел]
Дополнительные сведения см. в разделе УСТАРЕЛ.

Авторы

Команда Ansible Cloud (@ansible-collections)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/vmware/vmware_rest/vcenter_vm_guest_customization_module.html