Debian Codegraph @

ansible_collections/vmware/vmware_rest/docs/lookup_plugin_migration.md

raw
1 # Lookup Plugin Migration
2
3 Starting with version 4.8.0, the lookup plugins `vmware.vmware_rest.*_moid` have been deprecated. They will not work with ansible-core 2.19 or above.
4
5 The recommended replacement is `vmware.vmware.moid_from_path`, which is available in vmware.vmware version 2.1 and above. This document will show how you can migrate to the new lookup plugins.
6
7 ### Authentication
8
9 To make migration easier, the same authentication methods that worked for the vmware.vmware_rest plugins will work for the vmware.vmware plugins.
10
11 ## Differences
12
13 Both plugins are capable of looking up an object's MoID, but they do so in fundamentally different ways. The vmware.vmware plugin extends the ansible-core library, while the vmware.vmware_rest plugins extend the cloud.common turbo plugin library. Here are the main differences:
14
15 ### Output
16
17 The vmware.vmware_rest plugins will automatically convert multiple MoIDs to a list. This is inconsistent with the Ansible base plugin behavior, which requires that you specify `wantlist=True` to get a list back.
18 ```
19 # This will return 'vm-1,vm-2,vm-3'
20 - name: Lookup many vms
21 ansible.builtin.debug:
22 msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/vms/') }}"
23
24 # This will return ['vm-1', 'vm-2', 'vm-3']
25 - name: Lookup many vms
26 ansible.builtin.debug:
27 msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/vms/', wantlist=true) }}"
28
29 # This will return 'vm-1'
30 - name: Lookup many vms
31 ansible.builtin.debug:
32 msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/vms/my-vm') }}"
33
34 # This will return ['vm-1']
35 - name: Lookup many vms
36 ansible.builtin.debug:
37 msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/vms/my-vm', wantlist=true) }}"
38 ```
39
40 ### Object types are inferred
41
42 There is only one lookup plugin for vmware.vmware. If you specify a path to a single object you do not need to specify the object type for vmware.vmware lookups. The plugin will return that MoID regardless of the object type. If the path ends in a slash, for example `/my-datacenter/vms/`, all objects found in that container will be returned. You can limit the type of object returned using an optional `type` parameter. For example:
43
44 ```yaml
45 # This will return ESXi hosts or resource pools stored directly under the cluster 'foo'
46 - name: Lookup all 'host' objects in cluster 'foo'
47 ansible.builtin.debug:
48 msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/foo/') }}"
49
50 # This will return just ESXi hosts stored directly under the cluster 'foo'
51 - name: Lookup all 'host' objects in cluster 'foo'
52 ansible.builtin.debug:
53 msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/foo/', type='host') }}"
54
55 # This will return the cluster 'foo'
56 - name: Lookup all 'host' objects in cluster 'foo'
57 ansible.builtin.debug:
58 msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/foo') }}"
59 ```
60
61 ### Search paths must be valid inventory paths
62
63 The vmware.vmware_rest plugins worked by stepping through the provided "path" and using each part to create an additional filter for the final object search. This means that the provided search path did not need to be an actual vSphere inventory path. It also means that the plugin makes multiple API calls for every search.
64
65 For vmware.vmware, you must use a valid inventory path. For example:
66 ```bash
67 # Datacenters are held at the root of the path. These are valid paths.
68 /my-dc
69 /my-dc/
70
71 # Everything else is held in one of four folders. These are valid paths.
72 /my-dc/host/
73 /my-dc/vm/
74 /my-dc/network/
75 /my-dc/datastore/
76
77 # These are not valid paths
78 /my-dc/my-cluster # should be /my-dc/host/my-cluster
79 /my-dc/prod/my-datastore # should be /my-dc/datastore/prod/my-datastore
80 ```
81
82 There are a few ways to define VM pathing. VMs are not stored in clusters (directly). They are stored in resource pools, ESXi hosts, or folders.
83 ```bash
84 /my-dc/vm/my-cluster # this is not a valid path.
85
86 /my-dc/vm/prod # this returns all VMs in folder prod
87 /my-dc/host/my-cluster/my-esxi/ # this returns all VMs on the ESXi host
88 /my-dc/host/my-cluster/Resources/ # this returns all VMs in the cluster's default resource pool
89 ```