Implement basic Hetzner API support for more storagebox modules (#168)

* Implement basic Hetzner API support for storagebox_set_password.

* Implement basic Hetzner API support for storagebox_snapshot_info.

* Update/extend API.

* Implement basic Hetzner API support for storagebox_snapshot.

Author: felixfontein

antsibull-nox.toml

@@ -49,9 +49,6 @@ doc_fragment = "community.hrobot.attributes.actiongroup_robot"
 name = "api"
 pattern = "^storagebox.*$"
 exclusions = [
-    "storagebox_set_password",
-    "storagebox_snapshot_info",
-    "storagebox_snapshot",
     "storagebox_subaccount_info",
     "storagebox_subaccount",
 ]

changelogs/fragments/166-storagebox.yml

@@ -15,4 +15,5 @@ minor_changes:
     and the new ``community.hrobot.api`` action group, and will eventually drop the ``community.hrobot.robot`` action group once
     the Robot API for storage boxes is removed by Hetzner
     (https://github.com/ansible-collections/community.hrobot/pull/166,
-     https://github.com/ansible-collections/community.hrobot/pull/167).
+     https://github.com/ansible-collections/community.hrobot/pull/167,
+     https://github.com/ansible-collections/community.hrobot/pull/168).

changelogs/fragments/168-storagebox.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - "storagebox_set_password - support the new Hetzner API (https://github.com/ansible-collections/community.hrobot/pull/168)."
+  - "storagebox_snapshot - support the new Hetzner API (https://github.com/ansible-collections/community.hrobot/pull/168)."
+  - "storagebox_snapshot_info - support the new Hetzner API (https://github.com/ansible-collections/community.hrobot/pull/168)."

meta/runtime.yml

@@ -31,5 +31,8 @@ action_groups:
   api:
     - storagebox
     - storagebox_info
+    - storagebox_set_password
+    - storagebox_snapshot
+    - storagebox_snapshot_info
     - storagebox_snapshot_plan
     - storagebox_snapshot_plan_info

plugins/module_utils/api.py

@@ -189,6 +189,7 @@ def api_fetch_url_json_list(
     method='GET',
     timeout=10,
     headers=None,
+    accept_errors=None,
     page_size=100,
 ):
     '''
@@ -199,13 +200,17 @@ def api_fetch_url_json_list(
     result_list = []
     while page is not None and (last_page is None or last_page >= page):
         page_url = '{0}{1}{2}'.format(url, '&' if '?' in url else '?', deterministic_urlencode({"page": str(page), "per_page": page_size}))
-        result, dummy, dummy2 = api_fetch_url_json(
+        result, dummy, error = api_fetch_url_json(
             module,
             page_url,
             method=method,
             timeout=timeout,
             headers=headers,
+            accept_errors=accept_errors,
         )
+        # TODO: add coverage!
+        if error:  # pragma: no cover
+            return result_list, error  # pragma: no cover
         if isinstance(result.get(data_key), list):
             result_list += result[data_key]
         if isinstance(result.get("meta"), dict) and isinstance(result["meta"].get("pagination"), dict):
@@ -220,7 +225,7 @@ def api_fetch_url_json_list(
             break
         else:
             page += 1
-    return result_list
+    return result_list, None
 
 
 def api_fetch_url_json_with_retries(module, url, check_done_callback, check_done_delay=10, check_done_timeout=180, skip_first=False, **kwargs):
@@ -255,15 +260,27 @@ class ApplyActionError(Exception):
     pass
 
 
-def api_apply_action(module, action_url, action_data, action_check_url_provider, check_done_delay=10, check_done_timeout=180):
+def api_apply_action(
+    module,
+    action_url,
+    action_data,
+    action_check_url_provider,
+    method='POST',
+    check_done_delay=10,
+    check_done_timeout=180,
+    accept_errors=None,
+):
     headers = {"Content-type": "application/json"} if action_data is not None else {}
-    result, dummy, dummy2 = api_fetch_url_json(
+    result, dummy, error = api_fetch_url_json(
         module,
         action_url,
         data=module.jsonify(action_data) if action_data is not None else None,
         headers=headers,
-        method='POST',
+        method=method,
+        accept_errors=accept_errors,
     )
+    if error:
+        return error
     action_id = result["action"]["id"]
     if result["action"]["status"] == "running":
         this_action_url = action_check_url_provider(action_id)
@@ -284,3 +301,4 @@ def action_done_callback(result_, info_, error_):
         raise ApplyActionError('[{0}] {1}'.format(to_native(error.get("code")), to_native(error.get("message"))))
     elif result["action"]["status"] == "error":
         raise ApplyActionError('Unknown error')
+    return None

plugins/modules/storagebox_info.py

@@ -624,7 +624,7 @@ def main():
                 storageboxes = [result["storage_box"]]
         else:
             url = "{0}/v1/storage_boxes".format(API_BASE_URL)
-            storageboxes = api_fetch_url_json_list(module, url, data_key="storage_boxes")
+            storageboxes, dummy = api_fetch_url_json_list(module, url, data_key="storage_boxes")
         storageboxes = [add_hrobot_compat_shim(storagebox) for storagebox in storageboxes]
 
     module.exit_json(

plugins/modules/storagebox_set_password.py

@@ -17,8 +17,12 @@
 description:
   - (Re)set the password for a storage box.
 extends_documentation_fragment:
+  - community.hrobot.api._robot_compat_shim  # must come before api and robot
+  - community.hrobot.api
   - community.hrobot.robot
   - community.hrobot.attributes
+  - community.hrobot.attributes._actiongroup_robot_and_api  # must come before the other two!
+  - community.hrobot.attributes.actiongroup_api
   - community.hrobot.attributes.actiongroup_robot
 
 attributes:
@@ -32,6 +36,8 @@
       - This module performs an action on every invocation.
 
 options:
+  hetzner_token:
+    version_added: 2.5.0
   id:
     description:
       - The ID of the storage box to modify.
@@ -42,6 +48,7 @@
       - The new password for the storage box.
       - If not provided, a random password will be created by the Robot API
         and returned as RV(password).
+      - This option is required if O(hetzner_token) is provided, since the new API does not support setting (and returning) a random password.
     type: str
 """
 
@@ -52,7 +59,7 @@
     id: 123
     password: "newpassword"
 
-- name: Set a random password
+- name: Set a random password (only works with the legacy Robot API)
   community.hrobot.storagebox_set_password:
     id: 123
   register: result
@@ -79,41 +86,83 @@
 from ansible_collections.community.hrobot.plugins.module_utils.robot import (
     BASE_URL,
     ROBOT_DEFAULT_ARGUMENT_SPEC,
+    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT,
     fetch_url_json,
 )
 
+from ansible_collections.community.hrobot.plugins.module_utils.api import (
+    API_BASE_URL,
+    API_DEFAULT_ARGUMENT_SPEC,
+    _API_DEFAULT_ARGUMENT_SPEC_COMPAT,
+    ApplyActionError,
+    api_apply_action,
+)
+
 
 def main():
-    argument_spect = dict(
+    argument_spec = dict(
         id=dict(type="int", required=True),
         password=dict(type="str", no_log=True),
     )
-    argument_spect.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
-    module = AnsibleModule(argument_spect, supports_check_mode=False)
+    argument_spec.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
+    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    argument_spec.update(API_DEFAULT_ARGUMENT_SPEC)
+    argument_spec.update(_API_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    module = AnsibleModule(
+        argument_spec,
+        supports_check_mode=False,
+        required_by={"hetzner_token": "password"},
+    )
 
     id = module.params["id"]
     password = module.params.get("password")
 
-    url = "{0}/storagebox/{1}/password".format(BASE_URL, id)
-    accepted_errors = ["STORAGEBOX_NOT_FOUND", "STORAGEBOX_INVALID_PASSWORD"]
+    if module.params["hetzner_user"] is not None:
+        # DEPRECATED: old API
+        url = "{0}/storagebox/{1}/password".format(BASE_URL, id)
+        accepted_errors = ["STORAGEBOX_NOT_FOUND", "STORAGEBOX_INVALID_PASSWORD"]
 
-    if password:
-        headers = {"Content-type": "application/x-www-form-urlencoded"}
-        result, error = fetch_url_json(
-            module, url, method="POST", accept_errors=accepted_errors, data=urlencode({"password": password}), headers=headers)
-    else:
-        result, error = fetch_url_json(
-            module, url, method="POST", accept_errors=accepted_errors)
+        if password:
+            headers = {"Content-type": "application/x-www-form-urlencoded"}
+            result, error = fetch_url_json(
+                module, url, method="POST", accept_errors=accepted_errors, data=urlencode({"password": password}), headers=headers)
+        else:
+            result, error = fetch_url_json(
+                module, url, method="POST", accept_errors=accepted_errors)
+
+        if error == 'STORAGEBOX_NOT_FOUND':
+            module.fail_json(
+                msg='Storage Box with ID {0} not found'.format(id))
 
-    if error == 'STORAGEBOX_NOT_FOUND':
-        module.fail_json(
-            msg='Storage Box with ID {0} not found'.format(id))
+        if error == 'STORAGEBOX_INVALID_PASSWORD':
+            module.fail_json(
+                msg="The chosen password has been considered insecure or does not comply with Hetzner's password guideline")
 
-    if error == 'STORAGEBOX_INVALID_PASSWORD':
-        module.fail_json(
-            msg="The chosen password has been considered insecure or does not comply with Hetzner's password guideline")
+        module.exit_json(changed=True, password=result["password"])
 
-    module.exit_json(changed=True, password=result["password"])
+    else:
+        # NEW API!
+        action_url = "{0}/v1/storage_boxes/{1}/actions/reset_password".format(API_BASE_URL, id)
+        action = {
+            "password": password,
+        }
+        try:
+            error = api_apply_action(
+                module,
+                action_url,
+                action,
+                lambda action_id: "{0}/v1/storage_boxes/actions/{1}".format(API_BASE_URL, action_id),
+                check_done_delay=1,
+                check_done_timeout=60,
+                accept_errors=["not_found"],
+            )
+        except ApplyActionError as exc:
+            module.fail_json(msg='Error while resetting password: {0}'.format(exc))
+
+        if error == "not_found":
+            module.fail_json(msg='Storage Box with ID {0} not found'.format(id))
+
+        module.exit_json(changed=True, password=password)
 
 
 if __name__ == '__main__':  # pragma: no cover