# AWX — Web UI, API, and Task Engine for Ansible

> AWX is the upstream open-source project behind Red Hat Ansible Automation Platform, providing a web UI, REST API, and task engine for running, scheduling, and managing Ansible playbooks at scale.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# AWX — Web UI, API, and Task Engine for Ansible

## Quick Use
```bash
# Install the AWX Operator into a Kubernetes cluster (minikube / kind works)
kubectl create ns awx
helm repo add awx-operator https://ansible-community.github.io/awx-operator-helm/
helm install awx-operator awx-operator/awx-operator -n awx

# Request an AWX instance
cat <<EOF | kubectl apply -n awx -f -
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx-demo
spec:
  service_type: NodePort
EOF

# Fetch admin password and port
kubectl -n awx get secret awx-demo-admin-password -o jsonpath="{.data.password}" | base64 -d
kubectl -n awx get svc awx-demo-service
```

## Introduction
AWX exists because Ansible''s CLI, while excellent for single operators, does not scale to teams that need shared inventory, RBAC, scheduled runs, and an audit trail. AWX layers a Django-based control plane over the Ansible runner, turning playbooks into repeatable Job Templates, storing credentials in an encrypted vault, and exposing every operation through a REST API. It is the community distribution of what Red Hat sells as Ansible Automation Platform, minus commercial support and hardened content.

## What AWX Does
- Runs and schedules Ansible playbooks with per-job logs, status tracking, and cancellation.
- Manages dynamic and static inventories from sources like AWS, Azure, GCP, vCenter, and SCM.
- Encrypts and injects credentials (SSH keys, cloud tokens, vault passwords) into runs without exposing them to users.
- Exposes surveys and prompts so non-engineers can run parameterized automation from the UI.
- Provides RBAC on organizations, teams, projects, credentials, inventories, and job templates.

## Architecture Overview
An AWX deployment is a set of Kubernetes-native components orchestrated by the AWX Operator: a Django web/API pod, a PostgreSQL database, Redis for caching and websockets, and one or more execution-environment containers that run the actual Ansible workload. Jobs are dispatched through receptor, a mesh-aware task router that lets you add remote execution nodes into segmented networks. Websockets stream live stdout to the browser, and every event is persisted so reruns and reports can replay history.

## Self-Hosting & Configuration
- The AWX Operator is the supported install path; legacy docker-compose installs are deprecated.
- Provide a persistent volume class for PostgreSQL or point to an external managed PG instance.
- Use `AWX` CRs to declaratively set admin user, hostname, TLS secret, and LDAP/OIDC integration.
- Build custom execution environments with `ansible-builder` to pin collections, Python deps, and binaries.
- Enable receptor mesh nodes to reach air-gapped targets without opening your control plane.

## Key Features
- Job Templates, Workflow Templates, and Surveys compose complex multi-playbook pipelines.
- Execution Environments make runs reproducible by shipping Ansible + dependencies as OCI images.
- Fact caching, host metrics, and smart inventories speed up large fleets.
- Granular RBAC plus a fine-grained token system for CI/CD integration.
- Notifications to Slack, Teams, email, and webhooks on job state changes.

## Comparison with Similar Tools
- **Rundeck** — Generic runbook automation across scripts and tools; weaker native Ansible integration.
- **Semaphore UI** — Lightweight OSS Ansible UI; simpler, fewer enterprise features like RBAC and EEs.
- **Ansible Tower** — Commercial predecessor to AAP; AWX is the upstream, feature-equivalent but unsupported.
- **Jenkins + Ansible** — Flexible but you rebuild inventory, credentials, and RBAC yourself.
- **SaltStack** — Different automation model (agent-based, event-driven); AWX is agentless and push-based.

## FAQ
**Q:** Do I need Kubernetes to run AWX?
A: Yes — the current supported deployment is via the AWX Operator on a Kubernetes cluster (k3s/kind/minikube count).

**Q:** Is AWX production-ready?
A: It powers many large deployments, but there are no upgrade guarantees between releases; vendors who need support buy AAP.

**Q:** How are credentials stored?
A: In PostgreSQL, encrypted with a per-install secret key. Plaintext secrets never hit the UI or logs.

**Q:** Can I mesh into isolated networks?
A: Yes — deploy receptor execution nodes inside the target network and register them with the control plane.

## Sources
- https://github.com/ansible/awx
- https://ansible.readthedocs.io/projects/awx/


---
Source: https://tokrepo.com/en/workflows/awx-web-ui-api-task-engine-ansible-b559924e
Author: AI Open Source