Repository: ansible-collections/amazon.aws

Issue:
Explain what use_ssm_inventory in ec2 inventory plugin does
### Summary

I'm trying to combine both the ec2 inventory plugin, and the SSM connector plugin. I'm really struggling to figure out how to do this, because of several documentation issues. But I'll just mention one here.

In the inventory plugin, there's an option called "use_ssm_inventory". The description is very brief. "Add SSM inventory information into hostvars.". I assumed this means that if I set it to True, then the SSM plugin will just work. But this doesn't seem to be the case.

Looking at the boto3 docs, I see that SSM also uses the term "inventory", which may have a different meaning to Ansible inventory. The documentation should be updated to explain what the word "inventory" means in the context of this specific argument.

### Issue Type

Documentation Report

### Component Name

aws_ec2 inventory

### Ansible Version

```console (paste below)
$ ansible --version
ansible [core 2.14.4]
  config file = /Users/matthew/Documents/mms/new-repo/ansible.cfg
  configured module search path = ['/Users/matthew/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /Users/matthew/.pyenv/versions/3.10.0/lib/python3.10/site-packages/ansible
  ansible collection location = /Users/matthew/.ansible/collections:/usr/share/ansible/collections
  executable location = /Users/matthew/.pyenv/versions/3.10.0/bin/ansible
  python version = 3.10.0 (default, Nov 12 2021, 11:20:43) [Clang 12.0.5 (clang-1205.0.22.11)] (/Users/matthew/.pyenv/versions/3.10.0/bin/python3.10)
  jinja version = 3.1.2
  libyaml = False
```


### Collection Versions

```console (paste below)
$ ansible-galaxy collection list
# /Users/matthew/.pyenv/versions/3.10.0/lib/python3.10/site-packages/ansible_collections
Collection                    Version
----------------------------- -------
amazon.aws                    5.4.0  
ansible.netcommon             4.1.0  
ansible.posix                 1.5.1  
ansible.utils                 2.9.0  
ansible.windows               1.13.0 
arista.eos                    6.0.0  
awx.awx                       21.14.0
azure.azcollection            1.15.0 
check_point.mgmt              4.0.0  
chocolatey.chocolatey         1.4.0  
cisco.aci                     2.4.0  
cisco.asa                     4.0.0  
cisco.dnac                    6.6.4  
cisco.intersight              1.0.24 
cisco.ios                     4.4.0  
cisco.iosxr                   4.1.0  
cisco.ise                     2.5.12 
cisco.meraki                  2.15.1 
cisco.mso                     2.2.1  
cisco.nso                     1.0.3  
cisco.nxos                    4.1.0  
cisco.ucs                     1.8.0  
cloud.common                  2.1.3  
cloudscale_ch.cloud           2.2.4  
community.aws                 5.4.0  
community.azure               2.0.0  
community.ciscosmb            1.0.5  
community.crypto              2.11.1 
community.digitalocean        1.23.0 
community.dns                 2.5.2  
community.docker              3.4.3  
community.fortios             1.0.0  
community.general             6.5.0  
community.google              1.0.0  
community.grafana             1.5.4  
community.hashi_vault         4.2.0  
community.hrobot              1.8.0  
community.libvirt             1.2.0  
community.mongodb             1.5.1  
community.mysql               3.6.0  
community.network             5.0.0  
community.okd                 2.3.0  
community.postgresql          2.3.2  
community.proxysql            1.5.1  
community.rabbitmq            1.2.3  
community.routeros            2.8.0  
community.sap                 1.0.0  
community.sap_libs            1.4.1  
community.skydive             1.0.0  
community.sops                1.6.1  
community.vmware              3.5.0  
community.windows             1.12.0 
community.zabbix              1.9.2  
containers.podman             1.10.1 
cyberark.conjur               1.2.0  
cyberark.pas                  1.0.17 
dellemc.enterprise_sonic      2.0.0  
dellemc.openmanage            6.3.0  
dellemc.os10                  1.1.1  
dellemc.os6                   1.0.7  
dellemc.os9                   1.0.4  
dellemc.powerflex             1.5.0  
dellemc.unity                 1.5.0  
f5networks.f5_modules         1.23.0 
fortinet.fortimanager         2.1.7  
fortinet.fortios              2.2.3  
frr.frr                       2.0.0  
gluster.gluster               1.0.2  
google.cloud                  1.1.3  
grafana.grafana               1.1.1  
hetzner.hcloud                1.10.0 
hpe.nimble                    1.1.4  
ibm.qradar                    2.1.0  
ibm.spectrum_virtualize       1.11.0 
infinidat.infinibox           1.3.12 
infoblox.nios_modules         1.4.1  
inspur.ispim                  1.3.0  
inspur.sm                     2.3.0  
junipernetworks.junos         4.1.0  
kubernetes.core               2.4.0  
lowlydba.sqlserver            1.3.1  
mellanox.onyx                 1.0.0  
netapp.aws                    21.7.0 
netapp.azure                  21.10.0
netapp.cloudmanager           21.22.0
netapp.elementsw              21.7.0 
netapp.ontap                  22.4.1 
netapp.storagegrid            21.11.1
netapp.um_info                21.8.0 
netapp_eseries.santricity     1.4.0  
netbox.netbox                 3.11.0 
ngine_io.cloudstack           2.3.0  
ngine_io.exoscale             1.0.0  
ngine_io.vultr                1.1.3  
openstack.cloud               1.10.0 
openvswitch.openvswitch       2.1.0  
ovirt.ovirt                   2.4.1  
purestorage.flasharray        1.17.2 
purestorage.flashblade        1.10.0 
purestorage.fusion            1.4.1  
sensu.sensu_go                1.13.2 
splunk.es                     2.1.0  
t_systems_mms.icinga_director 1.32.2 
theforeman.foreman            3.9.0  
vmware.vmware_rest            2.3.1  
vultr.cloud                   1.7.0  
vyos.vyos                     4.0.1  
wti.remote                    1.0.4 
```


### Configuration

```console (paste below)
$ ansible-config dump --only-changed
ANY_ERRORS_FATAL(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = True
CONFIG_FILE() = /Users/matthew/Documents/mms/new-repo/ansible.cfg
DEFAULT_GATHERING(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = explicit
DEFAULT_HOST_LIST(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = ['/Users/matthew/Documents/mms/new-repo/hosts']
DEFAULT_KEEP_REMOTE_FILES(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = True
DEFAULT_STDOUT_CALLBACK(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = yaml
INTERPRETER_PYTHON(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = auto_silent
INVENTORY_UNPARSED_IS_FAILED(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = True
LOCALHOST_WARNING(/Users/matthew/Documents/mms/new-repo/ansible.cfg) = False
```


### OS / Environment

Mac

### Additional Information

_No response_

### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct


Discussion:
@mdavis-xyz Thank you for raising this issue. I prepared a PR (https://github.com/ansible-collections/amazon.aws/pull/1586) that attempts to provide a more exhaustive explanation for the `use_ssm_inventory` option. Can you please have a look and let me know if it clarifies your concerns?

Yes thanks. That's more clear now.

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
@@ -137,7 +137,10 @@
     version_added: 3.1.0
   use_ssm_inventory:
     description:
-      - Add SSM inventory information into hostvars.
+      - Enables fetching additional EC2 instance information from the AWS Systems Manager (SSM) inventory service into hostvars.
+      - By leveraging the SSM inventory data, the I(use_ssm_inventory) option provides additional details and attributes
+        about the EC2 instances in your inventory. These details can include operating system information, installed software,
+        network configurations, and custom inventory attributes defined in SSM.
     type: bool
     default: False
     version_added: 6.0.0


Test patch: