chore(ansible): dump newly discovered information

knowledge base/README.md

@@ -19,6 +19,9 @@ This is the collection of all notes, reminders and whatnot I gathered during the
     #!/usr/bin/env zsh
   ```
 
+- Prefer **GitHub**'s markdown flavour where multiple are available.<br/>
+  Just because GitHub seems to be the place most people will look at this repository.
+
 - Group related options in commands where possible.<br/>
   It gives enhanced clarity and a sense of continuation.
 

knowledge base/awx.md

@@ -1,12 +1,13 @@
 # Ansible AWX
 
 1. [Gotchas](#gotchas)
-1. [Instance setup](#instance-setup)
+1. [Setup](#setup)
    1. [Deployment](#deployment)
    1. [Update](#update)
    1. [Removal](#removal)
    1. [Testing](#testing)
-1. [Jobs execution](#jobs-execution)
+   1. [Job execution](#job-execution)
+1. [Job templates](#job-templates)
 1. [Workflow automation](#workflow-automation)
    1. [Pass data between workflow nodes](#pass-data-between-workflow-nodes)
 1. [API](#api)
@@ -84,7 +85,7 @@
 
   </details>
 
-## Instance setup
+## Setup
 
 ### Deployment
 
@@ -592,8 +593,7 @@ $ minikube kubectl -- delete ns 'awx'
 <details>
 <summary>Run: kustomized helm chart</summary>
 
-> #### Warning
+> [!warning]
->
 > Remember to include the CRDs from the helm chart.
 
   <details style="margin-left: 1em">
@@ -754,7 +754,7 @@ deployment.apps "awx-operator-controller-manager" deleted
   </details>
 </details>
 
-## Jobs execution
+### Job execution
 
 Unless explicitly defined in Job Templates or Schedules, Jobs using a containerized execution environment are executed
 by the _default_ container group.
@@ -888,6 +888,20 @@ resource limits.
 
 </details>
 
+## Job templates
+
+> [!warning]
+> Variables configured in job templates are given to the `ansible-playbook` command for the job using its
+> `-e, --extra-vars` option.<br/>
+> This means they will have the **highest** precedence of all variables, and as such they will override **any** other
+> block or task variable named like that. Refer [Ansible variables].
+
+> [!caution]
+> Once a variable is defined in a job template, it **will** be passed to the ansible command for the job.<br/>
+> When launching a job that allows for variables editing, the edited ones will be **merged** with the initial setting.
+> As such, deleting variables while launching a job will result in them still being passed on with the value they had in
+> the initial variables setting.
+
 ## Workflow automation
 
 Refer [How to use workflow job templates in Ansible], [Workflow job templates] and [Workflows].<br/>
@@ -1085,9 +1099,11 @@ Refer [AWX Command Line Interface] for more information.
   ═╬═Time══
   -->
 
+<!-- In-article sections -->
 [gotchas]: #gotchas
 
 <!-- Knowledge base -->
+[Ansible variables]: ansible.md#variables
 [helm]: kubernetes/helm.md
 [kubernetes]: kubernetes/README.md
 [kustomize]: kubernetes/kustomize.md

knowledge base/markdown.md

@@ -5,6 +5,8 @@ ReadMe's Markdown engine.
 Compare Markdown implementations at [babelmark].
 
 1. [TL;DR](#tldr)
+1. [Alerts](#alerts)
+1. [Images](#images)
 1. [Troubleshooting](#troubleshooting)
    1. [Escape the backtick character](#escape-the-backtick-character)
    1. [Render mermaid.js graphs in VS Code's Markdown preview](#render-mermaidjs-graphs-in-vs-codes-markdown-preview)
@@ -13,57 +15,6 @@ Compare Markdown implementations at [babelmark].
 
 ## TL;DR
 
-<details>
-  <summary>Alerts</summary>
-
-Requires the Alert extension.
-
-Refer [Github's alert formatting][github formatting  alerts].
-
-```md
-> [!NOTE]
-> Useful information that users should know, even when skimming content.
-
-> [!TIP]
-> Helpful advice for doing things better or more easily.
-
-> [!IMPORTANT]
-> Key information users need to know to achieve their goal.
-
-> [!WARNING]
-> Urgent info that needs immediate user attention to avoid problems.
-
-> [!CAUTION]
-> Advises about risks or negative outcomes of certain actions.
-```
-
----
-
-> [!NOTE]
-> Useful information that users should know, even when skimming content.
-
----
-
-> [!TIP]
-> Helpful advice for doing things better or more easily.
-
----
-
-> [!IMPORTANT]
-> Key information users need to know to achieve their goal.
-
----
-
-> [!WARNING]
-> Urgent info that needs immediate user attention to avoid problems.
-
----
-
-> [!CAUTION]
-> Advises about risks or negative outcomes of certain actions.
-
-</details>
-
 <details>
   <summary>Diagrams</summary>
 
@@ -87,30 +38,6 @@ Use a `<details>` HTML tag:
 
 </details>
 
-<details>
-  <summary>Include images</summary>
-
-Add an image:
-
-```md
-![description](path/to.image)
-![description][reference name]
-```
-
-Control width and height:
-
-```md
-<img src="./cat.png" width=300px height=200px />
-```
-
-Align in the center:
-
-```md
-<div align="center">![sleep-cat](./cat.png)</div>
-```
-
-</details>
-
 <details>
   <summary>Math</summary>
 
@@ -149,6 +76,9 @@ private void index(){
 }
 ```
 
+Refer [Syntax highlighting in markdown] and [linguist supported language syntax list] for recognized languages and their
+aliases.
+
 </details>
 
 <details>
@@ -165,6 +95,130 @@ checked one.
 
 </details>
 
+## Alerts
+
+Alerts are not defined in the base Markdown specification.<br/>
+They are extensions that the most famous flavours introduced or adopted, each with small but annoying differences.
+
+<details>
+  <summary>GitHub formatting</summary>
+
+Refer [GitHub's alert formatting][github formatting  alerts].
+
+```md
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+```
+
+---
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+---
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+---
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+---
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+---
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
+</details>
+
+<details>
+  <summary>GitLab formatting</summary>
+
+Refer [GitLab Flavored Markdown][gitlab flavored markdown  alerts].
+
+```md
+> [!note]
+> Information that users should take into account, even when skimming.
+
+> [!tip]
+> Optional information to help a user be more successful.
+
+> [!important]
+> Crucial information necessary for users to succeed.
+
+> [!caution]
+> Negative potential consequences of an action.
+
+> [!warning]
+> Critical potential risks.
+```
+
+---
+
+> [!note]
+> Information that users should take into account, even when skimming.
+
+---
+
+> [!tip]
+> Optional information to help a user be more successful.
+
+---
+
+> [!important]
+> Crucial information necessary for users to succeed.
+
+---
+
+> [!caution]
+> Negative potential consequences of an action.
+
+---
+
+> [!warning]
+> Critical potential risks.
+
+</details>
+
+## Images
+
+Add an image:
+
+```md
+![description](path/to.image)
+![description][reference name]
+```
+
+Control width and height:
+
+```md
+<img src="./cat.png" width=300px height=200px />
+```
+
+Align in the center:
+
+```md
+<div align="center">![sleep-cat](./cat.png)</div>
+```
+
 ## Troubleshooting
 
 ### Escape the backtick character
@@ -199,6 +253,8 @@ Install and enable [`bierner.markdown-mermaid`][bierner.markdown-mermaid]'s exte
 - [The magical Markdown I bet you don't know]
 - [slaise/High-level-Markdown]
 - [Syntax highlighting in Markdown]
+- [Writing on GitHub]
+- [GitLab Flavored Markdown]
 
 <!--
   Reference
@@ -220,9 +276,12 @@ Install and enable [`bierner.markdown-mermaid`][bierner.markdown-mermaid]'s exte
 [escaping backtick in markdown]: https://www.growingwiththeweb.com/2015/06/escaping-backtick-in-markdown.html
 [escaping backticks]: https://www.markdownguide.org/basic-syntax/#escaping-backticks
 [github formatting  alerts]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
+[GitLab Flavored Markdown  alerts]: https://docs.gitlab.com/user/markdown/#alerts
+[GitLab Flavored Markdown]: https://docs.gitlab.com/user/markdown/
 [linguist supported language syntax list]: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
 [live editor]: https://mermaid.live/edit
+[myst]: https://mystmd.org/
 [slaise/high-level-markdown]: https://github.com/slaise/High-level-Markdown
 [syntax highlighting in markdown]: https://support.codebasehq.com/articles/tips-tricks/syntax-highlighting-in-markdown
 [the magical markdown i bet you don't know]: https://medium.com/codex/the-magical-markdown-i-bet-you-dont-know-b51f8c049773
-[myst]: https://mystmd.org/
+[Writing on GitHub]: https://docs.github.com/en/get-started/writing-on-github

snippets/ansible/tasks/debug.yml

@@ -25,6 +25,7 @@
     var: install_method
 
 - name: Print all available variables
+  tags: print_all
   ansible.builtin.debug:
     var: vars  # magic variable
 
@@ -37,7 +38,9 @@
   ansible.builtin.shell: printenv | sort
 
 - name: Start the debugger on failure
-  tags: never
+  tags:
+    - never  # avoid execution unless explicitly requested with other tags
+    - debugger
   # print all variables at this point => p task_vars
   # continue => c
   # abort and quit => q

snippets/ansible/tasks/manipulate data.yml

@@ -319,3 +319,13 @@
     this_is_true_again: "{{ not false }}"
     true_is_truthy: "{{ true is truthy }}"
     false_is_falsy: "{{ false is falsy }}"
+
+- name: Undefined variables
+  tags: undefined_variable
+  # refer <https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_templating_undef.html>
+  # only works for variables of lesser priority
+  # e.g., works in tasks' `vars:`, but not in the `set_facts` module to (re)define a variable
+  vars:
+    test_var: "{{ undef() }}"
+  ansible.builtin.debug:
+    var: test_var

snippets/ansible/use tasks from other files.yml

@@ -8,11 +8,23 @@
   connection: local
   gather_facts: false
   tasks:
-    - ansible.builtin.import_tasks: tasks/debug.yml
+    - name: Import tasks in-line
-    - ansible.builtin.import_tasks:
+      ansible.builtin.import_tasks: tasks/debug.yml
+    - name: Import tasks with arguments and set variables for them
+      vars:
+        somevar: some value
+      ansible.builtin.import_tasks:
         file: tasks/control flows.yml
-    - ansible.builtin.include_tasks: tasks/manipulate data.yml
+    - name: Include tasks in-line
-    - ansible.builtin.include_tasks:
+      tags: always
+      ansible.builtin.include_tasks: tasks/manipulate data.yml
+    - name: Include tasks with arguments and set variables for them
+      tags: always
+      vars:
+        somevar: some value
+      ansible.builtin.include_tasks:
         file: tasks/manipulate data.yml
         apply:
           tags: data_manipulation
+          vars:
+            someothervar: some other value