New automount map management module.

There is a new server management module placed in the plugins folder:

    plugins/modules/ipaautomountmap.py

The server module allows to ensure presence and absence of automount
maps. The module requires an existing automount location to place the
map within. It does not create any automount keys with in the map.

Here is the documentation for the module:

    README-automountmap.md

New example playbooks have been added:

    playbooks/automount/automount-map-absent.yaml
    playbooks/automount/automount-map-present.yaml

New tests for the module:

    tests/automount/test_automountmap.yml

README-automountmap.md

+Automountmap module
+=====================
+
+Description
+-----------
+
+The automountmap module allows the addition and removal of maps within automount locations. 
+
+It is desgined to follow the IPA api as closely as possible while ensuring ease of use.
+
+
+Features
+--------
+* Automount map management
+
+Supported FreeIPA Versions
+--------------------------
+
+FreeIPA versions 4.4.0 and up are supported by the ipaautomountmap module.
+
+Requirements
+------------
+**Controller**
+* Ansible version: 2.8+
+
+**Node**
+* Supported FreeIPA version (see above)
+
+
+Usage
+=====
+
+Example inventory file
+
+```ini
+[ipaserver]
+ipaserver.test.local
+```
+
+
+Example playbook to ensure presence of an automount map:
+
+```yaml
+---
+- name: Playbook to add an automount map
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  - name: ensure map named auto.DMZ in location DMZ is created
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: auto.DMZ
+      location: DMZ
+      desc: "this is a map for servers in the DMZ"
+```
+
+
+Example playbook to ensure auto.DMZi does not exist
+```yaml
+---
+- name: Playbook to remove an automount map
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  - name: ensure map auto.DMZ has been removed
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: auto.DMZ
+      location: DMX
+      state: absent
+```
+
+
+Variables
+=========
+
+ipaautomountmap
+-------
+
+Variable | Description | Required
+-------- | ----------- | --------
+`ipaadmin_principal` | The admin principal is a string and defaults to `admin` | no
+`ipaadmin_password` | The admin password is a string and is required if there is no admin ticket available on the node | no
+`name` \| `mapname` \| `map` \| `automountmapname` | Name of the map to manage | yes
+`location` \| `automountlocation` \| `automountlocationcn` | Location name. | yes
+`desc` \| `description` | Description of the map | yes
+`state` | The state to ensure. It can be one of `present`, or `absent`, default: `present`. | no
+
+
+Authors
+=======
+
+Chris Procter

playbooks/automount/automount-map-absent.yaml

+---
+- name: Automount map absent example
+  hosts: ipaserver
+  become: true
+  tasks:
+  - name: ensure map TestMap is absent
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      state: absent
+

playbooks/automount/automount-map-present.yaml

+---
+- name: Automount map present example
+  hosts: ipaserver
+  become: true
+  tasks:
+  - name: ensure map TestMap is present
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      desc: "this is a test map"
+

plugins/modules/ipaautomountmap.py

+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Authors:
+#   Chris Procter <cprocter@redhat.com>
+#
+# Copyright (C) 2021 Red Hat
+# see file 'COPYING' for use and warranty information
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+ANSIBLE_METADATA = {
+    "metadata_version": "1.0",
+    "supported_by": "community",
+    "status": ["preview"],
+}
+
+
+DOCUMENTATION = '''
+---
+module: ipaautomountmap
+author: chris procter
+short_description: Manage FreeIPA autommount map
+description:
+- Add, delete, and modify an IPA automount map
+options:
+  ipaadmin_principal:
+    description: The admin principal
+    default: admin
+  ipaadmin_password:
+    description: The admin password
+    required: false
+  automountlocation:
+    description: automount location map is anchored to
+    choices: ["location", "automountlocationcn"]
+    required: True
+  name:
+    description: automount map to be managed
+    choices: ["mapname", "map", "automountmapname"]
+    required: True
+  desc:
+    description: description of automount map
+    choices: ["description"]
+    required: false
+  state:
+    description: State to ensure
+    required: false
+    default: present
+    choices: ["present", "absent"]
+'''
+
+EXAMPLES = '''
+  - name: ensure map named auto.DMZ in location DMZ is present
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: auto.DMZ
+      location: DMZ
+      desc: "this is a map for servers in the DMZ"
+
+  - name: remove a map named auto.DMZ in location DMZ if it exists
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: auto.DMZ
+      location: DMZ
+      state: absent
+'''
+
+RETURN = '''
+'''
+
+from ansible.module_utils.ansible_freeipa_module import FreeIPABaseModule
+
+
+class AutomountMap(FreeIPABaseModule):
+
+    ipa_param_mapping = {
+        "automountmapname": "name",
+    }
+
+    def get_map(self, location, name):
+        response = dict()
+        try:
+            response = self.api_command("automountmap_show",
+                                        location,
+                                        {"automountmapname": name})
+        except Exception:
+            pass
+
+        return response.get("result", None)
+
+    def check_ipa_params(self):
+
+        if self.ipa_params.state == "present":
+            if len(self.ipa_params.name) != 1:
+                self.fail_json(msg="Exactly one name must be provided \
+                                for state=present.")
+        else:
+            if len(self.ipa_params.name) == 0 :
+                self.fail_json(msg="At least one name must be provided \
+                                when state=absent.")
+
+    def define_ipa_commands(self):
+        args = self.get_ipa_command_args()
+
+        if self.ipa_params.state == "present":
+            automountmap = self.get_map(self.ipa_params.location,
+                                        self.ipa_params.name[0])
+            args['automountmapname'] = self.ipa_params.name[0]
+            if automountmap is None:
+                # does not exist and is wanted
+                self.add_ipa_command(
+                    "automountmap_add",
+                    name=self.ipa_params.location,
+                    args=args
+                )
+            else:
+                # exists and is wanted, check for changes
+                if self.ipa_params.desc != \
+                        automountmap.get('description', [None])[0]:
+                    args['description'] = self.ipa_params.desc
+                    self.add_ipa_command(
+                        "automountmap_mod",
+                        name=self.ipa_params.location,
+                        args=args
+                    )
+        else:
+            # exists and is not wanted (i.e. self.ipa_params.state == "absent")
+            to_del = [x for x in self.ipa_params.name
+                      if self.get_map(self.ipa_params.location, x) is not None]
+
+            if len(to_del) > 0:
+                self.add_ipa_command(
+                    "automountmap_del",
+                    name=self.ipa_params.location,
+                    args={"automountmapname": to_del}
+                )
+
+
+def main():
+    ipa_module = AutomountMap(
+        argument_spec=dict(
+            ipaadmin_principal=dict(type="str",
+                                    default="admin"
+                                    ),
+            ipaadmin_password=dict(type="str",
+                                   required=False,
+                                   no_log=True
+                                   ),
+            state=dict(type='str',
+                       default='present',
+                       choices=['present', 'absent']
+                       ),
+            location=dict(type="str",
+                          aliases=["automountlocation", "automountlocationcn"],
+                          default=None,
+                          required=True
+                          ),
+            name=dict(type="list",
+                      aliases=["mapname", "map", "automountmapname"],
+                      default=None,
+                      required=True
+                      ),
+            desc=dict(type="str",
+                      aliases=["description"],
+                      required=False,
+                      default=None
+                      ),
+        ),
+    )
+    ipa_module.ipa_run()
+
+
+if __name__ == "__main__":
+    main()

tests/automount/test_automountmap.yml

+---
+- name: Test automountmap
+  hosts: ipaserver
+  become: true
+  gather_facts: false
+
+  tasks:
+  - name: ensure location TestLocation is absent
+    ipaautomountlocation:
+      ipaadmin_password: SomeADMINpassword
+      name: TestLocation
+      state: absent
+
+  - name: ensure map TestMap is absent
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      state: absent
+
+  - name: ensure location TestLocation is present
+    ipaautomountlocation:
+      ipaadmin_password: SomeADMINpassword
+      name: TestLocation
+      state: present
+
+  - name: ensure map TestMap is present
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      desc: "this is a test map that should be deleted by the test"
+    register: result
+    failed_when: result.failed or not result.changed
+
+  - name: ensure map TestMap is present again
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+    register: result
+    failed_when: result.failed or result.changed
+
+  - name: ensure map TestMap has a different description
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      desc: "this is a changed description that should be deleted by the test"
+    register: result
+    failed_when: result.failed or  not result.changed
+
+  - name: ensure map TestMap has a different description
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      desc: "this is a changed description that should be deleted by the test"
+    register: result
+    failed_when: result.failed or result.changed
+
+  - name: ensure map TestMap is removed
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      state: absent
+    register: result
+    failed_when: result.failed or not result.changed
+
+  - name: ensure map TestMap has been removed
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap
+      location: TestLocation
+      state: absent
+    register: result
+    failed_when: result.failed or result.changed
+
+  - name: ensure map TestMap01 is present
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap01
+      location: TestLocation
+      desc: "this is a changed description that should be deleted by the test"
+    register: result
+    failed_when: result.failed or not result.changed
+
+  - name: ensure map TestMap02 is present
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name: TestMap02
+      location: TestLocation
+      desc: "this is a changed description that should be deleted by the test"
+    register: result
+    failed_when: result.failed or not result.changed
+
+  - name: ensure TestMap01 and TestMap02 are both absent
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name:
+        - TestMap01
+        - TestMap02
+      location: TestLocation
+      state: absent
+    register: result
+    failed_when: result.failed or not result.changed
+
+  - name: ensure TestMap01 and TestMap02 are both absent again
+    ipaautomountmap:
+      ipaadmin_password: SomeADMINpassword
+      name:
+        - TestMap01
+        - TestMap02
+      location: TestLocation
+      state: absent
+    register: result
+    failed_when: result.failed or result.changed
+
+  - name: ensure location TestLocation is absent
+    ipaautomountlocation:
+      ipaadmin_password: SomeADMINpassword
+      name: TestLocation
+      state: absent
+    register: result
+    failed_when: result.failed or not result.changed
+
+  - name: ensure location TestLocation is absent again
+    ipaautomountlocation:
+      ipaadmin_password: SomeADMINpassword
+      name: TestLocation
+      state: absent
+    register: result
+    failed_when: result.failed or result.changed
+