new: Return firewalls from nodebalancer and nodebalancer_info modules (…

…#460)

* Return firewalls from nodebalancer and nodebalancer_info modules

* Update wording

README.md

@@ -133,9 +133,11 @@ The Python module dependencies are not installed by `ansible-galaxy`.  They can
 be manually installed using pip:
 
 ```shell
-pip install -r https://raw.githubusercontent.com/linode/ansible_linode/main/requirements.txt
+pip install --upgrade -r https://raw.githubusercontent.com/linode/ansible_linode/main/requirements.txt
 ```
 
+> :warning: **NOTE:** Python dependencies should always be reinstalled when upgrading collection versions
+
 ## Usage
 Once the Linode Ansible collection is installed, it can be referenced by its [Fully Qualified Collection Namespace (FQCN)](https://github.com/ansible-collections/overview#terminology): `linode.cloud.module_name`.
 

docs/modules/nodebalancer.md

@@ -160,3 +160,15 @@ Manage a Linode NodeBalancer.
     - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view) for a list of returned fields
 
 
+- `firewalls` - A list IDs for firewalls attached to this NodeBalancer.
+
+    - Sample Response:
+        ```json
+        [
+          1234,
+          5678
+        ]
+        ```
+    - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#firewalls-list) for a list of returned fields
+
+

docs/modules/nodebalancer_info.md

@@ -113,3 +113,15 @@ Get info about a Linode NodeBalancer.
     - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view) for a list of returned fields
 
 
+- `firewalls` - A list IDs for firewalls attached to this NodeBalancer.
+
+    - Sample Response:
+        ```json
+        [
+          1234,
+          5678
+        ]
+        ```
+    - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#firewalls-list) for a list of returned fields
+
+

plugins/module_utils/doc_fragments/nodebalancer.py

@@ -81,3 +81,8 @@
     "weight": 50
   }
 ]''']
+
+result_firewalls_samples = ['''[
+  1234,
+  5678
+]''']

plugins/modules/nodebalancer.py

@@ -289,6 +289,13 @@
             type=FieldType.list,
             sample=docs.result_nodes_samples,
         ),
+        "firewalls": SpecReturnValue(
+            description="A list IDs for firewalls attached to this NodeBalancer.",
+            docs_url="https://www.linode.com/docs/api/nodebalancers/#firewalls-list",
+            type=FieldType.list,
+            elements=FieldType.integer,
+            sample=docs.result_firewalls_samples,
+        ),
     },
 )
 
@@ -307,6 +314,7 @@ def __init__(self) -> None:
             "node_balancer": None,
             "configs": [],
             "nodes": [],
+            "firewalls": [],
         }
 
         self._node_balancer: Optional[NodeBalancer] = None
@@ -617,6 +625,13 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]:
                 node._api_get()
                 cast(list, self.results["nodes"]).append(node._raw_json)
 
+        # NOTE: Only the Firewall IDs are used here to reduce the
+        # number of API requests made by this module and to simplify
+        # the module result.
+        self.results["firewalls"] = [
+            v.id for v in self._node_balancer.firewalls()
+        ]
+
         return self.results
 
 

plugins/modules/nodebalancer_info.py

@@ -79,6 +79,13 @@
             type=FieldType.list,
             sample=docs_parent.result_nodes_samples,
         ),
+        "firewalls": SpecReturnValue(
+            description="A list IDs for firewalls attached to this NodeBalancer.",
+            docs_url="https://www.linode.com/docs/api/nodebalancers/#firewalls-list",
+            type=FieldType.list,
+            elements=FieldType.integer,
+            sample=docs_parent.result_firewalls_samples,
+        ),
     },
 )
 
@@ -91,7 +98,12 @@ class LinodeNodeBalancerInfo(LinodeModuleBase):
     def __init__(self) -> None:
         self.module_arg_spec = SPECDOC_META.ansible_spec
         self.required_one_of: List[str] = []
-        self.results: dict = {"node_balancer": None, "configs": [], "nodes": []}
+        self.results: dict = {
+            "node_balancer": None,
+            "configs": [],
+            "nodes": [],
+            "firewalls": [],
+        }
 
         super().__init__(
             module_arg_spec=self.module_arg_spec,
@@ -155,6 +167,11 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]:
 
                 self.results["nodes"].append(node._raw_json)
 
+        # NOTE: Only the Firewall IDs are used here to reduce the
+        # number of API requests made by this module and to simplify
+        # the module result.
+        self.results["firewalls"] = [v.id for v in node_balancer.firewalls()]
+
         return self.results
 
 

template/README.template.md

@@ -65,9 +65,11 @@ The Python module dependencies are not installed by `ansible-galaxy`.  They can
 be manually installed using pip:
 
 ```shell
-pip install -r https://raw.githubusercontent.com/linode/ansible_linode/{{collection_version}}/requirements.txt
+pip install --upgrade -r https://raw.githubusercontent.com/linode/ansible_linode/{{collection_version}}/requirements.txt
 ```
 
+> :warning: **NOTE:** Python dependencies should always be reinstalled when upgrading collection versions
+
 ## Usage
 Once the Linode Ansible collection is installed, it can be referenced by its [Fully Qualified Collection Namespace (FQCN)](https://github.com/ansible-collections/overview#terminology): `linode.cloud.module_name`.
 

tests/integration/targets/nodebalancer_firewall/tasks/main.yaml

@@ -29,6 +29,19 @@
         that:
           - nodebalancer.changed
           - nodebalancer.configs|length == 0
+          - nodebalancer.firewalls|length == 1
+          - nodebalancer.firewalls[0] == firewall.firewall.id
+
+    - name: Get info about the NodeBalancer
+      linode.cloud.nodebalancer_info:
+        id: '{{ nodebalancer.node_balancer.id }}'
+      register: nodebalancer_info
+
+    - name: Ensure the attached firewalls are returned
+      assert:
+        that:
+          - nodebalancer_info.firewalls|length == 1
+          - nodebalancer_info.firewalls[0] == firewall.firewall.id
 
   always:
     - ignore_errors: yes