Skip to main content

​
Introduction to AWX

AWX provides a web-based user interface, REST API, and task engine built on top of Ansible. It is the upstream project for Red Hat Ansible Automation Platform, enabling teams to better control their Ansible automation at scale.
AWX is currently undergoing a large-scale refactoring to transition to a pluggable, service-oriented architecture. Follow the Ansible Forum for updates on this transformation.

​
What is AWX?

AWX is an open-source automation platform that makes Ansible even more powerful by adding a web UI, REST API, role-based access control (RBAC), job scheduling, credential management, and much more. It transforms Ansible from a command-line tool into a centralized automation hub for your entire organization.

​
Key Capabilities

Centralized Control

Manage all your Ansible automation from a single web interface with comprehensive visibility into job status, output, and history.

REST API

Full-featured REST API enables integration with CI/CD pipelines, external tools, and custom applications.

Role-Based Access

Granular permissions system using django-ansible-base RBAC to control who can execute which playbooks against which inventories.

Credential Management

Secure credential storage with encryption, supporting multiple credential types including cloud providers, SCM systems, and HashiCorp Vault.

Job Scheduling

Schedule playbook runs at specific times or intervals, with support for complex scheduling patterns.

Real-time Updates

WebSocket-based real-time job output and status updates keep you informed as automation executes.

​
Architecture Overview

AWX is built on modern, scalable technologies:
  • Django web framework with Django REST Framework for API endpoints
  • PostgreSQL database for persistent storage
  • Redis for caching and WebSocket message broker
  • Dispatcher task queue system for asynchronous job execution
  • Receptor mesh networking for distributed job execution

​
Core Concepts

​
Organizations

The highest level organizational unit in AWX. Organizations contain teams, users, and logical groupings of inventories, projects, and job templates.

​
Projects

Projects represent your Ansible playbook repositories. AWX supports Git, Subversion, and manual project types, automatically syncing playbook content from your SCM. 
# From awx/main/models/projects.py
SCM_TYPE_CHOICES = [
    ('', _('Manual')),
    ('git', _('Git')),
    ('svn', _('Subversion')),
    ('insights', _('Red Hat Insights')),
    ('archive', _('Remote Archive')),
]

​
Inventories

Inventories define the hosts and groups that your playbooks will run against. AWX supports:
  • Static inventories: Manually defined hosts and groups
  • Dynamic inventories: Auto-populated from cloud providers, Satellite, and other sources
  • Smart inventories: Host lists generated dynamically using filters
  • Constructed inventories: Parse multiple source inventories together

​
Job Templates

Job templates combine a project (playbooks), inventory (hosts), and credentials to create a reusable automation workflow. They define:
  • Which playbook to run
  • Which inventory to run against
  • What credentials to use
  • Job behavior (verbosity, privilege escalation, etc.)
  • Survey prompts for runtime variables

​
Credentials

Securely stored authentication information with support for:
  • Machine credentials (SSH keys, passwords)
  • SCM credentials (Git, Subversion)
  • Cloud credentials (AWS, Azure, GCP, OpenStack)
  • Network credentials (for network devices)
  • Custom credential types (extensible)
AWX uses encryption for sensitive credential data, with field-level encryption powered by the encrypt_field and decrypt_field utilities from awx/main/utils.

​
Job Execution Flow

When you launch a job in AWX, here’s what happens:
1

Job Creation

A Job record is created in the PostgreSQL database with status “pending”.
2

Task Manager

The AWX dispatcher’s task manager evaluates the job, checking capacity, dependencies, and resource availability.
3

Job Dispatch

Once resources are available, the job is dispatched to an execution node via the Receptor mesh network.
4

Ansible Execution

The ansible-runner library executes the playbook in an isolated environment (container or virtual environment).
5

Event Streaming

Job events are streamed back to AWX via callbacks, stored in partitioned event tables, and broadcast via WebSockets to connected clients.
6

Completion

Job status is updated to “successful”, “failed”, or “error”, and notifications are sent if configured.

​
Deployment Options

Starting with version 18.0, the AWX Operator is the preferred deployment method. It runs AWX on Kubernetes or OpenShift, providing:
  • Declarative configuration via Custom Resources
  • Automated upgrades and lifecycle management
  • High availability and scalability
  • Integration with Kubernetes ecosystem

​
Docker Compose (Development)

For development and testing, AWX can run via Docker Compose: 
# From the AWX source repository
make docker-compose-build
make docker-compose
Docker Compose deployments are intended for development/testing only and should not be used in production.

​
Use Cases

AWX excels at:
Maintain consistent configurations across hundreds or thousands of servers, ensuring compliance and reducing configuration drift.
Automate complex multi-tier application deployments with pre-flight checks, rolling updates, and rollback capabilities.
Provision and configure cloud infrastructure across AWS, Azure, GCP, and private clouds using Ansible’s cloud modules.
Configure network devices at scale using Ansible’s network modules with AWX’s credential management and scheduling.
Rapidly apply security patches and remediation playbooks across your infrastructure with audit trails and RBAC.
Chain multiple job templates together in workflows with conditional logic, approval steps, and error handling.

​
Integration Points

AWX integrates seamlessly with:
  • CI/CD pipelines via the REST API and CLI
  • LDAP/Active Directory for authentication
  • SAML/OAuth for single sign-on
  • Logging systems (Splunk, ELK, Loki) for centralized log aggregation
  • Notification systems (Slack, email, PagerDuty, webhooks)
  • Source control (GitHub, GitLab, Bitbucket)
  • Secret management (HashiCorp Vault, CyberArk)

​
Community and Support

AWX is an active open-source project with a vibrant community:

Ansible Forum

Join discussions, ask questions, and share feedback

GitHub

Contribute code, report issues, and view the source

Matrix Chat

Real-time chat with the AWX community

Ansible Docs

Official AWX documentation

​
Next Steps

Get Started

Install AWX and run your first automation job

Architecture Deep Dive

Learn about AWX’s internal architecture and components

Build docs developers (and LLMs) love

Get started for freeTalk to us