awx + curl for ~~fun and profit~~ whatever use it has to you

It’s the only song I knew of that had “and curl” in the title.
This article is not as cool as the Shabazz Palaces track.
This is an article about using cURL to trigger an AWX job and pass variables to it via the body of your cURL command.

Why do this?⌗

You may want to configure some kind of event driven API call that can interact with AWX to start a job.
You may think that triggering jobs via the API is cool, and you don’t want to use AWX CLI.
You may just want to learn something.

Getting started⌗

Things you need:

AWX
a job template with a SURVEY ENABLED.
a user token to authenticate with the AWX API
- (Click your username -> User Details -> Tokens -> Add -> Make sure the token has “write” capabilities)
- (Consider the security implications of an unsecured token with write capabilities)
either good old fashioned cURL, or a similar HTTP client like Bruno, etc

Why does this need a survey?⌗

If you do not have a survey enabled, the job will not accept extra_vars via an API call.

Example playbook⌗

Here’s an example playbook that I set up for this:

---
- name: cURL testing playbook
  hosts: all
  connection: local

  tasks:
  - name: This is my first variable
    ansible.builtin.debug:
      msg: "{{ test_var }}"

  - name: This is my second variable
    ansible.builtin.debug:
      msg: "{{ test_var_2 }}"

In AWX, I added a survey to the job template with two questions and set their variables to test_var and test_var_2, just like we have listed above.
Jot down the id of the job template, you’ll need it later. It’s the number in the URI:


https://my.awx.cool/api/v2/job_templates/32/ <-- that one

Using cURL to run the job template with variables⌗

You can dig through the AWX API documentation at your leisure, but the API endpoint you want to hit will be /api/v2/job_templates/<your job template id>/launch
Any extra_vars should be passed in the body of the request as JSON. Here’s an example:

curl --request POST \
  --url https://my.awx.cool/api/v2/job_templates/<your job template id>/launch \
  --header 'authorization: Bearer <your user token>' \
  --header 'content-type: application/json' \
  --data '{"extra_vars":
   {
    "test_var":"This is test var 1",
    "test_var_2": "This is test var 2"
  }
}'

Running this should kick off the job in AWX and give you the following output (cleaned a little for readability):

PLAY [cURL testing playbook]

TASK [Gathering Facts] ***************************************
    ok: [host1]

TASK [This is my first variable] *****************************
ok: [host1] => {
    "msg": "This is test var 1"
}

TASK [This is my second variable] ****************************
ok: [host1] => {
    "msg": "This is test var 2"
}

PLAY RECAP ***************************************************
host1         : ok=3    changed=0    unreachable=0 failed=0

What if my inventory is huge and I want to limit to a single host?⌗

You can pass in limits in the body of the request as well.

curl --request POST \
  --url https://my.awx.cool/api/v2/job_templates/<your job template id>/launch \
  --header 'authorization: Bearer <your user token>' \
  --header 'content-type: application/json' \
  --data '{"extra_vars":
   {
    "test_var":"This is test var 1",
    "test_var_2": "This is test var 2"
  },
  "limit": "host1"
}'

You could get even MORE creative here and do something psycho like writing a chat bot that takes arguments and turns them into vars for particular jobs. The world is your oyster.

Anyway, hope this was a useful search engine result for you.

Leave a comment, or don’t. Thanks for reading.

AWX + cURL for fun and profit whatever use it has to you