docker_plugin - adding alias option and general cleanup

changelogs/fragments/161-docker_plugin-alias-option.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - docker_plugin - added ``alias`` option to specify local names for docker plugins (https://github.com/ansible-collections/community.docker/pull/161).

plugins/modules/docker_plugin.py

@@ -37,6 +37,12 @@
       - disable
     type: str
 
+  alias:
+    description:
+     - Local name for plugin.
+    type: str
+    version_added: 1.8.0
+
   plugin_options:
     description:
       - Dictionary of plugin settings.
@@ -91,7 +97,7 @@
 
 - name: Install a plugin with options
   community.docker.docker_plugin:
-    name: weaveworks/net-plugin:latest_release
+    plugin_name: weaveworks/net-plugin:latest_release
     plugin_options:
       IPALLOC_RANGE: "10.32.0.0/12"
       WEAVE_PASSWORD: "PASSWORD"
@@ -104,11 +110,16 @@
     returned: success
     type: dict
     sample: {}
+actions:
+    description:
+      - List of actions performed during task execution.
+    returned: when I(state!=absent)
+    type: list
 '''
 
 import traceback
 
-from ansible.module_utils._text import to_native
+from ansible.module_utils.common.text.converters import to_native
 
 try:
     from docker.errors import APIError, NotFound, DockerException
@@ -130,6 +141,7 @@ def __init__(self, client):
         super(TaskParameters, self).__init__()
         self.client = client
         self.plugin_name = None
+        self.alias = None
         self.plugin_options = None
         self.debug = None
         self.force_remove = None
@@ -156,15 +168,15 @@ def __init__(self, client):
         self.dclient.api = client
 
         self.parameters = TaskParameters(client)
+        self.preferred_name = self.parameters.alias or self.parameters.plugin_name
         self.check_mode = self.client.check_mode
-        self.results = {
-            u'changed': False,
-            u'actions': []
-        }
         self.diff = self.client.module._diff
         self.diff_tracker = DifferenceTracker()
         self.diff_result = dict()
 
+        self.actions = []
+        self.changed = False
+
         self.existing_plugin = self.get_existing_plugin()
 
         state = self.parameters.state
@@ -180,12 +192,11 @@ def __init__(self, client):
         if self.diff or self.check_mode or self.parameters.debug:
             if self.diff:
                 self.diff_result['before'], self.diff_result['after'] = self.diff_tracker.get_before_after()
-            self.results['diff'] = self.diff_result
+            self.diff = self.diff_result
 
     def get_existing_plugin(self):
-        name = self.parameters.plugin_name
         try:
-            plugin = self.dclient.plugins.get(name)
+            plugin = self.dclient.plugins.get(self.preferred_name)
         except NotFound:
             return None
         except APIError as e:
@@ -225,14 +236,16 @@ def install_plugin(self):
         if not self.existing_plugin:
             if not self.check_mode:
                 try:
-                    self.existing_plugin = self.dclient.plugins.install(self.parameters.plugin_name, None)
+                    self.existing_plugin = self.dclient.plugins.install(
+                        self.parameters.plugin_name, self.parameters.alias
+                    )
                     if self.parameters.plugin_options:
                         self.existing_plugin.configure(prepare_options(self.parameters.plugin_options))
                 except APIError as e:
                     self.client.fail(to_native(e))
 
-            self.results['actions'].append("Installed plugin %s" % self.parameters.plugin_name)
-            self.results['changed'] = True
+            self.actions.append("Installed plugin %s" % self.preferred_name)
+            self.changed = True
 
     def remove_plugin(self):
         force = self.parameters.force_remove
@@ -243,8 +256,8 @@ def remove_plugin(self):
                 except APIError as e:
                     self.client.fail(to_native(e))
 
-            self.results['actions'].append("Removed plugin %s" % self.parameters.plugin_name)
-            self.results['changed'] = True
+            self.actions.append("Removed plugin %s" % self.preferred_name)
+            self.changed = True
 
     def update_plugin(self):
         if self.existing_plugin:
@@ -255,10 +268,10 @@ def update_plugin(self):
                         self.existing_plugin.configure(prepare_options(self.parameters.plugin_options))
                     except APIError as e:
                         self.client.fail(to_native(e))
-                self.results['actions'].append("Updated plugin %s settings" % self.parameters.plugin_name)
-                self.results['changed'] = True
+                self.actions.append("Updated plugin %s settings" % self.preferred_name)
+                self.changed = True
         else:
-            self.fail("Cannot update the plugin: Plugin does not exist")
+            self.client.fail("Cannot update the plugin: Plugin does not exist")
 
     def present(self):
         differences = DifferenceTracker()
@@ -276,7 +289,7 @@ def present(self):
             self.diff_tracker.merge(differences)
 
         if not self.check_mode and not self.parameters.debug:
-            self.results.pop('actions')
+            self.actions = None
 
     def absent(self):
         self.remove_plugin()
@@ -290,17 +303,17 @@ def enable(self):
                         self.existing_plugin.enable(timeout)
                     except APIError as e:
                         self.client.fail(to_native(e))
-                self.results['actions'].append("Enabled plugin %s" % self.parameters.plugin_name)
-                self.results['changed'] = True
+                self.actions.append("Enabled plugin %s" % self.preferred_name)
+                self.changed = True
         else:
             self.install_plugin()
             if not self.check_mode:
                 try:
                     self.existing_plugin.enable(timeout)
                 except APIError as e:
                     self.client.fail(to_native(e))
-            self.results['actions'].append("Enabled plugin %s" % self.parameters.plugin_name)
-            self.results['changed'] = True
+            self.actions.append("Enabled plugin %s" % self.preferred_name)
+            self.changed = True
 
     def disable(self):
         if self.existing_plugin:
@@ -310,14 +323,25 @@ def disable(self):
                         self.existing_plugin.disable()
                     except APIError as e:
                         self.client.fail(to_native(e))
-                self.results['actions'].append("Disable plugin %s" % self.parameters.plugin_name)
-                self.results['changed'] = True
+                self.actions.append("Disable plugin %s" % self.preferred_name)
+                self.changed = True
         else:
-            self.fail("Plugin not found: Plugin does not exist.")
+            self.client.fail("Plugin not found: Plugin does not exist.")
+
+    @property
+    def result(self):
+        result = {
+            'actions': self.actions,
+            'changed': self.changed,
+            'diff': self.diff,
+            'plugin': self.client.inspect_plugin(self.preferred_name) if self.parameters.state != 'absent' else {}
+        }
+        return dict((k, v) for k, v in result.items() if v is not None)
 
 
 def main():
     argument_spec = dict(
+        alias=dict(type='str'),
         plugin_name=dict(type='str', required=True),
         state=dict(type='str', default='present', choices=['present', 'absent', 'enable', 'disable']),
         plugin_options=dict(type='dict', default={}),
@@ -334,7 +358,7 @@ def main():
 
     try:
         cm = DockerPluginManager(client)
-        client.module.exit_json(**cm.results)
+        client.module.exit_json(**cm.result)
     except DockerException as e:
         client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
     except RequestException as e:

tests/integration/targets/docker_plugin/tasks/tests/basic_with_alias.yml

@@ -0,0 +1,79 @@
+---
+- name: Register plugin name and alias
+  set_fact:
+    plugin_name: "{{ name_prefix }}"
+    alias: "test"
+
+- name: Create a plugin with an alias
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: present
+  register: create_1
+
+- name: Create a plugin  with an alias (Idempotent)
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: present
+  register: create_2
+
+- name: Enable a plugin with an alias
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: enable
+  register: create_3
+
+- name: Enable a plugin with an alias (Idempotent)
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: enable
+  register: create_4
+
+- name: Disable a plugin with an alias
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: disable
+  register: absent_1
+
+- name: Disable a plugin with an alias (Idempotent)
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: disable
+  register: absent_2
+
+- name: Remove a plugin with an alias
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: absent
+  register: absent_3
+
+- name: Remove a plugin with an alias (Idempotent)
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: absent
+  register: absent_4
+
+- assert:
+    that:
+    - create_1 is changed
+    - create_2 is not changed
+    - create_3 is changed
+    - create_4 is not changed
+    - absent_1 is changed
+    - absent_2 is not changed
+    - absent_3 is changed
+    - absent_4 is not changed
+
+- name: Cleanup plugin with an alias
+  docker_plugin:
+    plugin_name: "{{ plugin_name }}"
+    alias: "{{ alias }}"
+    state: absent
+    force_remove: true