chore(ansible): improve article and examples for aws ssm integration

examples/ansible/aws_ec2.yml

@@ -0,0 +1,26 @@
+---
+
+################################################################################
+## aws_ec2.yml
+##
+## Dynamic inventory for integration with AWS SSM.
+## Makes use of the 'aws_ec2' plugin.
+## The file must be named 'aws_ec2.yml'.
+################################################################################
+
+plugin: aws_ec2
+regions:
+  - eu-east-2
+keyed_groups:
+  - key: tags.Name
+    # add hosts to 'tag_Name_<tag_value>' groups for each aws_ec2 host's 'Tags.Name' attribute
+    prefix: tag_Name_
+    separator: ""
+  - key: tags.application
+    # add hosts to 'tag_application_<tag_value>' groups for each aws_ec2 host's 'Tags.application' attribute
+    prefix: tag_application_
+    separator: ""
+hostnames:
+  - instance-id
+    # acts as keyword to use the instances' 'InstanceId' attribute
+    # use 'private-ip-address' to use the instances' 'PrivateIpAddress' attribute instead

knowledge base/ansible.md

@@ -572,7 +572,7 @@ Conversely, one can achieve the opposite by using the `always` tag and the `--sk
 
 Message example:
 
-> fatal: [i-4ccab452bb7743336]: UNREACHABLE! => {"changed": false, "msg": "Failed to create temporary directory. In some cases, you may have been able to authenticate and did not have permissions on the target directory. Consider changing the remote tmp path in ansible.cfg to a path rooted in \"/tmp\", for more error information use -vvv. Failed command was: ( umask 77 && mkdir -p \"` echo \u001b]0;@ip-192-168-42-42:/usr/bin\u0007/home/centos/.ansible/tmp `\"&& mkdir \"` echo \u001b]0;@ip-192-168-42-42:/usr/bin\u0007/home/centos/.ansible/tmp/ansible-tmp-1708603630.2433128-49665-225488680421418 `\" && echo ansible-tmp-1708603630.2433128-49665-225488680421418=\"` echo \u001b]0;@ip-192-168-42-42:/usr/bin\u0007/home/centos/.ansible/tmp/ansible-tmp-1708603630.2433128-49665-225488680421418 `\" ), exited with result 1, stdout output: \u001b]0;@ip-192-168-42-42:/usr/bin\u0007bash: @ip-192-168-42-42:/usr/bin/home/centos/.ansible/tmp: No such file or directory\r\r\nmkdir: cannot create directory '0': Permission denied\r\r", "unreachable": true}
+> fatal: \[i-4ccab452bb7743336]: UNREACHABLE! => {"changed": false, "msg": "Failed to create temporary directory. In some cases, you may have been able to authenticate and did not have permissions on the target directory. Consider changing the remote tmp path in ansible.cfg to a path rooted in \"/tmp\", for more error information use -vvv. Failed command was: ( umask 77 && mkdir -p \"` echo \u001b]0;@ip-192-168-42-42:/usr/bin\u0007/home/centos/.ansible/tmp `\"&& mkdir \"` echo \u001b]0;@ip-192-168-42-42:/usr/bin\u0007/home/centos/.ansible/tmp/ansible-tmp-1708603630.2433128-49665-225488680421418 `\" && echo ansible-tmp-1708603630.2433128-49665-225488680421418=\"` echo \u001b]0;@ip-192-168-42-42:/usr/bin\u0007/home/centos/.ansible/tmp/ansible-tmp-1708603630.2433128-49665-225488680421418 `\" ), exited with result 1, stdout output: \u001b]0;@ip-192-168-42-42:/usr/bin\u0007bash: @ip-192-168-42-42:/usr/bin/home/centos/.ansible/tmp: No such file or directory\r\r\nmkdir: cannot create directory '0': Permission denied\r\r", "unreachable": true}
 
 Root cause:
 
@@ -581,7 +581,7 @@ By default, SSM starts sessions in the `/usr/bin` directory.
 Solution:
 
 Explicitly set Ansible's temporary directory to a folder the remote user can write to.<br/>
-See [Integration with AWS SSM].
+See [Integrate with AWS SSM].
 
 ## Further readings
 
@@ -600,7 +600,7 @@ See [Integration with AWS SSM].
 - [Ansible Galaxy user guide]
 - [Windows playbook example]
 - [Special tags: `always` and `never`][special tags: always and never]
-- [Integration with AWS SSM]
+- [Integrate with AWS SSM]
 
 ### Sources
 
@@ -627,7 +627,7 @@ See [Integration with AWS SSM].
   -->
 
 <!-- Knowledge base -->
-[integration with aws ssm]: cloud%20computing/aws/ssm.md##integrate-with-ansible
+[integrate with aws ssm]: cloud%20computing/aws/ssm.md#integrate-with-ansible
 
 <!-- Files -->
 [examples]: ../examples/ansible/
@@ -645,6 +645,7 @@ See [Integration with AWS SSM].
 [special variables]: https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html
 [templating]: https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html
 [tests]: https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html
+[slurp]: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/slurp_module.html
 
 <!-- Others -->
 [ansible: set variable to file content]: https://stackoverflow.com/questions/24003880/ansible-set-variable-to-file-content

knowledge base/cloud computing/aws/ssm.md

@@ -44,20 +44,20 @@ It needs to be named like that to be found by the ['community.aws.aws_ssm' conne
 # File: 'aws_ec2.yml'.
 plugin: aws_ec2
 regions:
-  - eu-west-1
+  - eu-east-2
 keyed_groups:
-  - key: tags.application
-    # add hosts to tag_application_<tag_value> groups for each aws_ec2 host's
-    # tags.application attribute
-    prefix: tag_application_
-    separator: ""
   - key: tags.Name
-    # add hosts to tag_Name_<tag_value> groups for each aws_ec2 host's tags.Name
+    # add hosts to 'tag_Name_<tag_value>' groups for each aws_ec2 host's 'Tags.Name' attribute
-    # attribute
     prefix: tag_Name_
     separator: ""
+  - key: tags.application
+    # add hosts to 'tag_application_<tag_value>' groups for each aws_ec2 host's 'Tags.application' attribute
+    prefix: tag_application_
+    separator: ""
 hostnames:
-  - <instance-id>
+  - instance-id
+    # acts as keyword to use the instances' 'InstanceId' attribute
+    # use 'private-ip-address' to use the instances' 'PrivateIpAddress' attribute instead
 ```
 
 Pitfalls:
@@ -65,9 +65,13 @@ Pitfalls:
 - One **shall not use the `remote_user` connection option**, as it is not supported by the plugin.<br/>
   From the [plugin notes][aws_ssm connection plugin notes]:
 
-  > The `community.aws.aws_ssm` connection plugin does not support using the `remote_user` and `ansible_user` variables to configure the remote user.  The ``become_user`` parameter should be used to configure which user to run commands as. Remote commands will often default to running as the `ssm-agent` user, however this will also depend on how SSM has been configured.
+  > The `community.aws.aws_ssm` connection plugin does not support using the `remote_user` and `ansible_user` variables
+  > to configure the remote user.  The ``become_user`` parameter should be used to configure which user to run commands
+  > as. Remote commands will often default to running as the `ssm-agent` user, however this will also depend on how SSM
+  > has been configured.
 
-- Since [SSM starts shell sessions under `/usr/bin`][gotchas], one must explicitly set Ansible's temporary directory to a folder the remote user can write to ([source][ansible temp dir change]):
+- Since [SSM starts shell sessions under `/usr/bin`][gotchas], one must explicitly set Ansible's temporary directory to
+  a folder the remote user can write to ([source][ansible temp dir change]):
 
   ```sh
   ANSIBLE_REMOTE_TMP='/tmp' ansible…
@@ -85,6 +89,9 @@ Pitfalls:
      tasks: …
   ```
 
+  This, or use the shell profiles in [SSM's preferences][session manager preferences] to change the directory when
+  logged in.
+
 ## Further readings
 
 - [Ansible]
@@ -110,8 +117,9 @@ Pitfalls:
 
 <!-- Upstream -->
 [start a session]: https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html
-[session manager preferences]: https://eu-west-1.console.aws.amazon.com/systems-manager/session-manager/preferences?region=eu-west-1
+[session manager preferences]: https://console.aws.amazon.com/systems-manager/session-manager/preferences
 [aws_ssm connection plugin notes]: https://docs.ansible.com/ansible/latest/collections/community/aws/aws_ssm_connection.html#notes
+[community.aws.aws_ssm connection]: https://docs.ansible.com/ansible/latest/collections/community/aws/aws_ssm_connection.html
 
 <!-- Others -->
 [ansible temp dir change]: https://devops.stackexchange.com/questions/10703/ansible-temp-dir-change