From 294973785a212264c39b27b6d8f7311363d7aba7 Mon Sep 17 00:00:00 2001 From: jo Date: Tue, 19 Dec 2023 19:46:35 +0100 Subject: [PATCH] docs: improve firewall module docs --- plugins/modules/firewall.py | 113 +++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 52 deletions(-) diff --git a/plugins/modules/firewall.py b/plugins/modules/firewall.py index 2a626604..ef72e832 100644 --- a/plugins/modules/firewall.py +++ b/plugins/modules/firewall.py @@ -9,10 +9,8 @@ DOCUMENTATION = """ --- module: firewall - short_description: Create and manage firewalls on the Hetzner Cloud. - description: - Create, update and manage firewalls on the Hetzner Cloud. @@ -22,62 +20,69 @@ options: id: description: - - The ID of the Hetzner Cloud firewall to manage. - - Only required if no firewall I(name) is given + - The ID of the Hetzner Cloud Firewall to manage. + - Only required if no firewall O(name) is given. type: int name: description: - - The Name of the Hetzner Cloud firewall to manage. - - Only required if no firewall I(id) is given, or a firewall does not exist. + - The Name of the Hetzner Cloud Firewall to manage. + - Only required if no firewall O(id) is given, or the firewall does not exist. type: str labels: description: - - User-defined labels (key-value pairs) + - User-defined labels (key-value pairs). type: dict rules: description: - - List of rules the firewall should contain. + - List of rules the firewall contain. type: list elements: dict suboptions: - direction: + description: description: - - The direction of the firewall rule. + - User defined description of this rule. type: str - choices: [ in, out ] - port: + direction: description: - - The port of the firewall rule. + - The direction of the firewall rule. type: str + choices: [in, out] protocol: description: - The protocol of the firewall rule. type: str - choices: [ icmp, tcp, udp, esp, gre ] + choices: [icmp, tcp, udp, esp, gre] + port: + description: + - The port or port range allowed by this rule. + - A port range can be specified by separating two ports with a dash, e.g 1024-5000. + - Only used if O(protocol=tcp) or O(protocol=udp). + type: str source_ips: description: - - List of CIDRs that are allowed within this rule + - List of CIDRs that are allowed within this rule. + - Use 0.0.0.0/0 to allow all IPv4 addresses and ::/0 to allow all IPv6 addresses. + - Only used if O(direction=in). type: list elements: str - default: [ ] + default: [] destination_ips: description: - - List of CIDRs that are allowed within this rule + - List of CIDRs that are allowed within this rule. + - Use 0.0.0.0/0 to allow all IPv4 addresses and ::/0 to allow all IPv6 addresses. + - Only used if O(direction=out). type: list elements: str - default: [ ] - description: - description: - - User defined description of this rule. - type: str + default: [] state: description: - State of the firewall. default: present - choices: [ absent, present ] + choices: [absent, present] type: str + extends_documentation_fragment: -- hetzner.hcloud.hcloud + - hetzner.hcloud.hcloud """ EXAMPLES = """ @@ -90,12 +95,12 @@ hetzner.hcloud.firewall: name: my-firewall rules: - - direction: in + - description: allow icmp from everywhere + direction: in protocol: icmp source_ips: - 0.0.0.0/0 - ::/0 - description: allow icmp in state: present - name: Create a firewall with labels @@ -114,58 +119,62 @@ RETURN = """ hcloud_firewall: - description: The firewall instance - returned: Always - type: complex + description: The firewall instance. + returned: always + type: dict contains: id: - description: Numeric identifier of the firewall + description: Numeric identifier of the firewall. returned: always type: int sample: 1937415 name: - description: Name of the firewall + description: Name of the firewall. returned: always type: str - sample: my firewall + sample: my-firewall + labels: + description: User-defined labels (key-value pairs). + returned: always + type: dict rules: - description: List of Rules within this Firewall + description: List of rules the firewall contain. returned: always - type: complex + type: list + elements: dict contains: + description: + description: User defined description of this rule. + type: str + returned: always + sample: allow http from anywhere direction: - description: Direction of the Firewall Rule + description: The direction of the firewall rule. type: str returned: always sample: in protocol: - description: Protocol of the Firewall Rule + description: The protocol of the firewall rule. type: str returned: always - sample: icmp + sample: tcp port: - description: Port of the Firewall Rule, None/Null if protocol is icmp + description: The port or port range allowed by this rule. type: str - returned: always - sample: in + returned: if RV(protocol=tcp) or RV(protocol=udp) + sample: "80" source_ips: - description: Source IPs of the Firewall + 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: Source IPs of the Firewall + description: List of destination CIDRs that are allowed within this rule. type: list elements: str returned: always - description: - description: User defined description of the Firewall Rule - type: str - returned: always - labels: - description: User-defined labels (key-value pairs) - returned: always - type: dict + sample: [] """ import time @@ -303,16 +312,17 @@ def define_module(cls): argument_spec=dict( id={"type": "int"}, name={"type": "str"}, + labels={"type": "dict"}, rules=dict( type="list", elements="dict", options=dict( + description={"type": "str"}, direction={"type": "str", "choices": ["in", "out"]}, protocol={"type": "str", "choices": ["icmp", "udp", "tcp", "esp", "gre"]}, port={"type": "str"}, source_ips={"type": "list", "elements": "str", "default": []}, destination_ips={"type": "list", "elements": "str", "default": []}, - description={"type": "str"}, ), required_together=[["direction", "protocol"]], required_if=[ @@ -320,7 +330,6 @@ def define_module(cls): ["protocol", "tcp", ["port"]], ], ), - labels={"type": "dict"}, state={ "choices": ["absent", "present"], "default": "present",