1#!/usr/bin/python
2# -*- coding: utf-8 -*-
3#
4# Copyright (c) 2016 Red Hat, Inc.
5#
6# This file is part of Ansible
7#
8# Ansible is free software: you can redistribute it and/or modify
9# it under the terms of the GNU General Public License as published by
10# the Free Software Foundation, either version 3 of the License, or
11# (at your option) any later version.
12#
13# Ansible is distributed in the hope that it will be useful,
14# but WITHOUT ANY WARRANTY; without even the implied warranty of
15# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16# GNU General Public License for more details.
17#
18# You should have received a copy of the GNU General Public License
19# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
20#
21
22ANSIBLE_METADATA = {'metadata_version': '1.1',
23                    'status': ['preview'],
24                    'supported_by': 'community'}
25
26
27DOCUMENTATION = '''
28---
29module: ovirt_group_info
30short_description: Retrieve information about one or more oVirt/RHV groups
31author: "Ondra Machacek (@machacekondra)"
32version_added: "2.3"
33description:
34    - "Retrieve information about one or more oVirt/RHV groups."
35    - This module was called C(ovirt_group_facts) before Ansible 2.9, returning C(ansible_facts).
36      Note that the M(ovirt_group_info) module no longer returns C(ansible_facts)!
37notes:
38    - "This module returns a variable C(ovirt_groups), which
39       contains a list of groups. You need to register the result with
40       the I(register) keyword to use it."
41options:
42    pattern:
43      description:
44        - "Search term which is accepted by oVirt/RHV search backend."
45        - "For example to search group X use following pattern: name=X"
46extends_documentation_fragment: ovirt_info
47'''
48
49EXAMPLES = '''
50# Examples don't contain auth parameter for simplicity,
51# look at ovirt_auth module to see how to reuse authentication:
52
53# Gather information about all groups which names start with C(admin):
54- ovirt_group_info:
55    pattern: name=admin*
56  register: result
57- debug:
58    msg: "{{ result.ovirt_groups }}"
59'''
60
61RETURN = '''
62ovirt_groups:
63    description: "List of dictionaries describing the groups. Group attributes are mapped to dictionary keys,
64                  all groups attributes can be found at following url: http://ovirt.github.io/ovirt-engine-api-model/master/#types/group."
65    returned: On success.
66    type: list
67'''
68
69import traceback
70
71from ansible.module_utils.basic import AnsibleModule
72from ansible.module_utils.ovirt import (
73    check_sdk,
74    create_connection,
75    get_dict_of_struct,
76    ovirt_info_full_argument_spec,
77)
78
79
80def main():
81    argument_spec = ovirt_info_full_argument_spec(
82        pattern=dict(default='', required=False),
83    )
84    module = AnsibleModule(argument_spec)
85    is_old_facts = module._name == 'ovirt_group_facts'
86    if is_old_facts:
87        module.deprecate("The 'ovirt_group_facts' module has been renamed to 'ovirt_group_info', "
88                         "and the renamed one no longer returns ansible_facts", version='2.13')
89
90    check_sdk(module)
91
92    try:
93        auth = module.params.pop('auth')
94        connection = create_connection(auth)
95        groups_service = connection.system_service().groups_service()
96        groups = groups_service.list(search=module.params['pattern'])
97        result = dict(
98            ovirt_groups=[
99                get_dict_of_struct(
100                    struct=c,
101                    connection=connection,
102                    fetch_nested=module.params.get('fetch_nested'),
103                    attributes=module.params.get('nested_attributes'),
104                ) for c in groups
105            ],
106        )
107        if is_old_facts:
108            module.exit_json(changed=False, ansible_facts=result)
109        else:
110            module.exit_json(changed=False, **result)
111    except Exception as e:
112        module.fail_json(msg=str(e), exception=traceback.format_exc())
113    finally:
114        connection.close(logout=auth.get('token') is None)
115
116
117if __name__ == '__main__':
118    main()
119