We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
vmware_object_role_permission: Missing required parameters in examples
##### SUMMARY
Examples missing required fields of hostname, username, and password, while other module examples include these.

##### ISSUE TYPE
- Documentation Report

##### COMPONENT NAME
vmware_object_role_permission

##### ADDITIONAL INFORMATION
PR #422 

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `plugins/modules/vmware_object_role_permission.py`
Content:
```
1 #!/usr/bin/python
2 # -*- coding: utf-8 -*-
3 #
4 # Copyright: (c) 2018, Derek Rushing <derek.rushing@geekops.com>
5 # Copyright: (c) 2018, VMware, Inc.
6 # SPDX-License-Identifier: GPL-3.0-or-later
7 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
8 
9 from __future__ import absolute_import, division, print_function
10 
11 __metaclass__ = type
12 
13 
14 DOCUMENTATION = '''
15 ---
16 module: vmware_object_role_permission
17 short_description: Manage local roles on an ESXi host
18 description: This module can be used to manage object permissions on the given host.
19 author:
20 - Derek Rushing (@kryptsi)
21 - Joseph Andreatta (@vmwjoseph)
22 notes:
23     - Tested on ESXi 6.5, vSphere 6.7
24     - The ESXi login user must have the appropriate rights to administer permissions.
25     - Permissions for a distributed switch must be defined and managed on either the datacenter or a folder containing the switch.
26 requirements:
27     - "python >= 2.7"
28     - PyVmomi
29 options:
30   role:
31     description:
32     - The role to be assigned permission.
33     required: True
34     type: str
35   principal:
36     description:
37     - The user to be assigned permission.
38     - Required if C(group) is not specified.
39     type: str
40   group:
41     description:
42     - The group to be assigned permission.
43     - Required if C(principal) is not specified.
44     type: str
45   object_name:
46     description:
47     - The object name to assigned permission.
48     type: str
49     required: True
50   object_type:
51     description:
52     - The object type being targeted.
53     default: 'Folder'
54     choices: ['Folder', 'VirtualMachine', 'Datacenter', 'ResourcePool',
55               'Datastore', 'Network', 'HostSystem', 'ComputeResource',
56               'ClusterComputeResource', 'DistributedVirtualSwitch']
57     type: str
58   recursive:
59     description:
60     - Should the permissions be recursively applied.
61     default: True
62     type: bool
63   state:
64     description:
65     - Indicate desired state of the object's permission.
66     - When C(state=present), the permission will be added if it doesn't already exist.
67     - When C(state=absent), the permission is removed if it exists.
68     choices: ['present', 'absent']
69     default: present
70     type: str
71 extends_documentation_fragment:
72 - community.vmware.vmware.documentation
73 
74 '''
75 
76 EXAMPLES = '''
77 - name: Assign user to VM folder
78   community.vmware.vmware_object_role_permission:
79     role: Admin
80     principal: user_bob
81     object_name: services
82     state: present
83   delegate_to: localhost
84 
85 - name: Remove user from VM folder
86   community.vmware.vmware_object_role_permission:
87     role: Admin
88     principal: user_bob
89     object_name: services
90     state: absent
91   delegate_to: localhost
92 
93 - name: Assign finance group to VM folder
94   community.vmware.vmware_object_role_permission:
95     role: Limited Users
96     group: finance
97     object_name: Accounts
98     state: present
99   delegate_to: localhost
100 
101 - name: Assign view_user Read Only permission at root folder
102   community.vmware.vmware_object_role_permission:
103     role: ReadOnly
104     principal: view_user
105     object_name: rootFolder
106     state: present
107   delegate_to: localhost
108 '''
109 
110 RETURN = r'''
111 changed:
112     description: whether or not a change was made to the object's role
113     returned: always
114     type: bool
115 '''
116 
117 try:
118     from pyVmomi import vim, vmodl
119 except ImportError:
120     pass
121 
122 from ansible.module_utils.basic import AnsibleModule
123 from ansible.module_utils._text import to_native
124 from ansible_collections.community.vmware.plugins.module_utils.vmware import PyVmomi, vmware_argument_spec, find_obj
125 
126 
127 class VMwareObjectRolePermission(PyVmomi):
128     def __init__(self, module):
129         super(VMwareObjectRolePermission, self).__init__(module)
130         self.module = module
131         self.params = module.params
132         self.is_group = False
133 
134         if self.params.get('principal', None) is not None:
135             self.applied_to = self.params['principal']
136         elif self.params.get('group', None) is not None:
137             self.applied_to = self.params['group']
138             self.is_group = True
139 
140         self.get_role()
141         self.get_object()
142         self.get_perms()
143         self.perm = self.setup_permission()
144         self.state = self.params['state']
145 
146     def get_perms(self):
147         self.current_perms = self.content.authorizationManager.RetrieveEntityPermissions(self.current_obj, False)
148 
149     def same_permission(self, perm_one, perm_two):
150         return perm_one.principal.lower() == perm_two.principal.lower() \
151             and perm_one.roleId == perm_two.roleId
152 
153     def get_state(self):
154         for perm in self.current_perms:
155             if self.same_permission(self.perm, perm):
156                 return 'present'
157         return 'absent'
158 
159     def process_state(self):
160         local_permission_states = {
161             'absent': {
162                 'present': self.remove_permission,
163                 'absent': self.state_exit_unchanged,
164             },
165             'present': {
166                 'present': self.state_exit_unchanged,
167                 'absent': self.add_permission,
168             }
169         }
170         try:
171             local_permission_states[self.state][self.get_state()]()
172         except vmodl.RuntimeFault as runtime_fault:
173             self.module.fail_json(msg=to_native(runtime_fault.msg))
174         except vmodl.MethodFault as method_fault:
175             self.module.fail_json(msg=to_native(method_fault.msg))
176         except Exception as e:
177             self.module.fail_json(msg=to_native(e))
178 
179     def state_exit_unchanged(self):
180         self.module.exit_json(changed=False)
181 
182     def setup_permission(self):
183         perm = vim.AuthorizationManager.Permission()
184         perm.entity = self.current_obj
185         perm.group = self.is_group
186         perm.principal = self.applied_to
187         perm.roleId = self.role.roleId
188         perm.propagate = self.params['recursive']
189         return perm
190 
191     def add_permission(self):
192         if not self.module.check_mode:
193             self.content.authorizationManager.SetEntityPermissions(self.current_obj, [self.perm])
194         self.module.exit_json(changed=True)
195 
196     def remove_permission(self):
197         if not self.module.check_mode:
198             self.content.authorizationManager.RemoveEntityPermission(self.current_obj, self.applied_to, self.is_group)
199         self.module.exit_json(changed=True)
200 
201     def get_role(self):
202         for role in self.content.authorizationManager.roleList:
203             if role.name == self.params['role']:
204                 self.role = role
205                 return
206         self.module.fail_json(msg="Specified role (%s) was not found" % self.params['role'])
207 
208     def get_object(self):
209         # find_obj doesn't include rootFolder
210         if self.params['object_type'] == 'Folder' and self.params['object_name'] == 'rootFolder':
211             self.current_obj = self.content.rootFolder
212             return
213         try:
214             getattr(vim, self.params['object_type'])
215         except AttributeError:
216             self.module.fail_json(msg="Object type %s is not valid." % self.params['object_type'])
217         self.current_obj = find_obj(content=self.content,
218                                     vimtype=[getattr(vim, self.params['object_type'])],
219                                     name=self.params['object_name'])
220 
221         if self.current_obj is None:
222             self.module.fail_json(
223                 msg="Specified object %s of type %s was not found."
224                 % (self.params['object_name'], self.params['object_type'])
225             )
226         if self.params['object_type'] == 'DistributedVirtualSwitch':
227             msg = "You are applying permissions to a Distributed vSwitch. " \
228                   "This will probably fail, since Distributed vSwitches inherits permissions " \
229                   "from the datacenter or a folder level. " \
230                   "Define permissions on the datacenter or the folder containing the switch."
231             self.module.warn(msg)
232 
233 
234 def main():
235     argument_spec = vmware_argument_spec()
236     argument_spec.update(
237         dict(
238             role=dict(required=True, type='str'),
239             object_name=dict(required=True, type='str'),
240             object_type=dict(
241                 type='str',
242                 default='Folder',
243                 choices=[
244                     'Folder',
245                     'VirtualMachine',
246                     'Datacenter',
247                     'ResourcePool',
248                     'Datastore',
249                     'Network',
250                     'HostSystem',
251                     'ComputeResource',
252                     'ClusterComputeResource',
253                     'DistributedVirtualSwitch',
254                 ],
255             ),
256             principal=dict(type='str'),
257             group=dict(type='str'),
258             recursive=dict(type='bool', default=True),
259             state=dict(default='present', choices=['present', 'absent'], type='str'),
260         )
261     )
262 
263     module = AnsibleModule(
264         argument_spec=argument_spec,
265         supports_check_mode=True,
266         mutually_exclusive=[['principal', 'group']],
267         required_one_of=[['principal', 'group']],
268     )
269 
270     vmware_object_permission = VMwareObjectRolePermission(module)
271     vmware_object_permission.process_state()
272 
273 
274 if __name__ == '__main__':
275     main()
276
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/plugins/modules/vmware_object_role_permission.py b/plugins/modules/vmware_object_role_permission.py
--- a/plugins/modules/vmware_object_role_permission.py
+++ b/plugins/modules/vmware_object_role_permission.py
@@ -11,7 +11,7 @@
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: vmware_object_role_permission
 short_description: Manage local roles on an ESXi host
@@ -73,9 +73,12 @@
 
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 - name: Assign user to VM folder
   community.vmware.vmware_object_role_permission:
+    hostname: '{{ esxi_hostname }}'
+    username: '{{ esxi_username }}'
+    password: '{{ esxi_password }}'
     role: Admin
     principal: user_bob
     object_name: services
@@ -84,6 +87,9 @@
 
 - name: Remove user from VM folder
   community.vmware.vmware_object_role_permission:
+    hostname: '{{ esxi_hostname }}'
+    username: '{{ esxi_username }}'
+    password: '{{ esxi_password }}'
     role: Admin
     principal: user_bob
     object_name: services
@@ -92,6 +98,9 @@
 
 - name: Assign finance group to VM folder
   community.vmware.vmware_object_role_permission:
+    hostname: '{{ esxi_hostname }}'
+    username: '{{ esxi_username }}'
+    password: '{{ esxi_password }}'
     role: Limited Users
     group: finance
     object_name: Accounts
@@ -100,6 +109,9 @@
 
 - name: Assign view_user Read Only permission at root folder
   community.vmware.vmware_object_role_permission:
+    hostname: '{{ esxi_hostname }}'
+    username: '{{ esxi_username }}'
+    password: '{{ esxi_password }}'
     role: ReadOnly
     principal: view_user
     object_name: rootFolder

{"golden_diff": "diff --git a/plugins/modules/vmware_object_role_permission.py b/plugins/modules/vmware_object_role_permission.py\n--- a/plugins/modules/vmware_object_role_permission.py\n+++ b/plugins/modules/vmware_object_role_permission.py\n@@ -11,7 +11,7 @@\n __metaclass__ = type\n \n \n-DOCUMENTATION = '''\n+DOCUMENTATION = r'''\n ---\n module: vmware_object_role_permission\n short_description: Manage local roles on an ESXi host\n@@ -73,9 +73,12 @@\n \n '''\n \n-EXAMPLES = '''\n+EXAMPLES = r'''\n - name: Assign user to VM folder\n   community.vmware.vmware_object_role_permission:\n+    hostname: '{{ esxi_hostname }}'\n+    username: '{{ esxi_username }}'\n+    password: '{{ esxi_password }}'\n     role: Admin\n     principal: user_bob\n     object_name: services\n@@ -84,6 +87,9 @@\n \n - name: Remove user from VM folder\n   community.vmware.vmware_object_role_permission:\n+    hostname: '{{ esxi_hostname }}'\n+    username: '{{ esxi_username }}'\n+    password: '{{ esxi_password }}'\n     role: Admin\n     principal: user_bob\n     object_name: services\n@@ -92,6 +98,9 @@\n \n - name: Assign finance group to VM folder\n   community.vmware.vmware_object_role_permission:\n+    hostname: '{{ esxi_hostname }}'\n+    username: '{{ esxi_username }}'\n+    password: '{{ esxi_password }}'\n     role: Limited Users\n     group: finance\n     object_name: Accounts\n@@ -100,6 +109,9 @@\n \n - name: Assign view_user Read Only permission at root folder\n   community.vmware.vmware_object_role_permission:\n+    hostname: '{{ esxi_hostname }}'\n+    username: '{{ esxi_username }}'\n+    password: '{{ esxi_password }}'\n     role: ReadOnly\n     principal: view_user\n     object_name: rootFolder\n", "issue": "vmware_object_role_permission: Missing required parameters in examples\n##### SUMMARY\r\nExamples missing required fields of hostname, username, and password, while other module examples include these.\r\n\r\n##### ISSUE TYPE\r\n- Documentation Report\r\n\r\n##### COMPONENT NAME\r\nvmware_object_role_permission\r\n\r\n##### ADDITIONAL INFORMATION\r\nPR #422 \n", "before_files": [{"content": "#!/usr/bin/python\n# -*- coding: utf-8 -*-\n#\n# Copyright: (c) 2018, Derek Rushing <derek.rushing@geekops.com>\n# Copyright: (c) 2018, VMware, Inc.\n# SPDX-License-Identifier: GPL-3.0-or-later\n# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)\n\nfrom __future__ import absolute_import, division, print_function\n\n__metaclass__ = type\n\n\nDOCUMENTATION = '''\n---\nmodule: vmware_object_role_permission\nshort_description: Manage local roles on an ESXi host\ndescription: This module can be used to manage object permissions on the given host.\nauthor:\n- Derek Rushing (@kryptsi)\n- Joseph Andreatta (@vmwjoseph)\nnotes:\n    - Tested on ESXi 6.5, vSphere 6.7\n    - The ESXi login user must have the appropriate rights to administer permissions.\n    - Permissions for a distributed switch must be defined and managed on either the datacenter or a folder containing the switch.\nrequirements:\n    - \"python >= 2.7\"\n    - PyVmomi\noptions:\n  role:\n    description:\n    - The role to be assigned permission.\n    required: True\n    type: str\n  principal:\n    description:\n    - The user to be assigned permission.\n    - Required if C(group) is not specified.\n    type: str\n  group:\n    description:\n    - The group to be assigned permission.\n    - Required if C(principal) is not specified.\n    type: str\n  object_name:\n    description:\n    - The object name to assigned permission.\n    type: str\n    required: True\n  object_type:\n    description:\n    - The object type being targeted.\n    default: 'Folder'\n    choices: ['Folder', 'VirtualMachine', 'Datacenter', 'ResourcePool',\n              'Datastore', 'Network', 'HostSystem', 'ComputeResource',\n              'ClusterComputeResource', 'DistributedVirtualSwitch']\n    type: str\n  recursive:\n    description:\n    - Should the permissions be recursively applied.\n    default: True\n    type: bool\n  state:\n    description:\n    - Indicate desired state of the object's permission.\n    - When C(state=present), the permission will be added if it doesn't already exist.\n    - When C(state=absent), the permission is removed if it exists.\n    choices: ['present', 'absent']\n    default: present\n    type: str\nextends_documentation_fragment:\n- community.vmware.vmware.documentation\n\n'''\n\nEXAMPLES = '''\n- name: Assign user to VM folder\n  community.vmware.vmware_object_role_permission:\n    role: Admin\n    principal: user_bob\n    object_name: services\n    state: present\n  delegate_to: localhost\n\n- name: Remove user from VM folder\n  community.vmware.vmware_object_role_permission:\n    role: Admin\n    principal: user_bob\n    object_name: services\n    state: absent\n  delegate_to: localhost\n\n- name: Assign finance group to VM folder\n  community.vmware.vmware_object_role_permission:\n    role: Limited Users\n    group: finance\n    object_name: Accounts\n    state: present\n  delegate_to: localhost\n\n- name: Assign view_user Read Only permission at root folder\n  community.vmware.vmware_object_role_permission:\n    role: ReadOnly\n    principal: view_user\n    object_name: rootFolder\n    state: present\n  delegate_to: localhost\n'''\n\nRETURN = r'''\nchanged:\n    description: whether or not a change was made to the object's role\n    returned: always\n    type: bool\n'''\n\ntry:\n    from pyVmomi import vim, vmodl\nexcept ImportError:\n    pass\n\nfrom ansible.module_utils.basic import AnsibleModule\nfrom ansible.module_utils._text import to_native\nfrom ansible_collections.community.vmware.plugins.module_utils.vmware import PyVmomi, vmware_argument_spec, find_obj\n\n\nclass VMwareObjectRolePermission(PyVmomi):\n    def __init__(self, module):\n        super(VMwareObjectRolePermission, self).__init__(module)\n        self.module = module\n        self.params = module.params\n        self.is_group = False\n\n        if self.params.get('principal', None) is not None:\n            self.applied_to = self.params['principal']\n        elif self.params.get('group', None) is not None:\n            self.applied_to = self.params['group']\n            self.is_group = True\n\n        self.get_role()\n        self.get_object()\n        self.get_perms()\n        self.perm = self.setup_permission()\n        self.state = self.params['state']\n\n    def get_perms(self):\n        self.current_perms = self.content.authorizationManager.RetrieveEntityPermissions(self.current_obj, False)\n\n    def same_permission(self, perm_one, perm_two):\n        return perm_one.principal.lower() == perm_two.principal.lower() \\\n            and perm_one.roleId == perm_two.roleId\n\n    def get_state(self):\n        for perm in self.current_perms:\n            if self.same_permission(self.perm, perm):\n                return 'present'\n        return 'absent'\n\n    def process_state(self):\n        local_permission_states = {\n            'absent': {\n                'present': self.remove_permission,\n                'absent': self.state_exit_unchanged,\n            },\n            'present': {\n                'present': self.state_exit_unchanged,\n                'absent': self.add_permission,\n            }\n        }\n        try:\n            local_permission_states[self.state][self.get_state()]()\n        except vmodl.RuntimeFault as runtime_fault:\n            self.module.fail_json(msg=to_native(runtime_fault.msg))\n        except vmodl.MethodFault as method_fault:\n            self.module.fail_json(msg=to_native(method_fault.msg))\n        except Exception as e:\n            self.module.fail_json(msg=to_native(e))\n\n    def state_exit_unchanged(self):\n        self.module.exit_json(changed=False)\n\n    def setup_permission(self):\n        perm = vim.AuthorizationManager.Permission()\n        perm.entity = self.current_obj\n        perm.group = self.is_group\n        perm.principal = self.applied_to\n        perm.roleId = self.role.roleId\n        perm.propagate = self.params['recursive']\n        return perm\n\n    def add_permission(self):\n        if not self.module.check_mode:\n            self.content.authorizationManager.SetEntityPermissions(self.current_obj, [self.perm])\n        self.module.exit_json(changed=True)\n\n    def remove_permission(self):\n        if not self.module.check_mode:\n            self.content.authorizationManager.RemoveEntityPermission(self.current_obj, self.applied_to, self.is_group)\n        self.module.exit_json(changed=True)\n\n    def get_role(self):\n        for role in self.content.authorizationManager.roleList:\n            if role.name == self.params['role']:\n                self.role = role\n                return\n        self.module.fail_json(msg=\"Specified role (%s) was not found\" % self.params['role'])\n\n    def get_object(self):\n        # find_obj doesn't include rootFolder\n        if self.params['object_type'] == 'Folder' and self.params['object_name'] == 'rootFolder':\n            self.current_obj = self.content.rootFolder\n            return\n        try:\n            getattr(vim, self.params['object_type'])\n        except AttributeError:\n            self.module.fail_json(msg=\"Object type %s is not valid.\" % self.params['object_type'])\n        self.current_obj = find_obj(content=self.content,\n                                    vimtype=[getattr(vim, self.params['object_type'])],\n                                    name=self.params['object_name'])\n\n        if self.current_obj is None:\n            self.module.fail_json(\n                msg=\"Specified object %s of type %s was not found.\"\n                % (self.params['object_name'], self.params['object_type'])\n            )\n        if self.params['object_type'] == 'DistributedVirtualSwitch':\n            msg = \"You are applying permissions to a Distributed vSwitch. \" \\\n                  \"This will probably fail, since Distributed vSwitches inherits permissions \" \\\n                  \"from the datacenter or a folder level. \" \\\n                  \"Define permissions on the datacenter or the folder containing the switch.\"\n            self.module.warn(msg)\n\n\ndef main():\n    argument_spec = vmware_argument_spec()\n    argument_spec.update(\n        dict(\n            role=dict(required=True, type='str'),\n            object_name=dict(required=True, type='str'),\n            object_type=dict(\n                type='str',\n                default='Folder',\n                choices=[\n                    'Folder',\n                    'VirtualMachine',\n                    'Datacenter',\n                    'ResourcePool',\n                    'Datastore',\n                    'Network',\n                    'HostSystem',\n                    'ComputeResource',\n                    'ClusterComputeResource',\n                    'DistributedVirtualSwitch',\n                ],\n            ),\n            principal=dict(type='str'),\n            group=dict(type='str'),\n            recursive=dict(type='bool', default=True),\n            state=dict(default='present', choices=['present', 'absent'], type='str'),\n        )\n    )\n\n    module = AnsibleModule(\n        argument_spec=argument_spec,\n        supports_check_mode=True,\n        mutually_exclusive=[['principal', 'group']],\n        required_one_of=[['principal', 'group']],\n    )\n\n    vmware_object_permission = VMwareObjectRolePermission(module)\n    vmware_object_permission.process_state()\n\n\nif __name__ == '__main__':\n    main()\n", "path": "plugins/modules/vmware_object_role_permission.py"}], "after_files": [{"content": "#!/usr/bin/python\n# -*- coding: utf-8 -*-\n#\n# Copyright: (c) 2018, Derek Rushing <derek.rushing@geekops.com>\n# Copyright: (c) 2018, VMware, Inc.\n# SPDX-License-Identifier: GPL-3.0-or-later\n# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)\n\nfrom __future__ import absolute_import, division, print_function\n\n__metaclass__ = type\n\n\nDOCUMENTATION = r'''\n---\nmodule: vmware_object_role_permission\nshort_description: Manage local roles on an ESXi host\ndescription: This module can be used to manage object permissions on the given host.\nauthor:\n- Derek Rushing (@kryptsi)\n- Joseph Andreatta (@vmwjoseph)\nnotes:\n    - Tested on ESXi 6.5, vSphere 6.7\n    - The ESXi login user must have the appropriate rights to administer permissions.\n    - Permissions for a distributed switch must be defined and managed on either the datacenter or a folder containing the switch.\nrequirements:\n    - \"python >= 2.7\"\n    - PyVmomi\noptions:\n  role:\n    description:\n    - The role to be assigned permission.\n    required: True\n    type: str\n  principal:\n    description:\n    - The user to be assigned permission.\n    - Required if C(group) is not specified.\n    type: str\n  group:\n    description:\n    - The group to be assigned permission.\n    - Required if C(principal) is not specified.\n    type: str\n  object_name:\n    description:\n    - The object name to assigned permission.\n    type: str\n    required: True\n  object_type:\n    description:\n    - The object type being targeted.\n    default: 'Folder'\n    choices: ['Folder', 'VirtualMachine', 'Datacenter', 'ResourcePool',\n              'Datastore', 'Network', 'HostSystem', 'ComputeResource',\n              'ClusterComputeResource', 'DistributedVirtualSwitch']\n    type: str\n  recursive:\n    description:\n    - Should the permissions be recursively applied.\n    default: True\n    type: bool\n  state:\n    description:\n    - Indicate desired state of the object's permission.\n    - When C(state=present), the permission will be added if it doesn't already exist.\n    - When C(state=absent), the permission is removed if it exists.\n    choices: ['present', 'absent']\n    default: present\n    type: str\nextends_documentation_fragment:\n- community.vmware.vmware.documentation\n\n'''\n\nEXAMPLES = r'''\n- name: Assign user to VM folder\n  community.vmware.vmware_object_role_permission:\n    hostname: '{{ esxi_hostname }}'\n    username: '{{ esxi_username }}'\n    password: '{{ esxi_password }}'\n    role: Admin\n    principal: user_bob\n    object_name: services\n    state: present\n  delegate_to: localhost\n\n- name: Remove user from VM folder\n  community.vmware.vmware_object_role_permission:\n    hostname: '{{ esxi_hostname }}'\n    username: '{{ esxi_username }}'\n    password: '{{ esxi_password }}'\n    role: Admin\n    principal: user_bob\n    object_name: services\n    state: absent\n  delegate_to: localhost\n\n- name: Assign finance group to VM folder\n  community.vmware.vmware_object_role_permission:\n    hostname: '{{ esxi_hostname }}'\n    username: '{{ esxi_username }}'\n    password: '{{ esxi_password }}'\n    role: Limited Users\n    group: finance\n    object_name: Accounts\n    state: present\n  delegate_to: localhost\n\n- name: Assign view_user Read Only permission at root folder\n  community.vmware.vmware_object_role_permission:\n    hostname: '{{ esxi_hostname }}'\n    username: '{{ esxi_username }}'\n    password: '{{ esxi_password }}'\n    role: ReadOnly\n    principal: view_user\n    object_name: rootFolder\n    state: present\n  delegate_to: localhost\n'''\n\nRETURN = r'''\nchanged:\n    description: whether or not a change was made to the object's role\n    returned: always\n    type: bool\n'''\n\ntry:\n    from pyVmomi import vim, vmodl\nexcept ImportError:\n    pass\n\nfrom ansible.module_utils.basic import AnsibleModule\nfrom ansible.module_utils._text import to_native\nfrom ansible_collections.community.vmware.plugins.module_utils.vmware import PyVmomi, vmware_argument_spec, find_obj\n\n\nclass VMwareObjectRolePermission(PyVmomi):\n    def __init__(self, module):\n        super(VMwareObjectRolePermission, self).__init__(module)\n        self.module = module\n        self.params = module.params\n        self.is_group = False\n\n        if self.params.get('principal', None) is not None:\n            self.applied_to = self.params['principal']\n        elif self.params.get('group', None) is not None:\n            self.applied_to = self.params['group']\n            self.is_group = True\n\n        self.get_role()\n        self.get_object()\n        self.get_perms()\n        self.perm = self.setup_permission()\n        self.state = self.params['state']\n\n    def get_perms(self):\n        self.current_perms = self.content.authorizationManager.RetrieveEntityPermissions(self.current_obj, False)\n\n    def same_permission(self, perm_one, perm_two):\n        return perm_one.principal.lower() == perm_two.principal.lower() \\\n            and perm_one.roleId == perm_two.roleId\n\n    def get_state(self):\n        for perm in self.current_perms:\n            if self.same_permission(self.perm, perm):\n                return 'present'\n        return 'absent'\n\n    def process_state(self):\n        local_permission_states = {\n            'absent': {\n                'present': self.remove_permission,\n                'absent': self.state_exit_unchanged,\n            },\n            'present': {\n                'present': self.state_exit_unchanged,\n                'absent': self.add_permission,\n            }\n        }\n        try:\n            local_permission_states[self.state][self.get_state()]()\n        except vmodl.RuntimeFault as runtime_fault:\n            self.module.fail_json(msg=to_native(runtime_fault.msg))\n        except vmodl.MethodFault as method_fault:\n            self.module.fail_json(msg=to_native(method_fault.msg))\n        except Exception as e:\n            self.module.fail_json(msg=to_native(e))\n\n    def state_exit_unchanged(self):\n        self.module.exit_json(changed=False)\n\n    def setup_permission(self):\n        perm = vim.AuthorizationManager.Permission()\n        perm.entity = self.current_obj\n        perm.group = self.is_group\n        perm.principal = self.applied_to\n        perm.roleId = self.role.roleId\n        perm.propagate = self.params['recursive']\n        return perm\n\n    def add_permission(self):\n        if not self.module.check_mode:\n            self.content.authorizationManager.SetEntityPermissions(self.current_obj, [self.perm])\n        self.module.exit_json(changed=True)\n\n    def remove_permission(self):\n        if not self.module.check_mode:\n            self.content.authorizationManager.RemoveEntityPermission(self.current_obj, self.applied_to, self.is_group)\n        self.module.exit_json(changed=True)\n\n    def get_role(self):\n        for role in self.content.authorizationManager.roleList:\n            if role.name == self.params['role']:\n                self.role = role\n                return\n        self.module.fail_json(msg=\"Specified role (%s) was not found\" % self.params['role'])\n\n    def get_object(self):\n        # find_obj doesn't include rootFolder\n        if self.params['object_type'] == 'Folder' and self.params['object_name'] == 'rootFolder':\n            self.current_obj = self.content.rootFolder\n            return\n        try:\n            getattr(vim, self.params['object_type'])\n        except AttributeError:\n            self.module.fail_json(msg=\"Object type %s is not valid.\" % self.params['object_type'])\n        self.current_obj = find_obj(content=self.content,\n                                    vimtype=[getattr(vim, self.params['object_type'])],\n                                    name=self.params['object_name'])\n\n        if self.current_obj is None:\n            self.module.fail_json(\n                msg=\"Specified object %s of type %s was not found.\"\n                % (self.params['object_name'], self.params['object_type'])\n            )\n        if self.params['object_type'] == 'DistributedVirtualSwitch':\n            msg = \"You are applying permissions to a Distributed vSwitch. \" \\\n                  \"This will probably fail, since Distributed vSwitches inherits permissions \" \\\n                  \"from the datacenter or a folder level. \" \\\n                  \"Define permissions on the datacenter or the folder containing the switch.\"\n            self.module.warn(msg)\n\n\ndef main():\n    argument_spec = vmware_argument_spec()\n    argument_spec.update(\n        dict(\n            role=dict(required=True, type='str'),\n            object_name=dict(required=True, type='str'),\n            object_type=dict(\n                type='str',\n                default='Folder',\n                choices=[\n                    'Folder',\n                    'VirtualMachine',\n                    'Datacenter',\n                    'ResourcePool',\n                    'Datastore',\n                    'Network',\n                    'HostSystem',\n                    'ComputeResource',\n                    'ClusterComputeResource',\n                    'DistributedVirtualSwitch',\n                ],\n            ),\n            principal=dict(type='str'),\n            group=dict(type='str'),\n            recursive=dict(type='bool', default=True),\n            state=dict(default='present', choices=['present', 'absent'], type='str'),\n        )\n    )\n\n    module = AnsibleModule(\n        argument_spec=argument_spec,\n        supports_check_mode=True,\n        mutually_exclusive=[['principal', 'group']],\n        required_one_of=[['principal', 'group']],\n    )\n\n    vmware_object_permission = VMwareObjectRolePermission(module)\n    vmware_object_permission.process_state()\n\n\nif __name__ == '__main__':\n    main()\n", "path": "plugins/modules/vmware_object_role_permission.py"}]}