amazon.aws
amazon.aws copied to clipboard
ansible-collections
aws_ec2 inventory - Filter examples do not quote the key values
Summary
Based on this reddit thread, it seems like the docs examples should be quoting the key values for filters but aren't.
Issue Type
Documentation Report
Component Name
aws_ec2_guide.rst
Ansible Version
$ ansible --version
unknown
Collection Versions
$ ansible-galaxy collection list
unknown
Configuration
$ ansible-config dump --only-changed
unknown
OS / Environment
unknown
Additional Information
No response
Code of Conduct
- [X] I agree to follow the Ansible Code of Conduct
Files identified in the description:
- [
docs/docsite/rst/aws_ec2_guide.rst](https://github.com/['ansible-collections/amazon.aws', 'ansible-collections/community.aws', 'ansible-collections/community.vmware']/blob/main/docs/docsite/rst/aws_ec2_guide.rst)
If these files are inaccurate, please update the component name section of the description or use the !component bot command.
Agree that we need some specific examples, however I want to make sure what's needed is correctly documented.
The docs as they stand do now include examples quoting the values, and they're not technically required (which is why it's not called out). Unfortunately, I see no sign that they actually came across the new documentation, and as such we may need the help of the Docs team to get them visible in the right places. Since the new docs use quotes, this might have given the original poster the hint they needed.
From the poster's initial comment it's not obvious that this is what's going on (they didn't post all of the filter), however once they post the solution you can see they are using the string yes.
The complicating factor here is actually that they're hitting a quirk of YAML (and Ansible's YAML parser), combined with how AWS handles tags.
(1) The value of all AWS tags are strings.
(2) The way that Ansible's YAML parser works the strings yes, no, true and false (upper case and lower case) results in these strings being converted into their boolean counterparts: True and False, unless we can explicitly tell it we wanted strings. Because the keys in the filter are free form, we don't have a way to explicitly tell the parser that the values are strings, and as such have to rely on the YAML parser's default behaviour. As such, all we can do is convert these back to the strings "True" and "False" which of course won't match the strings "yes" and "no" (the filtering is handled by AWS we can't try to work around this)
Thanks @tremble . From the docs perspective, things get a bit tricky since this is a customer using AAP, and some versions of AAP (maybe all?) can support plugins etc all the way back to ansible 2.9. so yeah, not sure which examples were originally looked at.
This is the current docs for this on docs.ansible.com - https://docs.ansible.com/ansible/latest/collections/amazon/aws/docsite/aws_ec2_guide.html#filters
It seems to be the same as what is on devel, so reflects the most recent collection version released on galaxy.
as for the YAML gotcha - is it worth adding a note on that page somewhere that says something like "quotes are not required except for when representing boolean values (yes/no)." ?
@samccann
Ah, I just noticed that include_ / exclude_ filters examples use quotes, but the simple filters docs don't.
As for the YAML gotcha. Yeah, probabably worth specifically having a "yes" example in there.