Running Jobs

Job templates define how Ansible playbooks are executed in AWX. They bring together projects, inventories, credentials, and playbooks to create reusable automation workflows.

Understanding Job Templates

A Job Template is a definition for running an Ansible playbook. It includes:

Project: Source of playbooks
Playbook: The specific playbook to run
Inventory: Target hosts and groups
Credentials: Authentication for hosts and other services
Execution Environment: Container image with Ansible and dependencies
Variables: Extra variables to pass to the playbook
Options: Verbosity, limits, tags, and other runtime settings

Job Types

Run

Execute the playbook normally (default)

Check

Dry-run mode - shows what would change without making changes

Creating a Job Template

Via Web UI

Navigate to Templates in the sidebar
Click Add → Add job template
Fill in the required fields:
- Name: Descriptive name
- Job Type: Run or Check
- Inventory: Select target inventory
- Project: Select project with playbooks
- Playbook: Choose from available playbooks
- Credentials: Add required credentials
Configure options:
- Verbosity: Output detail level (0-4)
- Forks: Parallel execution count
- Limit: Restrict to specific hosts
- Instance Groups: Where to run the job
Click Save

Via API

curl -X POST https://awx.example.com/api/v2/job_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy Web Application",
    "description": "Deploys the web application to production",
    "job_type": "run",
    "inventory": 1,
    "project": 1,
    "playbook": "deploy.yml",
    "credentials": [1, 2],
    "verbosity": 0,
    "extra_vars": "{\"app_version\": \"1.0.0\"}",
    "allow_simultaneous": false,
    "ask_variables_on_launch": true
  }'

Via Ansible

- name: Create job template
  awx.awx.job_template:
    name: Deploy Web Application
    description: Deploys the web application to production
    job_type: run
    inventory: Production Servers
    project: Infrastructure Playbooks
    playbook: deploy.yml
    credentials:
      - SSH Credential
      - Vault Credential
    verbosity: 0
    extra_vars:
      app_version: "1.0.0"
    ask_variables_on_launch: true
    state: present
    controller_host: awx.example.com
    controller_oauthtoken: "{{ awx_token }}"

Launching Jobs

Simple Launch

Web UI
API
Ansible

Navigate to Templates
Click the rocket icon next to your template
Fill in any prompted values
Click Launch

# Simple launch
curl -X POST https://awx.example.com/api/v2/job_templates/1/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN"

- name: Launch job template
  awx.awx.job_launch:
    job_template: Deploy Web Application
    wait: true
    timeout: 3600

Launch with Extra Variables

API
Ansible

curl -X POST https://awx.example.com/api/v2/job_templates/1/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "extra_vars": {
      "app_version": "2.0.0",
      "environment": "production",
      "debug_mode": false
    }
  }'

- name: Launch with extra vars
  awx.awx.job_launch:
    job_template: Deploy Web Application
    extra_vars:
      app_version: "2.0.0"
      environment: production
      debug_mode: false
    wait: true

Launch with Limit

Restrict execution to specific hosts:

curl -X POST https://awx.example.com/api/v2/job_templates/1/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": "web01:web02"
  }'

Launch with Different Inventory

curl -X POST https://awx.example.com/api/v2/job_templates/1/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inventory": 2
  }'

Job Template Options

Credentials

Multiple credentials can be attached:

- name: Job template with multiple credentials
  awx.awx.job_template:
    name: Complex Deployment
    project: Infrastructure Playbooks
    playbook: deploy.yml
    credentials:
      - SSH Credential          # Machine credential
      - AWS Credentials         # Cloud credential
      - Vault Password          # Vault credential
      - ServiceNow Token        # Custom credential
    state: present

Credential types:

Machine (SSH): For host authentication
Vault: Ansible Vault passwords
Cloud: AWS, Azure, GCP credentials
Network: Network device credentials
Source Control: Git/SCM credentials
Custom: User-defined credential types

Privilege Escalation

Enable privilege escalation (sudo):

become_enabled: true

In the API:

{
  "become_enabled": true
}

Verbosity Levels

# 0 = Normal (default)
verbosity: 0

# 1 = Verbose (-v)
verbosity: 1

# 2 = More Verbose (-vv)
verbosity: 2

# 3 = Debug (-vvv)
verbosity: 3

# 4 = Connection Debug (-vvvv)
verbosity: 4

Forks (Parallelism)

Control parallel execution:

# Run on 10 hosts at a time
forks: 10

# Run on 50 hosts at a time (higher parallelism)
forks: 50

Job Tags

Run specific tagged tasks:

job_tags: "deploy,configure"
skip_tags: "backup,cleanup"

In Ansible playbook:

- name: Deploy application
  tasks:
    - name: Copy files
      copy:
        src: app/
        dest: /var/www/app/
      tags: [deploy]
    
    - name: Configure app
      template:
        src: config.j2
        dest: /etc/app/config.ini
      tags: [configure]
    
    - name: Backup old version
      archive:
        path: /var/www/app/
        dest: /backup/app.tar.gz
      tags: [backup]

Diff Mode

Show file changes:

diff_mode: true

Useful for:

Reviewing template changes
Auditing configuration modifications
Compliance reporting

Prompt on Launch

Allow users to override values when launching:

- name: Job template with prompts
  awx.awx.job_template:
    name: Flexible Deployment
    project: Infrastructure Playbooks
    playbook: deploy.yml
    inventory: Production Servers
    ask_inventory_on_launch: true
    ask_credential_on_launch: true
    ask_variables_on_launch: true
    ask_limit_on_launch: true
    ask_tags_on_launch: true
    ask_skip_tags_on_launch: true
    ask_job_type_on_launch: true
    ask_verbosity_on_launch: true
    ask_diff_mode_on_launch: true
    state: present

Available prompts:

ask_inventory_on_launch
ask_credential_on_launch
ask_variables_on_launch
ask_limit_on_launch
ask_tags_on_launch
ask_skip_tags_on_launch
ask_job_type_on_launch
ask_verbosity_on_launch
ask_diff_mode_on_launch
ask_scm_branch_on_launch
ask_execution_environment_on_launch
ask_forks_on_launch
ask_timeout_on_launch
ask_instance_groups_on_launch

Job Slicing

Distribute a job across multiple slices for large inventories:

- name: Job template with slicing
  awx.awx.job_template:
    name: Large Scale Deployment
    project: Infrastructure Playbooks
    playbook: deploy.yml
    inventory: Production Servers
    job_slice_count: 10  # Split into 10 parallel jobs
    state: present

When launched, this creates a workflow job with 10 slices:

Each slice processes 1/10th of the inventory
Slices run in parallel
Overall job completes faster

Execution Environments

Specify the container image to use:

- name: Job template with custom EE
  awx.awx.job_template:
    name: Python 3.11 Deployment
    project: Infrastructure Playbooks
    playbook: deploy.yml
    execution_environment: Custom Python 3.11 EE
    state: present

Instance Groups

Control where jobs execute:

- name: Job template with instance groups
  awx.awx.job_template:
    name: Regional Deployment
    project: Infrastructure Playbooks
    playbook: deploy.yml
    instance_groups:
      - US-East Instance Group
      - Default
    state: present

Jobs will prefer the first available instance group in the list.

Job Lifecycle

Job States

Pending

Job is queued and waiting to start

Waiting

Job is waiting for dependencies or approval

Running

Job is currently executing

Successful

Job completed without errors

Failed

Job failed with errors

Error

Job encountered a system error

Canceled

Job was canceled by user

Monitoring Job Progress

# Get job status
curl https://awx.example.com/api/v2/jobs/123/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Stream job output (websocket)
wscat -c "wss://awx.example.com/websocket/" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get job events
curl https://awx.example.com/api/v2/jobs/123/job_events/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get stdout
curl https://awx.example.com/api/v2/jobs/123/stdout/?format=txt \
  -H "Authorization: Bearer YOUR_TOKEN"

Waiting for Job Completion

- name: Launch and wait for job
  awx.awx.job_launch:
    job_template: Deploy Web Application
    wait: true
    timeout: 1800  # 30 minutes
  register: job

- name: Display job result
  debug:
    msg: "Job {{ job.id }} finished with status {{ job.status }}"

Canceling Jobs

Web UI
API
Ansible

Click the Cancel button on the job details page

curl -X POST https://awx.example.com/api/v2/jobs/123/cancel/ \
  -H "Authorization: Bearer YOUR_TOKEN"

- name: Cancel job
  awx.awx.job_cancel:
    job_id: 123

Relaunching Jobs

Relaunch a job with the same parameters:

curl -X POST https://awx.example.com/api/v2/jobs/123/relaunch/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Relaunch uses:

Same inventory, project, playbook
Same credentials
Same extra variables
Same limit, tags, etc.

Simultaneous Jobs

By default, job templates don’t allow concurrent execution. Enable it:

allow_simultaneous: true

Be careful with simultaneous jobs - they may conflict if they modify the same resources.

Webhooks

Trigger jobs via webhooks (GitHub, GitLab, etc.):

- name: Enable webhook
  awx.awx.job_template:
    name: Deploy on Push
    project: Infrastructure Playbooks
    playbook: deploy.yml
    webhook_service: github
    webhook_credential: GitHub Webhook Secret
    state: present

Webhook URL format:

https://awx.example.com/api/v2/job_templates/1/github/

Configure in GitHub:

Repository Settings → Webhooks → Add webhook
Payload URL: Your AWX webhook URL
Content type: application/json
Secret: Your webhook credential
Events: Push, Pull Request, etc.

Job Templates vs. Workflows

Job Templates

Run a single playbookUse when:

Single task to execute
Simple automation
No dependencies

Workflows

Chain multiple job templatesUse when:

Multi-stage deployments
Conditional logic
Complex orchestration

Best Practices

Use Surveys

Create surveys for user-friendly variable input

Set Timeouts

Configure reasonable timeouts to prevent hung jobs

Limit Scope

Use limits and tags to minimize blast radius

Test in Check Mode

Always test with job_type: check first

Troubleshooting

Job fails immediately

Common causes:

Missing or invalid credentials
Inventory is empty
Project sync failed
Playbook not found

Check job output:

curl https://awx.example.com/api/v2/jobs/123/stdout/?format=txt \
  -H "Authorization: Bearer YOUR_TOKEN"

Job stuck in pending

Possible issues:

No available instance groups
Capacity limits reached
Previous job blocking (simultaneous = false)

Check instance capacity:

curl https://awx.example.com/api/v2/instances/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Playbook not found in project

Verify:

Project update completed successfully
Playbook file has .yml or .yaml extension
Playbook is valid Ansible syntax
File is in the project repository

List available playbooks:

curl https://awx.example.com/api/v2/projects/1/playbooks/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Variables not applying

Check variable precedence:

Job extra_vars (highest)
Job template extra_vars
Survey responses
Host/group variables
Inventory variables (lowest)

View final variables:

curl https://awx.example.com/api/v2/jobs/123/ \
  -H "Authorization: Bearer YOUR_TOKEN" | jq '.extra_vars'

Surveys

Add surveys to job templates for user input

Scheduling

Schedule jobs to run automatically

Notifications

Set up notifications for job status

Workflows

Create complex workflows with multiple jobs

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

​Understanding Job Templates

​Job Types

Run

Check

​Creating a Job Template

​Launching Jobs

​Simple Launch

​Launch with Extra Variables

​Launch with Limit

​Launch with Different Inventory

​Job Template Options

​Credentials

​Privilege Escalation

​Verbosity Levels

​Forks (Parallelism)

​Job Tags

​Diff Mode

​Prompt on Launch

​Job Slicing

​Execution Environments

​Instance Groups

​Job Lifecycle

​Job States

​Monitoring Job Progress

​Waiting for Job Completion

​Canceling Jobs

​Relaunching Jobs

​Simultaneous Jobs

​Webhooks

​Job Templates vs. Workflows

Job Templates

Workflows

​Best Practices

Use Surveys

Set Timeouts

Limit Scope

Test in Check Mode

​Troubleshooting

​Related Resources

Surveys

Scheduling

Notifications

Workflows

Build docs developers (and LLMs) love

Understanding Job Templates

Job Types

Creating a Job Template

Launching Jobs

Simple Launch

Launch with Extra Variables

Launch with Limit

Launch with Different Inventory

Job Template Options

Credentials

Privilege Escalation

Verbosity Levels

Forks (Parallelism)

Job Tags

Diff Mode

Prompt on Launch

Job Slicing

Execution Environments

Instance Groups

Job Lifecycle

Job States

Monitoring Job Progress

Waiting for Job Completion

Canceling Jobs

Relaunching Jobs

Simultaneous Jobs

Webhooks

Job Templates vs. Workflows

Best Practices

Troubleshooting

Related Resources