vmware.vmware_rest.vcenter_vm_guest_customization module Documentation

[mgamboa]

Summary

I was trying the module and when running with the example fail the reason was missing the 3 variables that are required, they come documented but in the example is no show how to use it

Issue Type

Documentation Report

Component Name

vmware.vmware_rest.vcenter_vm_guest_customization module

Ansible Version

$ ansible --version
2.15

Collection Versions

$ ansible-galaxy collection list

Configuration

$ ansible-config dump --only-changed

OS / Environment

AWX

Additional Information

No response

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[mikemorency]

hi @mgamboa

Are you talking about the parameters vcenter_hostname, vcenter_username, and vcenter_password? Those parameters are used for authentication to your vCenter cluster. You need to specify some values, but you can set them as environment variables (as described here) or as parameters when using the module.

Ill wait for you to confirm that is what your talking about, but in the meantime here is an example where they are defined as parameters while using the module.

- name: Customize the VM
  vmware.vmware_rest.vcenter_vm_guest_customization:
    vcenter_hostname: my-vcenter.domain.local
    vcenter_username: [email protected]
    vcenter_password: SuperSecretPass
    vm: "{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/test_vm1') }}"
    configuration_spec:
      linux_config:
        domain: mydomain
        hostname:
          fixed_name: foobar
          type: FIXED
    interfaces:
    - adapter:
        ipv4:
          type: STATIC
          gateways:
          - 192.168.123.1
          ip_address: 192.168.123.50
          prefix: 24
    global_DNS_settings:
      dns_suffix_list: []
      dns_servers:
      - 1.1.1.1

[mgamboa]

What i talking about the example is missing about the use for example of cloudinit I already defeat to try to figure out how to deploy the machine with customization on it because the documentation is not acure compare with other modules that explain the use of it , can we possible to expand the example a little further to understand better how the syntax works on the module i try to make something with cloud init but was terrible impossible even try just to put the hostname can't do i decide just create the vm the only thing that works for me on vsphere 8 the reason i change to rest api is because all my code works ok with vsphere 7 but with 8 doesn't accept tnow the legacy vmware.guest module at all

…

On Tue, Sep 10, 2024 at 3:02 AM mikemorency ***@***.***> wrote: hi @mgamboa <https://github.com/mgamboa> Are you talking about the parameters vcenter_hostname, vcenter_username, and vcenter_password? Those parameters are used for authentication to your vCenter cluster. You need to specify some values, but you can set them as environment variables (as described here <https://docs.ansible.com/ansible/latest/collections/vmware/vmware_rest/vcenter_vm_guest_customization_module.html#parameter-vcenter_hostname>) or as parameters when using the module. Ill wait for you to confirm that is what your talking about, but in the meantime here is an example where they are defined as parameters while using the module. - name: Customize the VM vmware.vmware_rest.vcenter_vm_guest_customization: vcenter_hostname: my-vcenter.domain.local vcenter_username: ***@***.*** vcenter_password: SuperSecretPass vm: "{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/test_vm1') }}" configuration_spec: linux_config: domain: mydomain hostname: fixed_name: foobar type: FIXED interfaces: - adapter: ipv4: type: STATIC gateways: - 192.168.123.1 ip_address: 192.168.123.50 prefix: 24 global_DNS_settings: dns_suffix_list: [] dns_servers: - 1.1.1.1 — Reply to this email directly, view it on GitHub <#527 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAC7SAYZAVNOBBVWZCPNT4TZVXIDTAVCNFSM6AAAAABN4EZCAKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMZYGYZDONRZGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[mikemorency]

Hello, Ive opened a PR to update the documentation examples for this module. Heres the current version, please let me know your thoughts here or in the PR

##########
#
# 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.
#
##########

# Heres 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

# Heres an example using the Linux script text. The script shebang can be anything (bash, perl, python), so long as the script will actually run
# Theres 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


# Heres an 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

- 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

[sean-freeman]

FYI @mgamboa

@mikemorency The cited PR takes my provided code in #471 for cloud-init, but does not fix #471 and therefore is documenting a procedure that cannot possibly work for any end-user. It should be removed from the Ansible Collection documentation until the procedure is confirmed working.

[mikemorency]

Hi @sean-freeman , I tested with cloud-init and found it to work without much setup. I just needed to install cloud init on the template, which the documentation mentions. I tested with the example provided in this issue. Ill try again with the documentation example and update as necessary.

FWIW i accidentally linked 471. I thought it was related but then saw you were talking about the library template module documentation specifically

[mikemorency]

Hi @sean-freeman , I checked both cloud init examples in the documentation for this module and they both worked as described. I used a RHEL9 template with cloud-init installed. I did not need any of the other specifications you mentioned in 471.
Please let me know your thoughts, otherwise I think the examples in this module are sufficient for its use cases