Repository: ansible-collections/amazon.aws

Issue:
Documentation for "groups" in aws_ec2.py module
### Summary

The module does not have any examples of how to use `groups`. I think this is what I would use to add all items from a specific inventory configuration to a dynamic group for use in playbooks.

### Issue Type

Documentation Report

### Component Name

aws_ec2.py

### Ansible Version

```console (paste below)
ansible 2.9.22
  config file = /Users/tmisilo/ansible-master/ansible.cfg
  configured module search path = ['/Users/tmisilo/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /Users/tmisilo/ansible/lib/python3.9/site-packages/ansible
  executable location = /Users/tmisilo/ansible/bin/ansible
  python version = 3.9.4 (default, Apr  5 2021, 01:50:46) [Clang 12.0.0 (clang-1200.0.32.29)]

```


### Collection Versions

```console (paste below)
usage: ansible-galaxy collection [-h] COLLECTION_ACTION ...
ansible-galaxy collection: error: argument COLLECTION_ACTION: invalid choice: 'list' (choose from 'init', 'build', 'publish', 'install')
```


### Configuration

```console (paste below)
$ ansible-config dump --only-changed

```


### OS / Environment

_No response_

### Additional Information

_No response_

### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct


Discussion:
Files identified in the description:
* [`plugins/inventory/aws_ec2.py`](https://github.com/['ansible-collections/amazon.aws', 'ansible-collections/community.aws', 'ansible-collections/community.vmware']/blob/main/plugins/inventory/aws_ec2.py)

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 --->
Hi @misilot. What does your plugin config look like, and what result are you getting that is different than what you expect?
```yml
plugin: aws_ec2
regions:
   - us-east-1
boto_profile: lib
filters:
   instance-state-name: running
keyed_groups:
  - prefix: tag
    key: tags
hostnames:
  - tag:Name
  - tag:CustomDNSName
  - dns-name
  - public_dns_name
  - private-ip-address
compose:
   ansible_host: public_dns_name
```

Is what I have so far, my results are I guess I am not sure where to start with the `groups` option? I think I have something working by adding

```yml
groups:
  libvpc: vpc_id == 'vpc-####'
```

But really I wasn't sure what I should even be putting in there. Someone on IRC mentioned that I should be able to use any of the data available from the instance, but really I was just blindly guessing, but this seems to work. I can at least try and add a little to the README file that includes this example so there is some context of what might be able to be done with it.

Resolving patch:
diff --git a/plugins/inventory/aws_ec2.py b/plugins/inventory/aws_ec2.py
--- a/plugins/inventory/aws_ec2.py
+++ b/plugins/inventory/aws_ec2.py
@@ -188,6 +188,23 @@
 exclude_filters:
 - tag:Name:
   - 'my_first_tag'
+
+# Example using groups to assign the running hosts to a group based on vpc_id
+plugin: aws_ec2
+boto_profile: aws_profile
+# Populate inventory with instances in these regions
+regions:
+  - us-east-2
+filters:
+  # All instances with their state as `running`
+  instance-state-name: running
+keyed_groups:
+  - prefix: tag
+    key: tags
+compose:
+  ansible_host: public_dns_name
+groups:
+  libvpc: vpc_id == 'vpc-####'
 '''
 
 import re


Test patch: