diff --git a/knowledge base/awx.md b/knowledge base/awx.md index c326bb9..3f988b2 100644 --- a/knowledge base/awx.md +++ b/knowledge base/awx.md @@ -8,7 +8,8 @@ 1. [Removal](#removal) 1. [Testing](#testing) 1. [Executing jobs](#executing-jobs) -1. [Value precedence](#value-precedence) +1. [Attribute inheritance and overriding](#attribute-inheritance-and-overriding) + 1. [Variables inheritance and overriding](#variables-inheritance-and-overriding) 1. [Elevating privileges in tasks](#elevating-privileges-in-tasks) 1. [Workflow automation](#workflow-automation) 1. [Pass data between workflow Nodes](#pass-data-between-workflow-nodes) @@ -25,7 +26,8 @@ When in doubt about AWX's inner workings, consider [asking Devin][deepwiki ansib - When one does **not** define values in a resource during its creation, the resource will default to the settings of the same name defined by the underlying dependency (if any).
E.g.: not setting the `job_type` parameter in a schedule (or setting it to `null`) makes the job it starts use the - `job_type` setting defined in the job template that the schedule references. + `job_type` setting defined in the job template that the schedule references.
+ Refer [Attribute inheritance and overriding]. - Extra variables configured in job templates will take precedence over the ones defined in the playbook and its tasks, as if they were given to the `ansible-playbook` command for the job using its `-e, --extra-vars` option. @@ -33,7 +35,7 @@ When in doubt about AWX's inner workings, consider [asking Devin][deepwiki ansib These variables will have the **highest** precedence of all variables, and as such it is their value that will be used throughout the whole execution. They will **not** be overridden by any other definition for similarly named variables (not at play, host, block nor task level; not even the `set_facts` module will override them).
- Refer [Extra variables]. + Refer [Variables inheritance and overriding]. - Once a variable is defined in a job template, it **will** be passed to the ansible command for the job, even if its value is set to `null` (it will be an empty string). @@ -732,14 +734,13 @@ deployment.apps "awx-operator-controller-manager" deleted ### Executing jobs -Unless explicitly defined in Job Templates or Schedules, Jobs using a containerized execution environment are executed -by the _default_ container group. +Unless explicitly defined in Job Templates, Schedules, or other resources that allow specifying the `instance_groups` +key, Jobs using a containerized execution environment will execute in the _default_ container group. Normally, the _default_ container group does **not** limit where a Job's pod is executed, **nor** limits its assigned resources.
By explicitly configuring this container group, one can change the settings for Jobs that do not ask for custom -executors. - +executors.
E.g., one could set affinity and tolerations to assign Jobs to specific nodes by default, and set specific default resource limits. @@ -862,13 +863,22 @@ resource limits. -## Value precedence +## Attribute inheritance and overriding -If an AWX resource **both** references another AWX resource **and** sets a property it already defines, the uppermost -setting in the chain takes priority and overrides the value for the rest of the chain. +Some AWX-specific resources allow configuring similar attributes.
+E.g., Schedules, Workflow Job Template Nodes and Job Templates all define `diff_mode`, `job_type`, and other properties. -
- Example: Scheduled Job +This is usually true for resource types that can reference another resource type.
+It is meant to allow _parent_ resource to override properties of their _child_ through hierarchical inheritance.
+E.g.: + +- Schedules and Workflow Job Template Nodes can both reference Job Templates via the `unified_job_template` key. +- Schedules and Workflow Job Template Nodes specifying attributes like `diff_mode` or `job_type` will override the + attribute of the same name specified by the Job Templates they reference. + +
+ +Scheduled Jobs' attributes can override referenced Job Templates properties: ```yml - awx.awx.job_template: @@ -900,13 +910,17 @@ flowchart LR job_template("Job Template") schedule("Schedule") - schedule --> workflow_job_template --> workflow_node --> job_template + schedule --> job_template ```
+This effect is applied recursively to the full reference chain. +
- Example: Scheduled Workflow + +Scheduled Jobs' attributes can override referenced Workflow Job Templates' properties, which are propagated to the Job +Templates used by its Nodes: ```yml - awx.awx.job_template: @@ -955,24 +969,20 @@ flowchart LR
-In a similar fashion, extra variables or prompts defined in AWX resources that reference another AWX resource are -granted **higher** priority than those defined in the referenced resource.
-This effectively ends up applying to the resulting Job as if they were given it with the `--extra-vars` option.
-Refer [Ansible variables]. +### Variables inheritance and overriding -
- Example: Workflows +Variables inheritance works in a similar fashion to [Attribute inheritance and overriding], but is specific to the +`extra_vars` key (A.K.A. _prompts_ in the Web UI). -When Nodes combine variables, they merge the `extra_vars` defined in their Workflow Job Templates **on top** of their -own.
-This gives the values defined in their Workflow Job Templates precedence over the ones defined in the Nodes, and by -extension over the ones defined in the Job Template referenced by the node.
-Workflow Job Templates' variables **cannot** be overridden by individual Nodes nor by any task within the -Workflow.
-This limitation is enforced to try and ensure predictable behavior, with workflow-level configurations remaining -consistent across all jobs within a workflow. +Also see [Extra variables]. -
+Variables defined in parent resources recursively override those defined in children resources.
+Variables defined in ancestors **cannot** be overridden by any of the children in the chain, **nor are affected by any +task** during playbook execution.
+The result is effectively as if they were passed down with the `--extra-vars` CLI option. Refer [Ansible variables]. + +This limitation is enforced to try and ensure predictable behavior, with higher-level configurations remaining +consistent across the whole execution chain. > [!warning] > The AWX API has a specific restriction that does **not** allow nullified values for variables in templates.
@@ -1078,7 +1088,6 @@ As such, Nodes must be defined **last-to-first** in playbooks.
-FIXME When needing to use specific variables only in some Nodes within a workflow, consider: 1. Specifying those variable **only in the Nodes** that require them, and **not** at the Workflow Job Template's @@ -1325,6 +1334,8 @@ Refer [AWX Command Line Interface] for more information. [Gotchas]: #gotchas [Executing Jobs]: #executing-jobs [Pass data between workflow Nodes]: #pass-data-between-workflow-nodes +[Attribute inheritance and overriding]: #attribute-inheritance-and-overriding +[Variables inheritance and overriding]: #variables-inheritance-and-overriding [Ansible]: ansible.md