AWX in Action

Under the Hood: The AWX Architecture

AWX is a Django web application backed by PostgreSQL, deployed on Kubernetes via the AWX Operator. Jobs run inside short-lived pods called execution environments. That's the whole picture. The rest of this section unpacks each piece and why it matters when you operate AWX.

Execution environments

An execution environment (EE) is a container image that bundles ansible-core, Python, collections, and any system dependencies your playbooks need. When you launch a job, AWX creates a pod from the EE image, runs the playbook inside it, streams the output back, and tears the pod down. Nothing persists between runs.

AWX ships with a default EE image, quay.io/ansible/awx-ee, which covers most common cases. You build custom EEs when you need extra collections, Python libraries, or system packages that aren't in the default image. Job templates pick which EE to run against, so different jobs can have different runtimes without polluting each other.

Two reasons this design matters: execution isolation and reproducibility.

Why AWX Needs Kubernetes

AWX runs on Kubernetes (or OpenShift, which is Red Hat's Kubernetes distribution). This is not optional in the current AWX Operator. Standalone Docker Compose installs were deprecated years ago.

AWX needs to schedule arbitrary numbers of EE pods on demand. Kubernetes already does pod scheduling, secrets, service discovery, and rolling updates. Building that into AWX itself would duplicate what every modern infrastructure team already runs.

If your team doesn't run Kubernetes, AWX adds an operational burden you didn't sign up for. Community projects like fitbeard/awx-without-k8s repackage AWX for non-K8s environments, but they're unofficial, may lag behind upstream, and probably break on AWX upgrades. Use them for a homelab, not a production environment.

If Kubernetes is too much for your team and you only need a job runner with a UI, the honest answer is that AWX is the wrong tool. Use Semaphore or run playbooks from CI (GitLab, GitHub Actions, Jenkins) instead.

The API Is the Real Product

AWX has a REST API. The web UI is a client of that API, not a separate service. Anything you can do in the UI you can do with curl, the awx CLI, or any HTTP client. Job templates, inventories, credentials, schedules, workflows: all of it is exposed as REST endpoints under /api/v2/.

Example:

# Every endpoint is discoverable from the root.
curl -k -u admin:$AWX_PASSWORD https://$AWX_HOST/api/v2/