Skip to content

tower-invoke-curl

A task to POST to an AWX / Tower endpoint via curl (all OSes)

Performs an HTTP POST to the configured AWX / Tower API endpoint, with optional post-launch polling for job completion.

Authentication: if tower/bearer-token is set, uses Authorization: Bearer. Otherwise falls back to tower/login and tower/password (HTTP Basic auth).

The POST body is taken from tower/variables (serialized to JSON), and Expanded via the golang Template engine.

The Content-Type header is taken from tower/content-type (default: application/json). The URL is taken from the tower/url param.

On a successful 2xx response, fields listed in tower/output-to-inventory are extracted from the JSON response and stored on the Machine as inventory/tower/<field>.

On any non-2xx response the HTTP status code and response body are printed and the task exits with code 1.

Optional Job Polling

When tower/job-wait-type is set to simple or exponential, the task also polls the launched job to completion. With the default none, the task exits as soon as the POST returns, preserving historical behavior.

Polling configuration:

  • tower/job-poll-url: Polling endpoint URL. Must contain the literal placeholder string JOB_ID (no braces), which is substituted at runtime with the captured job ID.
  • tower/job-poll-interval: Seconds between polls (or initial interval for exponential).
  • tower/job-poll-max-interval: Upper bound on the sleep interval for exponential mode (default 60s). Ignored for simple.
  • tower/job-poll-max-wait: Total polling time cap, in seconds.
  • tower/job-poll-id-field: Field in the launch response that holds the job ID (default id). May be a dotted path for nested fields.
  • tower/job-poll-status-map: Object mapping the polling response's status field (dotted-path supported) to success / wait / failure values. Each of success/wait/failure may be a scalar string OR an array of strings — useful for APIs like AWX that have multiple non-terminal states (pending, waiting, running) or multiple failure states (failed, error, canceled). All four keys are required; the union of values across the three buckets must be pairwise disjoint. Comparisons are case-insensitive.

TLS verification for both POST and GET requests is controlled by tower/skip-tls-verify (default true for backwards compatibility with self-signed AWX deployments).

The captured job ID is written to tower/job-id. The polling lifecycle is tracked on the machine via tower/job-poll-state:

  • running during polling
  • failure on failure / unexpected status / HTTP error (exit 1)
  • max-time-expired on timeout (exit 1)
  • removed on success (exit 0)

On success, both tower/job-poll-state and tower/job-id are removed. To retain the job ID after a successful run for audit purposes, include id in tower/output-to-inventory (the default [id, url, status] already does so) — the value is preserved in inventory/tower/id.

Operator Recovery

If a polling cycle fails or times out, tower/job-poll-state remains on the machine and tower/job-id is preserved. The next run of this task (with polling enabled) refuses to launch a new job until the operator clears the state. Two recovery paths exist:

  • Resume polling on the existing Tower job — use after a timeout when the AWX job may still be running:

    drpcli machines set param tower/job-poll-resume to true # re-trigger the stage; task skips POST and re-enters polling

Resume preconditions: tower/job-poll-state=max-time-expired, tower/job-id set, and inventory/tower/id set. The third condition enforces that the launch-response audit trail is still present.

  • Start a brand-new Tower job — discard prior state:

    drpcli machines remove param tower/job-poll-state drpcli machines remove param tower/job-id # re-trigger the stage; task POSTs as normal

tower/job-poll-resume is always cleared on terminal exit (success, failure, or timeout), so each resume is an explicit single decision.

The task works for linux, darwin, and windows OSes.

Objects that Reference tower-invoke-curl

Objects used by tower-invoke-curl