Asif Javed

A Practical Guide to AWX: From Setup to Automation

Posted on by Asif

Introduction to AWX

AWX is the open source upstream project for Red Hat Ansible Automation Platform, providing a web-based interface, REST API, and task engine for Ansible. It helps teams manage automation at scale with role-based access control, scheduling, and workflow orchestration.

0. AWX Structure Overview

graph TB
    A[AWX Instance] --> B[Organization]
    A --> C[Administration]

    B --> D[Teams]
    B --> E[Users]
    B --> F[Inventories]
    B --> G[Projects]

    G --> H[Job Templates]
    G --> I[Workflow Templates]

    H --> J[Jobs]
    I --> K[Workflow Jobs]

    C --> L[Notification Templates]
    C --> M[Credentials]
    C --> N[Settings]

1. Creating an Organization

Organizations are the highest level of isolation in AWX. They contain users, teams, inventories, and projects.

Steps:

  1. Navigate to Organizations → Add
  2. Enter Name and Description
  3. Configure optional settings:
    • Maximum Hosts
    • Execution Environment defaults
    • Galaxy credentials

Best Practice: Create separate organizations for different departments (Dev, Ops, Security) or environments (Production, Staging).

2. Creating Teams

Teams allow grouping users within an organization with specific permissions.

Steps:

  1. Select your Organization
  2. Go to Teams → Add
  3. Define team name and assign members
  4. Set permissions for Inventories, Projects, or Templates
graph LR
    A[Organization] --> B[Team: DevOps]
    A --> C[Team: Network]
    A --> D[Team: Security]

    B --> E[User: Alice]
    B --> F[User: Bob]

    C --> G[User: Charlie]

    D --> H[User: Dana]

3. Creating Users

Users can belong to multiple organizations and teams.

Steps:

  1. Navigate to Users → Add
  2. Fill in user details
  3. Assign to Organizations and Teams
  4. Set System Administrator flag if needed
  5. Configure user type (Normal, System Auditor, System Administrator)

Note: Consider integrating with LDAP/AD for enterprise-scale deployments.

4. Creating Inventories

Inventories define the hosts and groups that Ansible manages.

Types:

  • Static Inventories: Manually defined hosts
  • Smart Inventories: Dynamic based on filters
  • Constructed Inventories: Generated from other inventories

Steps:

  1. Go to Inventories → Add Inventory
  2. Choose type and provide details
  3. Add hosts manually or use source:
    • Cloud providers (AWS, Azure, GCP)
    • SCM (Git)
    • Custom script

Example Smart Inventory Filter: ansible_facts.ansible_os_family: RedHat

5. Creating Projects

Projects are collections of Ansible playbooks, usually sourced from version control.

Supported Sources:

  • Git (GitHub, GitLab, Bitbucket)
  • Subversion
  • Mercurial
  • Local directory (for manual sync)

Steps:

  1. Projects → Add Project
  2. Configure SCM details
  3. Set update options (manual/on launch)
  4. Choose Execution Environment

Pro Tip: Use project revision control to track playbook changes over time.

6. Creating Job Templates

Job Templates link projects, inventories, and credentials to create executable jobs.

graph TD
    A[Project<br/>Playbooks] --> D[Job Template]
    B[Inventory<br/>Hosts/Groups] --> D
    C[Credential<br/>SSH/Cloud] --> D
    E[Execution Environment] --> D
    F[Extra Variables] --> D

    D --> G[Job Execution]

Steps:

  1. Templates → Add Job Template
  2. Configure:
    • Name and Description
    • Inventory
    • Project and Playbook
    • Credentials (machine, cloud, vault)
    • Execution Environment
    • Forks, timeout, verbosity
  1. Set prompt-on-launch options for flexibility

7. Creating Workflow Templates

Workflow Templates chain multiple job templates and other workflows.

Node Types:

  • Job Template
  • Project Sync
  • Inventory Sync
  • Workflow Approval
  • Workflow Template (nested)
graph LR
    A[Workflow Start] --> B[Provision Servers]
    B --> C{Approval?}
    C -- Yes --> D[Configure Applications]
    C -- No --> E[Send Notification]
    D --> F[Run Tests]
    F --> G[Deploy to Production]

    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#e8f5e8

Steps:

  1. Templates → Add Workflow Template
  2. Design workflow visually using the Workflow Visualizer
  3. Configure convergence (always/all/successful)
  4. Set extra variables and survey

8. Executing a Job from a Job Template

Methods:

  1. Web UI: Click “Launch” on Job Template
  2. CLI: Use awx or tower-cli
  3. API: POST request to /api/v2/job_templates/N/launch/

Monitoring:

  • Real-time output in web UI
  • Job status updates
  • Notifications on completion
  • Detailed job reports and metrics

9. Executing a Job from a Workflow Template

Key Differences:

  • Parallel or sequential execution
  • Conditional paths
  • Approval steps
  • Comprehensive audit trail

Execution Flow:

  1. Launch triggers first node
  2. Each node runs based on convergence rules
  3. Progress shown in Workflow Visualizer
  4. Final status aggregated

10. Scheduling Jobs

Schedule recurring or future executions.

Configuration Options:

  • Frequency: Minute, Hourly, Daily, Weekly, Monthly, Custom cron
  • Start/End Dates: Set expiration for temporary schedules
  • Time Zones: Local or UTC
  • Extra Variables: Override per schedule

Use Cases:

  • Daily configuration compliance checks
  • Weekly reporting
  • Monthly maintenance windows
  • On-demand scheduled deployments

11. Configuring Notification Templates

Notifications alert users and systems about job status.

Supported Integrations:

  • Email
  • Slack
  • Microsoft Teams
  • Webhooks
  • IRC
  • PagerDuty
  • Grafana

Steps:

  1. Administration → Notification Templates → Add
  2. Choose type and configure
  3. Test using “Test” button
  4. Customize messages with templates

12. Assigning Notifications to Templates

Notifications can be assigned at multiple levels:

Assignment Hierarchy:

  1. Organization-level (all jobs)
  2. Template-level (specific jobs/workflows)
  3. Job-level (override for specific run)

Configuration:

  1. Edit Template → Notifications tab
  2. Add notification templates
  3. Choose triggers:
    • Success
    • Error
    • Started
    • Approval needed/approved/denied

13. Leveraging the AWX API

The REST API enables full automation of AWX itself.

Common Use Cases:

  • CI/CD pipeline integration
  • Bulk operations
  • Custom dashboards
  • External system integration

API Examples:

# Launch job via API
curl -X POST https://awx.example.com/api/v2/job_templates/7/launch/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

# Create inventory via API
curl -X POST https://awx.example.com/api/v2/inventories/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "organization": 1}'

Python Example:

import requests
from awx import Awx

awx = Awx(
    username='admin',
    password='password',
    base_url='https://awx.example.com'
)

# Create and launch job
job = awx.job_templates.launch(
    id=7,
    extra_vars={'version': '2.1.0'}
)

Best Practices & Tips

  1. RBAC Strategy: Follow principle of least privilege
  2. Inventory Management: Use dynamic inventories for cloud environments
  3. Version Control: Store all playbooks in Git
  4. Credential Security: Use vault for sensitive data
  5. Monitoring: Configure comprehensive notifications
  6. Backup: Regularly backup AWX database
  7. Scaling: Use isolated execution nodes for large environments

Conclusion

AWX provides enterprise-grade automation capabilities while remaining open source. By following this structured approach—from organizations and teams to job templates and workflows—teams can build scalable, maintainable automation pipelines. The API-first design ensures AWX can integrate into any DevOps toolchain, making it a versatile choice for infrastructure automation.

Start small with a single job template, then expand to workflows and scheduled jobs as your automation maturity grows.