Repository: ansible-collections/amazon.aws

Issue:
Poor documentation for from_port, to_port in ec2_groups
The documentation for specifying port ranges in security groups is confusing.

* No given example of actual ranges, only one individual port per security group.
* No given example of allowing ALL ports.
* Documentation says to use -1 to indicate no bound. But when you actually try to use -1 in `from_port` and/or `to_port`, then you will get errors running your playbook.

As a workaround, you can specify 0, 65535 as the port range bounds.


Discussion:
Files identified in the description:
None

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
@mcandre: Greetings! Thanks for taking the time to open this issue. In order for the community to handle your issue effectively, we need a bit more information.

Here are the items we could not find in your description:
- issue type
- ansible version
- component name

Please set the description of this issue with this template:
https://raw.githubusercontent.com/ansible/ansible/devel/.github/ISSUE_TEMPLATE/bug_report.md

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: issue_missing_data --->
`-1` value in parameter `from_port` and `to_port` is only supported for `proto: icmp`.  

> * FromPort (integer) --
>
> The start of port range for the TCP and UDP protocols, or an ICMP/ICMPv6 type number. A value of -1 indicates all ICMP/ICMPv6 types. If you specify all ICMP/ICMPv6 types, you must specify all codes.

That's a missing part in the module documentation.  So yes. for all other proto values, you must specify `0-65535`.  
Alternativley, you also can specify `proto: all`, which allows the entire traffic to/from the target.

> No given example of actual ranges, only one individual port per security group.

There is an example with multipl ports and ranges.
https://github.com/ansible-collections/amazon.aws/blob/main/plugins/modules/ec2_group.py#L303



```yml
    - name: mb
      ec2_group:
        name: mbtest01
        description: mb test 01
        region: eu-central-1
        state: present
        vpc_id: "{{ VPC }}"
        purge_rules_egress : True
        purge_rules: True
        rules:
          - proto: tcp
            ports: 0-65535
            cidr_ip: 10.0.0.0/8
            rule_desc: all port ranges in tcp
          - proto: icmp
            from_port: -1
            to_port: -1
            cidr_ip: 10.0.0.0/8
            rule_desc: only available for icmp
          - proto: all
            cidr_ip:  "{{ lookup('dig', 'osuv.de') }}/32"
            rule_desc: all from osuv.de
        rules_egress: []
```
Hi @mcandre, thank you for reporting this issue. Would you be willing to open a PR to address this issue? Thank you.

Resolving patch:
diff --git a/plugins/modules/ec2_group.py b/plugins/modules/ec2_group.py
--- a/plugins/modules/ec2_group.py
+++ b/plugins/modules/ec2_group.py
@@ -95,10 +95,16 @@
             - The IP protocol name (C(tcp), C(udp), C(icmp), C(icmpv6)) or number (U(https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers))
         from_port:
             type: int
-            description: The start of the range of ports that traffic is coming from.  A value of C(-1) indicates all ports.
+            description:
+            - The start of the range of ports that traffic is coming from.
+            - A value can be between C(0) to C(65535).
+            - A value of C(-1) indicates all ports (only supported when I(proto=icmp)).
         to_port:
             type: int
-            description: The end of the range of ports that traffic is coming from.  A value of C(-1) indicates all ports.
+            description:
+            - The end of the range of ports that traffic is coming from.
+            - A value can be between C(0) to C(65535).
+            - A value of C(-1) indicates all ports (only supported when I(proto=icmp)).
         rule_desc:
             type: str
             description: A description for the rule.
@@ -156,10 +162,16 @@
             - The IP protocol name (C(tcp), C(udp), C(icmp), C(icmpv6)) or number (U(https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers))
         from_port:
             type: int
-            description: The start of the range of ports that traffic is going to.  A value of C(-1) indicates all ports.
+            description:
+            - The start of the range of ports that traffic is going to.
+            - A value can be between C(0) to C(65535).
+            - A value of C(-1) indicates all ports (only supported when I(proto=icmp)).
         to_port:
             type: int
-            description: The end of the range of ports that traffic is going to.  A value of C(-1) indicates all ports.
+            description:
+            - The end of the range of ports that traffic is going to.
+            - A value can be between C(0) to C(65535).
+            - A value of C(-1) indicates all ports (only supported when I(proto=icmp)).
         rule_desc:
             type: str
             description: A description for the rule.
@@ -269,7 +281,7 @@
         # the containing group name may be specified here
         group_name: example
       - proto: all
-        # in the 'proto' attribute, if you specify -1, all, or a protocol number other than tcp, udp, icmp, or 58 (ICMPv6),
+        # in the 'proto' attribute, if you specify -1 (only supported when I(proto=icmp)), all, or a protocol number other than tcp, udp, icmp, or 58 (ICMPv6),
         # traffic on all ports is allowed, regardless of any ports you specify
         from_port: 10050 # this value is ignored
         to_port: 10050 # this value is ignored


Test patch: