feat: improve firewall resources management (#324)

##### SUMMARY

  - firewall - Return resources the firewall is `applied_to`.
- firewall_info - Add new `firewall_info` module to gather firewalls
info.
- firewall_resource - Add new `firewall_resource` module to manage
firewalls resources.

Fixes #111

##### ISSUE TYPE

- Feature Pull Request


##### COMPONENT NAME

firewall
firewall_info
firewall_resource

---------

Co-authored-by: Julian Tölle <julian.toelle97@gmail.com>

plugins/modules/firewall.py

@@ -175,6 +175,40 @@ hcloud_firewall:
                     elements: str
                     returned: always
                     sample: []
+        applied_to:
+            description: List of Resources the Firewall is applied to.
+            returned: always
+            type: list
+            elements: dict
+            contains:
+                type:
+                    description: Type of the resource.
+                    type: str
+                    choices: [server, label_selector]
+                    sample: label_selector
+                server:
+                    description: ID of the server.
+                    type: int
+                    sample: 12345
+                label_selector:
+                    description: Label selector value.
+                    type: str
+                    sample: env=prod
+                applied_to_resources:
+                    description: List of Resources the Firewall label selector is applied to.
+                    returned: if RV(hcloud_firewall.applied_to[].type=label_selector)
+                    type: list
+                    elements: dict
+                    contains:
+                        type:
+                            description: Type of resource referenced.
+                            type: str
+                            choices: [server]
+                            sample: server
+                        server:
+                            description: ID of the Server.
+                            type: int
+                            sample: 12345
 """
 
 import time
@@ -184,7 +218,11 @@ from ansible.module_utils.common.text.converters import to_native
 
 from ..module_utils.hcloud import AnsibleHCloud
 from ..module_utils.vendor.hcloud import APIException, HCloudException
-from ..module_utils.vendor.hcloud.firewalls import BoundFirewall, FirewallRule
+from ..module_utils.vendor.hcloud.firewalls import (
+    BoundFirewall,
+    FirewallResource,
+    FirewallRule,
+)
 
 
 class AnsibleHCloudFirewall(AnsibleHCloud):
@@ -198,11 +236,12 @@ class AnsibleHCloudFirewall(AnsibleHCloud):
             "name": to_native(self.hcloud_firewall.name),
             "rules": [self._prepare_result_rule(rule) for rule in self.hcloud_firewall.rules],
             "labels": self.hcloud_firewall.labels,
+            "applied_to": [self._prepare_result_applied_to(resource) for resource in self.hcloud_firewall.applied_to],
         }
 
-    def _prepare_result_rule(self, rule):
+    def _prepare_result_rule(self, rule: FirewallRule):
         return {
-            "direction": rule.direction,
+            "direction": to_native(rule.direction),
             "protocol": to_native(rule.protocol),
             "port": to_native(rule.port) if rule.port is not None else None,
             "source_ips": [to_native(cidr) for cidr in rule.source_ips],
@@ -210,6 +249,24 @@ class AnsibleHCloudFirewall(AnsibleHCloud):
             "description": to_native(rule.description) if rule.description is not None else None,
         }
 
+    def _prepare_result_applied_to(self, resource: FirewallResource):
+        result = {
+            "type": to_native(resource.type),
+            "server": to_native(resource.server.id) if resource.server is not None else None,
+            "label_selector": (
+                to_native(resource.label_selector.selector) if resource.label_selector is not None else None
+            ),
+        }
+        if resource.applied_to_resources is not None:
+            result["applied_to_resources"] = [
+                {
+                    "type": to_native(item.type),
+                    "server": to_native(item.server.id) if item.server is not None else None,
+                }
+                for item in resource.applied_to_resources
+            ]
+        return result
+
     def _get_firewall(self):
         try:
             if self.module.params.get("id") is not None:
@@ -239,11 +296,13 @@ class AnsibleHCloudFirewall(AnsibleHCloud):
                 )
                 for rule in rules
             ]
+
         if not self.module.check_mode:
             try:
                 self.client.firewalls.create(**params)
             except HCloudException as exception:
                 self.fail_json_hcloud(exception, params=params)
+
         self._mark_as_changed()
         self._get_firewall()
 
@@ -277,6 +336,7 @@ class AnsibleHCloudFirewall(AnsibleHCloud):
                 ]
                 self.hcloud_firewall.set_rules(new_rules)
             self._mark_as_changed()
+
         self._get_firewall()
 
     def present_firewall(self):

plugins/modules/firewall_info.py

@@ -0,0 +1,246 @@
+#!/usr/bin/python
+
+# Copyright: (c) 2019, Hetzner Cloud GmbH <info@hetzner-cloud.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+from __future__ import annotations
+
+DOCUMENTATION = """
+---
+module: firewall_info
+short_description: Gather infos about the Hetzner Cloud Firewalls.
+
+description:
+    - Gather facts about your Hetzner Cloud Firewalls.
+
+author:
+    - Jonas Lammler (@jooola)
+
+options:
+    id:
+        description:
+            - The ID of the Firewall you want to get.
+            - The module will fail if the provided ID is invalid.
+        type: int
+    name:
+        description:
+            - The name for the Firewall you want to get.
+        type: str
+    label_selector:
+        description:
+            - The label selector for the Firewalls you want to get.
+        type: str
+
+extends_documentation_fragment:
+    - hetzner.hcloud.hcloud
+"""
+
+EXAMPLES = """
+- name: Gather hcloud Firewall infos
+  hetzner.hcloud.firewall_info:
+  register: output
+
+- name: Print the gathered infos
+  debug:
+    var: output
+"""
+
+RETURN = """
+hcloud_firewall_info:
+    description: List of Firewalls.
+    returned: always
+    type: list
+    elements: dict
+    contains:
+        id:
+            description: Numeric identifier of the firewall.
+            returned: always
+            type: int
+            sample: 1937415
+        name:
+            description: Name of the firewall.
+            returned: always
+            type: str
+            sample: my-firewall
+        labels:
+            description: User-defined labels (key-value pairs).
+            returned: always
+            type: dict
+        rules:
+            description: List of rules the firewall contain.
+            returned: always
+            type: list
+            elements: dict
+            contains:
+                description:
+                    description: User defined description of this rule.
+                    type: str
+                    returned: always
+                    sample: allow http from anywhere
+                direction:
+                    description: The direction of the firewall rule.
+                    type: str
+                    returned: always
+                    sample: in
+                protocol:
+                    description: The protocol of the firewall rule.
+                    type: str
+                    returned: always
+                    sample: tcp
+                port:
+                    description: The port or port range allowed by this rule.
+                    type: str
+                    returned: if RV(hcloud_firewall_info[].rules[].protocol=tcp) or RV(hcloud_firewall_info[].rules[].protocol=udp)
+                    sample: "80"
+                source_ips:
+                    description: List of source CIDRs that are allowed within this rule.
+                    type: list
+                    elements: str
+                    returned: always
+                    sample: ["0.0.0.0/0", "::/0"]
+                destination_ips:
+                    description: List of destination CIDRs that are allowed within this rule.
+                    type: list
+                    elements: str
+                    returned: always
+                    sample: []
+        applied_to:
+            description: List of Resources the Firewall is applied to.
+            returned: always
+            type: list
+            elements: dict
+            contains:
+                type:
+                    description: Type of the resource.
+                    type: str
+                    choices: [server, label_selector]
+                    sample: label_selector
+                server:
+                    description: ID of the server.
+                    type: int
+                    sample: 12345
+                label_selector:
+                    description: Label selector value.
+                    type: str
+                    sample: env=prod
+                applied_to_resources:
+                    description: List of Resources the Firewall label selector is applied to.
+                    returned: if RV(hcloud_firewall_info[].applied_to[].type=label_selector)
+                    type: list
+                    elements: dict
+                    contains:
+                        type:
+                            description: Type of resource referenced.
+                            type: str
+                            choices: [server]
+                            sample: server
+                        server:
+                            description: ID of the Server.
+                            type: int
+                            sample: 12345
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.common.text.converters import to_native
+
+from ..module_utils.hcloud import AnsibleHCloud
+from ..module_utils.vendor.hcloud import HCloudException
+from ..module_utils.vendor.hcloud.firewalls import (
+    BoundFirewall,
+    FirewallResource,
+    FirewallRule,
+)
+
+
+class AnsibleHCloudFirewallInfo(AnsibleHCloud):
+    represent = "hcloud_firewall_info"
+
+    hcloud_firewall_info: list[BoundFirewall] | None = None
+
+    def _prepare_result(self):
+        tmp = []
+
+        for firewall in self.hcloud_firewall_info:
+            if firewall is None:
+                continue
+
+            tmp.append(
+                {
+                    "id": to_native(firewall.id),
+                    "name": to_native(firewall.name),
+                    "labels": firewall.labels,
+                    "rules": [self._prepare_result_rule(rule) for rule in firewall.rules],
+                    "applied_to": [self._prepare_result_applied_to(resource) for resource in firewall.applied_to],
+                }
+            )
+
+        return tmp
+
+    def _prepare_result_rule(self, rule: FirewallRule):
+        return {
+            "description": to_native(rule.description) if rule.description is not None else None,
+            "direction": to_native(rule.direction),
+            "protocol": to_native(rule.protocol),
+            "port": to_native(rule.port) if rule.port is not None else None,
+            "source_ips": [to_native(cidr) for cidr in rule.source_ips],
+            "destination_ips": [to_native(cidr) for cidr in rule.destination_ips],
+        }
+
+    def _prepare_result_applied_to(self, resource: FirewallResource):
+        result = {
+            "type": to_native(resource.type),
+            "server": to_native(resource.server.id) if resource.server is not None else None,
+            "label_selector": (
+                to_native(resource.label_selector.selector) if resource.label_selector is not None else None
+            ),
+        }
+        if resource.applied_to_resources is not None:
+            result["applied_to_resources"] = [
+                {
+                    "type": to_native(item.type),
+                    "server": to_native(item.server.id) if item.server is not None else None,
+                }
+                for item in resource.applied_to_resources
+            ]
+        return result
+
+    def get_firewalls(self):
+        try:
+            if self.module.params.get("id") is not None:
+                self.hcloud_firewall_info = [self.client.firewalls.get_by_id(self.module.params.get("id"))]
+            elif self.module.params.get("name") is not None:
+                self.hcloud_firewall_info = [self.client.firewalls.get_by_name(self.module.params.get("name"))]
+            elif self.module.params.get("label_selector") is not None:
+                self.hcloud_firewall_info = self.client.firewalls.get_all(
+                    label_selector=self.module.params.get("label_selector")
+                )
+            else:
+                self.hcloud_firewall_info = self.client.firewalls.get_all()
+
+        except HCloudException as exception:
+            self.fail_json_hcloud(exception)
+
+    @classmethod
+    def define_module(cls):
+        return AnsibleModule(
+            argument_spec=dict(
+                id={"type": "int"},
+                name={"type": "str"},
+                label_selector={"type": "str"},
+                **super().base_module_arguments(),
+            ),
+            supports_check_mode=True,
+        )
+
+
+def main():
+    module = AnsibleHCloudFirewallInfo.define_module()
+    hcloud = AnsibleHCloudFirewallInfo(module)
+
+    hcloud.get_firewalls()
+    module.exit_json(**hcloud.get_result())
+
+
+if __name__ == "__main__":
+    main()

plugins/modules/firewall_resource.py

@@ -0,0 +1,243 @@
+#!/usr/bin/python
+
+# Copyright: (c) 2019, Hetzner Cloud GmbH <info@hetzner-cloud.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+from __future__ import annotations
+
+DOCUMENTATION = """
+---
+module: firewall_resource
+short_description: Manage Resources a Hetzner Cloud Firewall is applied to.
+
+description:
+    - Add and Remove Resources a Hetzner Cloud Firewall is applied to.
+
+author:
+    - Jonas Lammler (@jooola)
+
+version_added: 2.5.0
+options:
+    firewall:
+        description:
+            - Name or ID of the Hetzner Cloud Firewall.
+        type: str
+        required: true
+    servers:
+        description:
+            - List of Server Name or ID.
+        type: list
+        elements: str
+    label_selectors:
+        description:
+            - List of Label Selector.
+        type: list
+        elements: str
+    state:
+        description:
+            - State of the firewall resources.
+        default: present
+        choices: [absent, present]
+        type: str
+
+extends_documentation_fragment:
+    - hetzner.hcloud.hcloud
+"""
+
+EXAMPLES = """
+- name: Apply a firewall to a list of servers
+  hetzner.hcloud.firewall_resource:
+    name: my-firewall
+    servers:
+      - my-server
+      - 3456789
+    state: present
+
+- name: Remove a firewall from a list of servers
+  hetzner.hcloud.firewall_resource:
+    name: my-firewall
+    servers:
+      - my-server
+      - 3456789
+    state: absent
+
+- name: Apply a firewall to resources using label selectors
+  hetzner.hcloud.firewall_resource:
+    name: my-firewall
+    label_selectors:
+      - env=prod
+    state: present
+
+- name: Remove a firewall from resources using label selectors
+  hetzner.hcloud.firewall_resource:
+    name: my-firewall
+    label_selectors:
+      - env=prod
+    state: absent
+"""
+
+RETURN = """
+hcloud_firewall_resource:
+    description: The Resources a Hetzner Cloud Firewall is applied to.
+    returned: always
+    type: dict
+    contains:
+        firewall:
+            description:
+                - Name of the Hetzner Cloud Firewall.
+            type: str
+            sample: my-firewall
+        servers:
+            description:
+                - List of Server Name.
+            type: list
+            elements: str
+            sample: [my-server1, my-server2]
+        label_selectors:
+            description:
+                - List of Label Selector.
+            type: list
+            elements: str
+            sample: [env=prod]
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.common.text.converters import to_native
+
+from ..module_utils.hcloud import AnsibleHCloud
+from ..module_utils.vendor.hcloud import HCloudException
+from ..module_utils.vendor.hcloud.firewalls import (
+    BoundFirewall,
+    FirewallResource,
+    FirewallResourceLabelSelector,
+)
+from ..module_utils.vendor.hcloud.servers import BoundServer
+
+
+class AnsibleHCloudFirewallResource(AnsibleHCloud):
+    represent = "hcloud_firewall_resource"
+
+    hcloud_firewall_resource: BoundFirewall | None = None
+
+    def _prepare_result(self):
+        servers = []
+        label_selectors = []
+        for resource in self.hcloud_firewall_resource.applied_to:
+            if resource.type == FirewallResource.TYPE_SERVER:
+                servers.append(to_native(resource.server.name))
+            elif resource.type == FirewallResource.TYPE_LABEL_SELECTOR:
+                label_selectors.append(to_native(resource.label_selector.selector))
+
+        return {
+            "firewall": to_native(self.hcloud_firewall_resource.name),
+            "servers": servers,
+            "label_selectors": label_selectors,
+        }
+
+    def _get_firewall(self):
+        try:
+            self.hcloud_firewall_resource = self._client_get_by_name_or_id(
+                "firewalls",
+                self.module.params.get("firewall"),
+            )
+        except HCloudException as exception:
+            self.fail_json_hcloud(exception)
+
+    def _diff_firewall_resources(self, operator) -> list[FirewallResource]:
+        before = self._prepare_result()
+
+        resources: list[FirewallResource] = []
+
+        servers: list[str] | None = self.module.params.get("servers")
+        if servers:
+            for server_param in servers:
+                try:
+                    server: BoundServer = self._client_get_by_name_or_id("servers", server_param)
+                except HCloudException as exception:
+                    self.fail_json_hcloud(exception)
+
+                if operator(server.name, before["servers"]):
+                    resources.append(
+                        FirewallResource(
+                            type=FirewallResource.TYPE_SERVER,
+                            server=server,
+                        )
+                    )
+
+        label_selectors = self.module.params.get("label_selectors")
+        if label_selectors:
+            for label_selector in label_selectors:
+                if operator(label_selector, before["label_selectors"]):
+                    resources.append(
+                        FirewallResource(
+                            type=FirewallResource.TYPE_LABEL_SELECTOR,
+                            label_selector=FirewallResourceLabelSelector(selector=label_selector),
+                        )
+                    )
+
+        return resources
+
+    def present_firewall_resources(self):
+        self._get_firewall()
+        resources = self._diff_firewall_resources(
+            lambda to_add, before: to_add not in before,
+        )
+        if resources:
+            if not self.module.check_mode:
+                actions = self.hcloud_firewall_resource.apply_to_resources(resources=resources)
+                for action in actions:
+                    action.wait_until_finished()
+
+                self.hcloud_firewall_resource.reload()
+
+            self._mark_as_changed()
+
+    def absent_firewall_resources(self):
+        self._get_firewall()
+        resources = self._diff_firewall_resources(
+            lambda to_remove, before: to_remove in before,
+        )
+        if resources:
+            if not self.module.check_mode:
+                actions = self.hcloud_firewall_resource.remove_from_resources(resources=resources)
+                for action in actions:
+                    action.wait_until_finished()
+
+                self.hcloud_firewall_resource.reload()
+
+            self._mark_as_changed()
+
+    @classmethod
+    def define_module(cls):
+        return AnsibleModule(
+            argument_spec={
+                "firewall": {"type": "str", "required": True},
+                "servers": {"type": "list", "elements": "str"},
+                "label_selectors": {"type": "list", "elements": "str"},
+                "state": {
+                    "choices": ["absent", "present"],
+                    "default": "present",
+                },
+                **super().base_module_arguments(),
+            },
+            required_one_of=[["servers", "label_selectors"]],
+            supports_check_mode=True,
+        )
+
+
+def main():
+    module = AnsibleHCloudFirewallResource.define_module()
+
+    hcloud = AnsibleHCloudFirewallResource(module)
+    state = module.params.get("state")
+    if state == "absent":
+        hcloud.absent_firewall_resources()
+    elif state == "present":
+        hcloud.present_firewall_resources()
+
+    module.exit_json(**hcloud.get_result())
+
+
+if __name__ == "__main__":
+    main()