How ansible/awx works
1. What this repo is
AWX is a Django-based automation controller. The core product is split into a web/API application, a background task/dispatch engine, a websocket/real-time channel, and a set of automation clients and deployment assets around it.
2. Primary application boundary
The main runtime lives under awx/. manage.py, awx/wsgi.py, and awx/asgi.py are the entry points. Django settings are separated into awx/settings/, with environment-specific defaults for development, production, quiet, and Kubernetes-like deployments.
3. HTTP/API layer
awx/api/ is the REST surface. It contains authentication, permissions, serializers, pagination, schema generation, renderers/parsers, and a large set of view and URL modules grouped by resource domain: jobs, templates, inventories, projects, credentials, schedules, workflow jobs, instances, organizations, and notifications. This layer is the public contract consumed by the UI, awxkit, and the Ansible collection.
4. Domain model layer
The business model is centered in awx/main/models/ and awx/conf/models.py. awx/main/models/ covers inventories, hosts, projects, jobs, workflows, credentials, labels, notifications, RBAC, execution environments, receptor addresses, and high-availability state. awx/conf/ stores controller settings and licensing/subscription-related configuration. Django migrations are extensive, which signals that the database schema is a major architectural boundary.
5. Job execution and dispatch pipeline
The asynchronous execution path is in awx/main/dispatch/, awx/main/scheduler/, awx/main/tasks/, awx/main/queue.py, and the management commands like run_dispatcher, dispatcherd, run_callback_receiver, and run_wsrelay. The scheduler chooses what should run, the dispatcher hands work to execution backends, and task modules handle job callbacks, fact collection, host metrics, policy checks, receptor interactions, and system maintenance. This is the core “control plane” versus “execution plane” split.
6. Execution mesh / receptor integration
AWX integrates with a receptor-based execution mesh. The codebase has receptor-facing models, tasks, routing, and install-bundle templates under awx/api/templates/instance_install_bundle/. This is the path by which jobs are placed onto execution nodes rather than run only on the controller host.
7. Real-time updates and analytics
Websocket and event streaming are first-class concerns. awx/main/consumers.py, awx/main/routing.py, and awx/main/wsrelay.py support live updates to clients. awx/main/analytics/ and awx/api/metrics.py collect and expose subsystem metrics, job/job-event stats, and dispatch-related telemetry. These flows connect background activity to the UI and API consumers.
8. UI boundary
The controller UI lives in awx/ui/. It is a separate Django app with its own URLs, context processors, and static/public assets. The repository also contains awx/static/ and awx/templates/ for server-rendered error and API pages, but the main user-facing frontend boundary is the awx/ui app.
9. Notification and external integration subsystem
Notification delivery is isolated under awx/main/notifications/, with backends for email, webhook, Slack, PagerDuty, Mattermost, Rocket.Chat, Twilio, Grafana, IRC, and AWS SNS. This subsystem is fed by job and workflow events from the main domain model and is triggered by controller-side task logic.
10. Automation client and content distribution
The repo includes two important external-facing packages: awx_collection/ and awxkit/. awx_collection is the Ansible Collection that wraps controller resources as modules/lookup plugins/inventory plugins for automation-driven management. awxkit is the Python/CLI client built around the same REST API, using page objects and resource helpers. These are separate distribution artifacts, not part of the server runtime.
11. Deployment and developer infrastructure
The tools/ and config/ directories encode how the system is assembled: Docker/compose, Ansible-based image generation, minikube bootstrap, Grafana/Loki/Prometheus/OTel configs, Redis and rsyslog configs, and release/debug scripts. This repo is designed to run as a multi-process service stack rather than a single process.
12. Data stores and cross-cutting dependencies
PostgreSQL is the primary persistence layer for the Django models and migrations. Redis is used for caching/coordination and websocket-related plumbing. The application also relies on Ansible ecosystem components, receptor communication, and optional observability tooling. Those are important architecture boundaries because they separate controller state, async coordination, and execution telemetry.
13. Quality and change management
Tests are broad and mirror the architecture: API, models, tasks, scheduler, notifications, live/functional, and collection/client tests. The heavy test surface reinforces that AWX is a platform with multiple integration boundaries, not just a single web service.
Main entry points: api/__init__.py REST API · consumers.py Realtime · overview.md Docs · models/__init__.py Domain models
Components 23
Server runtime
Django controller, API surface, async workers, and real-time channels.
- manage.py · Django management entrypoint for the controller.
manage.py - ASGI · Async web/server entrypoint.
awx/asgi.py - WSGI · Sync web/server entrypoint.
awx/wsgi.py - Settings · Environment-specific Django settings and defaults.
awx/settings/defaults.py - REST API · Public REST surface for controller resources.
awx/api/__init__.py - API core · Authentication, permissions, pagination, schema, rendering, and validation.
awx/api/authentication.py - Resource routes · Resource-domain URL modules for jobs, inventories, projects, credentials, workflows, instances, and more.
awx/api/urls/urls.py - API views · View implementations for bulk actions, inventory, metrics, organization, webhooks, and install bundles.
awx/api/views/root.py - API docs · Browsable API and install-bundle templates.
awx/api/templates/api/api_root_view.md - Controller config · Persistent settings, licensing, and subscription configuration.
awx/conf/models.py - Domain models · Core controller entities for inventories, jobs, workflows, projects, credentials, RBAC, execution environments, and HA state.
awx/main/models/__init__.py - Migrations · Large schema-evolution boundary for controller state.
awx/main/migrations/0001_initial.py - Scheduler · Decides what should run and builds dependency graphs.
awx/main/scheduler/task_manager.py - Dispatcher · Hands scheduled work to execution backends and workers.
awx/main/dispatch/worker/dispatcherd.py - Tasks · Job callbacks, facts, host metrics, policy, receptor, and system maintenance tasks.
awx/main/tasks/jobs.py - Realtime · Consumers, routing, relay, and websocket heartbeat for live updates.
awx/main/consumers.py - Analytics · Subsystem metrics, dispatch telemetry, and websocket broadcast analytics.
awx/main/analytics/core.py - Notifications · Outbound email, webhook, chat, pager, SMS, and SNS backends.
awx/main/notifications/base.py - Web UI · Separate Django UI boundary with its own URLs, context processors, and public assets.
awx/ui/urls.py
Clients
External-facing automation clients built from the controller API.
- AWX Collection · Ansible collection for managing controller resources as modules, lookup plugins, and inventory plugins.
awx_collection/plugins/modules/job_launch.py - AWXKit · Python/CLI client built on the REST API with page objects and resource helpers.
awxkit/awxkit/api/client.py
Deployment
Build, runtime, and observability assembly for local, container, and cluster installs.
- Tools · Docker, compose, minikube, scripts, and observability assembly.
tools/docker-compose/launch_awx.sh
Docs & tests
Validation surface and repository documentation.
- Docs · Repository documentation for architecture, APIs, workflows, and operations.
docs/overview.md
Connections 34
- manage.py → Settings: loads · Django runtime bootstraps environment settings.
- manage.py → REST API: starts · Management commands exercise the Django API app.
- manage.py → Domain models: uses · Commands operate on controller domain state.
- ASGI → Realtime: serves · ASGI path supports websocket and async channels.
- WSGI → REST API: serves · WSGI path exposes the REST and browsable API.
- Settings → Controller config: binds · Settings incorporate controller configuration and licensing.
- REST API → API core: contains · Core API machinery for auth, permissions, serialization, and schema.
- REST API → Resource routes: routes · Resource-specific URL modules define the public contract.
- REST API → API views: implements · View modules handle resource behavior and actions.
- REST API → API docs: documents · Browsable API and install-bundle templates are generated here.
- REST API → Domain models: reads/writes · REST resources expose controller domain entities.
- REST API → Analytics: exposes · Metrics and analytics endpoints surface subsystem telemetry.
- REST API → Notifications: configures · Notification templates and delivery resources are managed via API.
- Domain models → Migrations: evolves · Schema changes track the domain model over time.
- Scheduler → Domain models: plans · Scheduling decisions are based on jobs, workflows, instances, and capacity state.
- Scheduler → Dispatcher: hands off · Scheduled work is passed to the dispatcher for execution.
- Dispatcher → Tasks: runs · Dispatcher and workers execute callback, policy, receptor, and maintenance tasks.
- Tasks → Domain models: updates · Background work mutates job, host, project, and HA state.
- Tasks → Notifications: triggers · Task outcomes drive outbound notifications.
- Tasks → Realtime: publishes · Background events are pushed into live channels.
- Realtime → Analytics: feeds · Realtime activity contributes to analytics and telemetry.
- Web UI → REST API: consumes · Frontend boundary uses the REST API.
- Web UI → Realtime: subscribes · UI receives live updates over websocket channels.
- AWX Collection → REST API: wraps · Collection modules call controller REST resources.
- AWXKit → REST API: consumes · Python/CLI client is built around the same API contract.
- Tools → manage.py: orchestrates · Container and bootstrap tooling launch Django processes and commands.
- Tools → Dispatcher: deploys · Service definitions include controller worker/dispatcher processes.
- Tools → Realtime: deploys · Deployment assets include websocket relay and heartbeat services.
- Tools → Analytics: observes · Observability stack captures controller metrics and logs.
- Docs → REST API: describes · Documentation covers REST conventions and API reference.
- Docs → Scheduler: describes · Docs explain task manager and scheduling behavior.
- Docs → Realtime: describes · Docs cover websocket architecture and live updates.
- Docs → AWX Collection: describes · Docs include collection usage and content distribution.
- Docs → AWXKit: describes · Docs cover client usage and command-line workflows.