Ansible AWX — Open Source Tower

What Is Ansible AWX?

Ansible AWX (or simply AWX) is the open-source upstream project for Red Hat Ansible Automation Platform (AAP) Controller (formerly Ansible Tower). It provides a web-based UI, REST API, role-based access control (RBAC), job scheduling, credential management, and inventory syncing — all free. AWX is ideal for teams that need centralized Ansible automation management without the cost of AAP licensing.

AWX vs Ansible Tower vs AAP

Feature             | AWX (Free)         | AAP Controller (Paid)
────────────────────|────────────────────|──────────────────────
License             | Apache 2.0         | Red Hat subscription
Support             | Community          | Red Hat support
Release cycle       | Frequent (weekly)  | Stable (quarterly)
Installation        | Kubernetes/Docker  | RPM, containerized
RBAC                | ✅                 | ✅
REST API            | ✅                 | ✅
Job scheduling      | ✅                 | ✅
Credential mgmt     | ✅                 | ✅
Execution Envs      | ✅                 | ✅
Workflow templates   | ✅                 | ✅
Clustering          | ✅                 | ✅ (certified)
Automation mesh     | ❌                 | ✅
Subscription mgmt   | ❌                 | ✅
Content signing     | ❌                 | ✅

Install AWX on Kubernetes (Recommended)

The AWX Operator is the recommended deployment method.

Prerequisites

# Kubernetes cluster (minikube, k3s, kind, EKS, GKE, AKS)
# kubectl configured
# At least 4 CPU, 8GB RAM available

# Install minikube for local dev
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
minikube start --cpus=4 --memory=8192

Deploy AWX Operator

# Install the AWX Operator via Kustomize
cat > kustomization.yaml << 'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - github.com/ansible/awx-operator/config/default?ref=2.19.1
images:
  - name: quay.io/ansible/awx-operator
    newTag: 2.19.1
namespace: awx
EOF

# Create namespace and deploy
kubectl create namespace awx
kubectl apply -k .

# Wait for operator to be ready
kubectl -n awx get pods -w
# NAME                                 READY   STATUS    RESTARTS   AGE
# awx-operator-controller-manager-xxx  2/2     Running   0          2m

Deploy AWX Instance

# awx-instance.yaml
---
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx
  namespace: awx
spec:
  service_type: NodePort
  nodeport_port: 30080
  postgres_storage_class: standard
  projects_persistence: true
  projects_storage_size: 8Gi

# Add to kustomization.yaml
cat >> kustomization.yaml << 'EOF'
  - awx-instance.yaml
EOF

# Deploy
kubectl apply -k .

# Watch deployment (takes 5-10 minutes)
kubectl -n awx get pods -w

# Get admin password
kubectl -n awx get secret awx-admin-password -o jsonpath="{.data.password}" | base64 -d; echo

# Access AWX UI
# minikube: minikube service awx-service -n awx
# NodePort: http://<node-ip>:30080
# Default user: admin

Install AWX with Docker Compose (Development)

# Clone AWX repository
git clone https://github.com/ansible/awx.git
cd awx

# Build and start with Docker Compose
make docker-compose-build
make docker-compose

# Access at http://localhost:8013
# Default credentials: admin / password

AWX Core Concepts

Concept            | Description
───────────────────|──────────────────────────────────────────
Organization       | Top-level grouping (teams, projects, inventories)
Project            | Source control repo containing playbooks
Inventory          | Hosts and groups (static, dynamic, smart)
Credential         | SSH keys, vault passwords, cloud tokens
Template           | Job + project + inventory + credential combo
Job                | A single playbook run (with logs, status)
Workflow           | Chain of templates with conditional logic
Schedule           | Cron-like timing for automatic job runs
Notification       | Alerts on job success/failure (Slack, email)

Configure AWX

Add a Project (Git Repository)

# Via REST API:
POST /api/v2/projects/
{
  "name": "My Ansible Project",
  "organization": 1,
  "scm_type": "git",
  "scm_url": "https://github.com/myorg/ansible-playbooks.git",
  "scm_branch": "main",
  "scm_update_on_launch": true
}

Add an Inventory

# Static inventory via API:
POST /api/v2/inventories/
{
  "name": "Production Servers",
  "organization": 1
}

# Add a host:
POST /api/v2/hosts/
{
  "name": "web01.example.com",
  "inventory": 1,
  "variables": "ansible_host: 192.168.1.10\nansible_user: deploy"
}

Dynamic Inventory Sources

# AWS EC2 dynamic inventory
POST /api/v2/inventory_sources/
{
  "name": "AWS EC2",
  "inventory": 1,
  "source": "ec2",
  "credential": 3,
  "source_vars": "regions:\n  - us-east-1\n  - eu-west-1\nkeyed_groups:\n  - key: tags.Environment\n    prefix: env"
}

Create a Job Template

POST /api/v2/job_templates/
{
  "name": "Deploy Web App",
  "project": 1,
  "playbook": "deploy.yml",
  "inventory": 1,
  "credential": 2,
  "job_type": "run",
  "verbosity": 1,
  "extra_vars": "app_version: latest\nenvironment: production",
  "ask_variables_on_launch": true
}

Create a Workflow

# Workflow: provision → deploy → test → notify
POST /api/v2/workflow_job_templates/
{
  "name": "Full Deployment Pipeline",
  "organization": 1
}

# Add workflow nodes:
# Node 1: Provision infrastructure
# Node 2: Deploy application (on success of node 1)
# Node 3: Run tests (on success of node 2)
# Node 4: Notify team (always, on success or failure)

AWX REST API Usage

# Authentication
export AWX_HOST="http://localhost:30080"
export AWX_TOKEN="your-oauth2-token"

# List job templates
curl -s -H "Authorization: Bearer $AWX_TOKEN" \
  "$AWX_HOST/api/v2/job_templates/" | python3 -m json.tool

# Launch a job
curl -s -X POST -H "Authorization: Bearer $AWX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"extra_vars": {"app_version": "3.2.1"}}' \
  "$AWX_HOST/api/v2/job_templates/5/launch/"

# Check job status
curl -s -H "Authorization: Bearer $AWX_TOKEN" \
  "$AWX_HOST/api/v2/jobs/42/" | python3 -m json.tool

# Download job stdout
curl -s -H "Authorization: Bearer $AWX_TOKEN" \
  "$AWX_HOST/api/v2/jobs/42/stdout/?format=txt"

Using awxkit (Python SDK)

# pip install awxkit
from awxkit import api

# Connect
root = api.Api("http://localhost:30080")
root.load_session("admin", "password")

# List projects
for project in root.get("/api/v2/projects/").results:
    print(f"{project.name}: {project.scm_url}")

# Launch a job template
jt = root.get("/api/v2/job_templates/5/")
job = jt.launch(extra_vars={"app_version": "3.2.1"})
print(f"Job {job.id} status: {job.status}")

# Wait for completion
job.wait_until_completed()
print(f"Final status: {job.status}")

AWX with ansible-playbook (CLI Alternative)

# You can also use AWX collections from regular playbooks
ansible-galaxy collection install awx.awx

# Use in a playbook to manage AWX itself
---
- name: Configure AWX
  hosts: localhost
  connection: local
  collections:
    - awx.awx
  tasks:
    - name: Create organization
      organization:
        name: "Engineering"
        state: present
        controller_host: "http://awx.example.com"
        controller_username: admin
        controller_password: "{{ vault_awx_password }}"

    - name: Create project
      project:
        name: "Web App Playbooks"
        organization: "Engineering"
        scm_type: git
        scm_url: "https://github.com/myorg/playbooks.git"
        controller_host: "http://awx.example.com"
        controller_oauthtoken: "{{ vault_awx_token }}"

Troubleshooting

# Check AWX pods
kubectl -n awx get pods
kubectl -n awx describe pod awx-web-xxx

# View AWX logs
kubectl -n awx logs deployment/awx-web -c awx-web
kubectl -n awx logs deployment/awx-task -c awx-task

# Database issues
kubectl -n awx logs statefulset/awx-postgres-15

# Reset admin password
kubectl -n awx exec -it deployment/awx-web -c awx-web -- \
  awx-manage changepassword admin

# Check AWX version
kubectl -n awx exec deployment/awx-web -c awx-web -- \
  awx-manage version

# Common issues:
# - "Project sync failed" → Check Git URL and credentials
# - "Host key verification failed" → Add known_hosts or disable checking
# - "Vault password not provided" → Add vault credential to template
# - Pods in CrashLoopBackOff → Check resource limits (need 4CPU/8GB)

Common Mistakes

# ❌ MISTAKE 1: Running AWX in production with Docker Compose
# Docker Compose is for DEVELOPMENT only
# Use the AWX Operator on Kubernetes for production

# ❌ MISTAKE 2: Not setting resource limits
# AWX needs significant resources — at least 4 CPU, 8GB RAM
# Under-provisioning causes OOMKills and slow UI

# ❌ MISTAKE 3: Storing credentials in playbooks
# Use AWX credential management instead — it encrypts at rest
# Never commit passwords to Git

# ❌ MISTAKE 4: Ignoring AWX upgrades
# AWX releases frequently — stay within 2-3 versions of latest
# Old versions miss security patches

# ❌ MISTAKE 5: Using AWX when ansible-core is enough
# If you're one person running playbooks manually, you don't need AWX
# AWX shines with teams, scheduling, RBAC, and audit trails

Conclusion

AWX gives you enterprise Ansible features — web UI, REST API, RBAC, scheduling, credential management — at zero licensing cost. Deploy with the AWX Operator on Kubernetes for production, or Docker Compose for local development. It's the right choice for teams that need centralized automation management, audit trails, and self-service job launching without the cost of AAP. Start with a single-node deployment, add projects and inventories, then expand to workflows and schedules as your automation grows.