From a0ff7101b0c54cde4245a02e3e975fd19eaf82c7 Mon Sep 17 00:00:00 2001 From: Mike Morency Date: Tue, 6 Aug 2024 10:02:37 -0400 Subject: [PATCH] updating lookup documentation and examples --- .../503_mm-feature_update_lookup_docs.yml | 10 ++ plugins/doc_fragments/moid.py | 24 +++- plugins/lookup/cluster_moid.py | 110 +++++++++++++-- plugins/lookup/datacenter_moid.py | 115 ++++++++++++--- plugins/lookup/datastore_moid.py | 124 +++++++++++++--- plugins/lookup/folder_moid.py | 119 +++++++++++++--- plugins/lookup/host_moid.py | 128 ++++++++++++++--- plugins/lookup/network_moid.py | 132 +++++++++++++++--- plugins/lookup/resource_pool_moid.py | 117 +++++++++++++--- plugins/lookup/vm_moid.py | 102 +++++++++++--- 10 files changed, 837 insertions(+), 144 deletions(-) create mode 100644 changelogs/fragments/503_mm-feature_update_lookup_docs.yml diff --git a/changelogs/fragments/503_mm-feature_update_lookup_docs.yml b/changelogs/fragments/503_mm-feature_update_lookup_docs.yml new file mode 100644 index 00000000..8ca79834 --- /dev/null +++ b/changelogs/fragments/503_mm-feature_update_lookup_docs.yml @@ -0,0 +1,10 @@ +--- +minor_changes: + - cluster_moid - updated documentation around lookup plugin usage + - datacenter_moid - updated documentation around lookup plugin usage + - datastore_moid - updated documentation around lookup plugin usage + - folder_moid - updated documentation around lookup plugin usage + - host_moid - updated documentation around lookup plugin usage + - network_moid - updated documentation around lookup plugin usage + - resource_pool_moid - updated documentation around lookup plugin usage + - vm_moid - updated documentation around lookup plugin usage diff --git a/plugins/doc_fragments/moid.py b/plugins/doc_fragments/moid.py index fe061b3b..1b925016 100644 --- a/plugins/doc_fragments/moid.py +++ b/plugins/doc_fragments/moid.py @@ -9,9 +9,24 @@ class ModuleDocFragment(object): # Parameters for the Lookup Managed Object Reference (MoID) plugins DOCUMENTATION = r""" + notes: + - >- + Lookup plugins are run on the ansible controller and are used to lookup information from an external + resource. See https://docs.ansible.com/ansible/latest/plugins/lookup.html#lookup-plugins + - >- + This collection's plugins allow you to quickly gather VMWare resource identifiers and either store or + use them, instead of requiring multiple modules and tasks to do the same thing. + See the examples section for a comparison. + options: _terms: - description: Path to query. + description: + - The absolute folder path to the object you would like to lookup. + - Folder paths always start with the datacenter name, and then the object type (host, vm, network, datastore). + - >- + If the object is in a sub folder, the sub folder path should be added after the object type + (for example /my_dc/vm/some/sub_folder/vm_name_to_lookup). + - Enter the object or folder names as seen in the VCenter GUI. Do not escape spaces or special characters. required: True type: string vcenter_hostname: @@ -51,4 +66,11 @@ class ModuleDocFragment(object): env: - name: VMWARE_VALIDATE_CERTS type: boolean + object_type: + description: + - Should not be set by the user, it is set internally when using a specific lookup plugin. + - Describes the type of object to lookup. Example, cluster, datacenter, datastore, etc. + default: 'cluster' + type: str + required: False """ diff --git a/plugins/lookup/cluster_moid.py b/plugins/lookup/cluster_moid.py index 474af1d4..5bfb617c 100644 --- a/plugins/lookup/cluster_moid.py +++ b/plugins/lookup/cluster_moid.py @@ -11,33 +11,113 @@ name: cluster_moid short_description: Look up MoID for vSphere cluster objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere cluster object contained in the specified path. + - Returns Managed Object Reference (MoID) of the vSphere cluster object contained in the specified path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc' and a cluster named 'my_cluster'. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: vcenter_hostname: "vcenter.test" vcenter_username: "administrator@vsphere.local" vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/') }}" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}" + +# +# Cluster Search Path Examples +# +# Clusters are located under the 'host' folder in a datacenter. +# The basic path for a cluster should look like '//host/' +- name: Lookup Cluster Named 'my_cluster' in Datacenter 'my_dc' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}" + +# +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Retrieve details about a cluster named 'my_cluster' + vmware.vmware_rest.vcenter_cluster_info: + names: + - my_cluster + register: my_cluster_info + +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + cluster: "{{ my_cluster_info.value[0].cluster }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + cluster: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 """ diff --git a/plugins/lookup/datacenter_moid.py b/plugins/lookup/datacenter_moid.py index f80e1a68..42b5ea38 100644 --- a/plugins/lookup/datacenter_moid.py +++ b/plugins/lookup/datacenter_moid.py @@ -11,33 +11,112 @@ name: datacenter_moid short_description: Look up MoID for vSphere datacenter objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere datacenter object contained in the specified path. + - Returns Managed Object Reference (MoID) of the vSphere datacenter object contained in the specified path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc'. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: - vcenter_hostname: "vcenter.test" - vcenter_username: "administrator@vsphere.local" - vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_folder/') }}" + vcenter_hostname: "vcenter.test" + vcenter_username: "administrator@vsphere.local" + vcenter_password: "1234" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}" + +# +# Datacenter Search Path Examples +# +# Datacenters are located at the root of VMWare paths. +# The basic path for a datacenter should look like '/' +- name: Lookup Datacenter 'my_dc' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}" + +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Retrieve details about a datacenter named 'my_dc' + vmware.vmware_rest.vcenter_datacenter_info: + names: + - my_dc + register: my_dc_info + +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + datacenter: "{{ my_dc_info.value[0].datacebter }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + datacenter: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 """ diff --git a/plugins/lookup/datastore_moid.py b/plugins/lookup/datastore_moid.py index 02a0e094..88602b2a 100644 --- a/plugins/lookup/datastore_moid.py +++ b/plugins/lookup/datastore_moid.py @@ -11,33 +11,121 @@ name: datastore_moid short_description: Look up MoID for vSphere datastore objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere datastore object object contained in the specified path. + - Returns Managed Object Reference (MoID) of the vSphere datastore object object contained in the specified path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc' and a datastore named 'my_datastore'. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/my_datastore', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: - vcenter_hostname: "vcenter.test" - vcenter_username: "administrator@vsphere.local" - vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/host/my_cluster/esxi1.test/ro_datastore', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/') }}" + vcenter_hostname: "vcenter.test" + vcenter_username: "administrator@vsphere.local" + vcenter_password: "1234" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/my_datastore', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/my_datastore') }}" + +# +# Datastore Search Path Examples +# +# Datastores are located under the 'datastore' folder in a datacenter. +# The basic path for a datastore should look like '//datastore/' +# You can also lookup datastores under a specific host, if needed. +# The basic path should look like '//host///' +# Note: All datastores are still accessible at this path, not just the ones attached to the host. +- name: Lookup Datastore Named 'my_datastore' in Datacenter 'my_dc' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/my_datastore') }}" + +# If the datastore is in a user created 'datastore' type folder, the path shoud just include the +# datacenter and folder name. +- name: Lookup Datastore Named 'my_datastore' in Datacenter 'my_dc' in a datastore folder 'production' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/production/my_datastore') }}" +# +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Retrieve details about a datastore named 'my_datastore' + vmware.vmware_rest.vcenter_cluster_info: + names: + - my_datastore + register: my_datastore_info + +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + datastore: "{{ my_datastore_info.value[0].datastore }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + datastore: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/my_datastore') }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 """ diff --git a/plugins/lookup/folder_moid.py b/plugins/lookup/folder_moid.py index 7d9d2476..34e63045 100644 --- a/plugins/lookup/folder_moid.py +++ b/plugins/lookup/folder_moid.py @@ -11,33 +11,116 @@ name: folder_moid short_description: Look up MoID for vSphere folder objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere folder object contained in the specified path. + - Returns Managed Object Reference (MoID) of the vSphere folder object contained in the specified path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc' and a host folder structure like path/to/my_folder. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/path/to/my_folder', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: - vcenter_hostname: "vcenter.test" - vcenter_username: "administrator@vsphere.local" - vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm/foo/bar', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm/foo/') }}" + vcenter_hostname: "vcenter.test" + vcenter_username: "administrator@vsphere.local" + vcenter_password: "1234" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/path/to/my_folder', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/path/to/my_folder') }}" + +# +# Folder Search Path Examples +# +# Due to a known issue, duplicate named folders in a datacenter are not searchable with this lookup. +# For example, you cannot reliably get a host folder named 'test_folder' when a vm folder named 'test_folder' +# exists. +# +# https://github.com/ansible-collections/vmware.vmware_rest/issues/500 +- name: Lookup Folder Named 'my_folder' in Datacenter 'my_dc' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/my_folder') }}" + +# +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Retrieve details about a folder named 'my_folder' + vmware.vmware_rest.vcenter_cluster_info: + names: + - my_folder + register: my_foler_info + +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + folder: "{{ my_foler_info.value[0].folder }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + folder: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/path/to/my_folder') }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 """ diff --git a/plugins/lookup/host_moid.py b/plugins/lookup/host_moid.py index b9fe8903..513ceec2 100644 --- a/plugins/lookup/host_moid.py +++ b/plugins/lookup/host_moid.py @@ -11,33 +11,125 @@ name: host_moid short_description: Look up MoID for vSphere host objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere host object contained in the specified path. + - Returns Managed Object Reference (MoID) of the vSphere host object contained in the specified path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc', a cluster named 'my_cluster', and an ESXI host named 'my_host'. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: - vcenter_hostname: "vcenter.test" - vcenter_username: "administrator@vsphere.local" - vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/esxi1.test', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/') }}" + vcenter_hostname: "vcenter.test" + vcenter_username: "administrator@vsphere.local" + vcenter_password: "1234" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host') }}" + +# +# Host Search Path Examples +# +# Hosts are located under the 'host' folder in a datacenter. They may also be under a cluster, which is +# under the host folder. +# The basic path for a host in a cluster should look like '//host//' +# The basic path for a host outside of a cluster should look like '//host/' +- name: Lookup Host named 'my_host' in a Cluster Named 'my_cluster' in Datacenter 'my_dc' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host') }}" + +- name: Lookup Host named 'my_host' not in a Cluster but in Datacenter 'my_dc' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_host') }}" + +# If the host is in a user created 'host' type folder, the path shoud just include the +# datacenter and folder name. +- name: Lookup Host Named 'my_host' in Datacenter 'my_dc' in a Host folder 'production' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/production/my_host') }}" + +# +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Retrieve details about an ESXI host named 'my_host' + vmware.vmware_rest.vcenter_host_info: + names: + - my_host + register: my_host_info + +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + host: "{{ my_host_info.value[0].host }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + cluster: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host') }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 """ diff --git a/plugins/lookup/network_moid.py b/plugins/lookup/network_moid.py index 7047a13b..dd076877 100644 --- a/plugins/lookup/network_moid.py +++ b/plugins/lookup/network_moid.py @@ -11,35 +11,127 @@ name: network_moid short_description: Look up MoID for vSphere network objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere network object contained in the specified path. - - This lookup cannot distinguish between multiple networks with the same name defined in multiple switches - as that is not supported by the vSphere REST API; network names must be unique within a given datacenter/folder path. + - Returns Managed Object Reference (MoID) of the vSphere network object contained in the specified path. + - >- + This lookup cannot distinguish between multiple networks with the same name defined in multiple switches + as that is not supported by the vSphere REST API; network names must be unique within a given datacenter/folder path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc' and a network named 'my_network'. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/my_network', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: - vcenter_hostname: "vcenter.test" - vcenter_username: "administrator@vsphere.local" - vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/test_network', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/') }}" + vcenter_hostname: "vcenter.test" + vcenter_username: "administrator@vsphere.local" + vcenter_password: "1234" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/my_network', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/my_network') }}" + +# +# Network Search Path Examples +# +# Networks are located under the 'network' folder in a datacenter. +# The basic path for a datastore should look like '//network/' +- name: Lookup Network Named 'my_network' in Datacenter 'my_dc' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/my_network') }}" + +# If the network is in a user created 'network' type folder, the path shoud just include the +# datacenter and folder name. +- name: Lookup Network Named 'my_network' in Datacenter 'my_dc' in a Network folder 'production' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/production/my_network') }}" + + +# +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Retrieve details about the network named 'my_network' + vmware.vmware_rest.vcenter_network_info: + names: + - my_network + register: my_network_info + +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + nics: + - backing: + type: STANDARD_PORTGROUP + network: "{{ my_network_info.value[0].network }}" + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + nics: + - backing: + type: STANDARD_PORTGROUP + network: "{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/my_network') }}" """ diff --git a/plugins/lookup/resource_pool_moid.py b/plugins/lookup/resource_pool_moid.py index bd4f1adf..e0e5e11d 100644 --- a/plugins/lookup/resource_pool_moid.py +++ b/plugins/lookup/resource_pool_moid.py @@ -11,33 +11,114 @@ name: resource_pool_moid short_description: Look up MoID for vSphere resource pool objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere resource pool object contained in the specified path. + - Returns Managed Object Reference (MoID) of the vSphere resource pool object contained in the specified path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc', a cluster named 'my_cluster', and a resource pool named 'my_pool'. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources/my_pool', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: - vcenter_hostname: "vcenter.test" - vcenter_username: "administrator@vsphere.local" - vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources/my_resource_pool', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources/') }}" + vcenter_hostname: "vcenter.test" + vcenter_username: "administrator@vsphere.local" + vcenter_password: "1234" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources/my_pool', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources/my_pool') }}" + +# +# Resource Pool Search Path Examples +# +# Pools are located under the 'host' folder in a datacenter. They are nested under the cluster name, and +# then a special 'Resources' folder. +# The basic path for a pool should look like '//host//Resources/' +- name: Lookup Pool Named 'my_pool' in Datacenter 'my_dc' and Cluster 'my_cluster' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources/my_pool') }}" + +# +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Retrieve details about a resource pool named 'my_pool' + vmware.vmware_rest.vcenter_resource_pool_info: + names: + - my_pool + register: my_pool_info + +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + resource_pool: "{{ my_pool_info.value[0].resource_pool }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Create a VM + vmware.vmware_rest.vcenter_vm: + placement: + resource_pool: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources/my_pool') }}" + name: test_vm1 + guest_OS: RHEL_7_64 + hardware_version: VMX_11 + memory: + size_MiB: 1024 + disks: + - type: SATA + new_vmdk: + name: first_disk + capacity: 3200 """ diff --git a/plugins/lookup/vm_moid.py b/plugins/lookup/vm_moid.py index 4c49b8d0..c93894e5 100644 --- a/plugins/lookup/vm_moid.py +++ b/plugins/lookup/vm_moid.py @@ -11,33 +11,99 @@ name: vm_moid short_description: Look up MoID for vSphere vm objects using vCenter REST API description: - - Returns Managed Object Reference (MoID) of the vSphere vm object contained in the specified path. + - Returns Managed Object Reference (MoID) of the vSphere vm object contained in the specified path. author: - - Alina Buzachis (@alinabuzachis) + - Alina Buzachis (@alinabuzachis) version_added: 2.1.0 requirements: - - vSphere 7.0.3 or greater - - python >= 3.6 - - aiohttp + - vSphere 7.0.3 or greater + - python >= 3.6 + - aiohttp extends_documentation_fragment: -- vmware.vmware_rest.moid + - vmware.vmware_rest.moid """ EXAMPLES = r""" -# lookup sample -- name: set connection info - ansible.builtin.set_fact: +# +# +# The examples below assume you have a datacenter named 'my_dc' and a vm named 'my_vm'. +# Replace these values as needed for your environment. +# +# + +# +# Authentication / Connection Arguments +# +# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases +- name: Pass In Connection Arguments Explicitly + ansible.builtin.debug: + msg: >- + {{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/my_cluster/my_vm', + vcenter_hostname="vcenter.test", + vcenter_username="administrator@vsphere.local", + vcenter_password="1234") }} + +# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the +# lookup plugins. This makes the individual lookup plugin calls simpler +- name: Example Playbook + hosts: all + vars: connection_args: - vcenter_hostname: "vcenter.test" - vcenter_username: "administrator@vsphere.local" - vcenter_password: "1234" - -- name: lookup MoID of the object - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/host/my_cluster/esxi1.test/test_vm1', **connection_args) }}" - -- name: lookup MoID of the object inside the path - ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/') }}" + vcenter_hostname: "vcenter.test" + vcenter_username: "administrator@vsphere.local" + vcenter_password: "1234" + tasks: + # Add more tasks or lookups as needed, referencing the same connection_args variable + - name: Lookup MoID of the object + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/my_cluster/my_vm', **connection_args) }}" + +# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing +# extra args to the lookup plugins +- name: Use a lookup plugin with VMWARE_* environment variables set + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/my_cluster/my_vm') }}" + +# +# VM Search Path Examples +# +# VMs are located under the 'vm' folder in a datacenter. If they are not in a folder, the path +# should include the cluster name. +# The basic path for a VM should look like '//vm//' +- name: Lookup VM Named 'my_vm' in Datacenter 'my_dc' in Cluster 'my_cluster' + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm/my_cluster/my_vm') }}" + +# If the VM is in a user created VM folder, you just include the folder name. +- name: Lookup VM Named 'my_vm' in Datacenter 'my_dc' in Folder 'production' (also in Cluster 'my_cluster') + ansible.builtin.debug: + msg: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/production/my_vm') }}" + +# +# Usage in Playbooks +# +# +# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it. +# +# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution +# and adds extra steps to the playbook: +- name: Look up the VM called 'my_vm' in the inventory + vmware.vmware_rest.vcenter_vm_info: + filter_names: + - my_vm + register: my_vm_info + +- name: Delete a VM + vmware.vmware_rest.vcenter_vm: + vm: '{{ my_vm_info.value[0].vm }}' + state: absent + +# With the lookup, playbooks are shorter, quicker, and more intuitive: +- name: Delete a VM + vmware.vmware_rest.vcenter_vm: + vm: "{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/my_vm') }}" + state: absent """