Getting Started with Ansible AWX: Complete Installation and Configuration Guide

Ansible AWX is the open-source upstream project for Red Hat Ansible Automation Platform. It provides a web-based user interface, REST API, and task engine built on top of Ansible, making it easier to manage and scale your automation. This guide will walk you through installing and configuring AWX in 2025.

What is AWX?

AWX provides enterprise-like features for Ansible automation:

• Web UI – Visual interface for managing playbooks and inventories
• REST API – Programmatic access to all features
• Role-Based Access Control – Granular permissions management
• Job Scheduling – Run playbooks on schedules
• Inventory Management – Dynamic and static inventory support
• Credential Management – Secure storage for secrets
• Notifications – Alerts via email, Slack, webhooks
• Logging and Auditing – Complete history of all runs

AWX vs Ansible Automation Platform

Understanding when to use each:

Use AWX for: Learning, development, small teams, home labs

Use AAP for: Production environments, enterprise deployments, compliance requirements

Installation Methods

AWX can be installed via:

1. AWX Operator on Kubernetes – Recommended method
2. Docker Compose – For development and testing
3. Minikube – Single-node Kubernetes for labs

Prerequisites

Before installing AWX, ensure you have:

• Linux server (RHEL, Ubuntu, or compatible)
• Minimum 4 GB RAM (8 GB recommended)
• 2+ CPU cores
• 20 GB disk space
• Docker or Kubernetes cluster
• kubectl and Helm (for Kubernetes install)

Method 1: AWX Operator on Minikube

Step 1: Install Minikube

# Install minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Start minikube with sufficient resources
minikube start --cpus=4 --memory=8g --addons=ingress

# Verify
minikube status

Step 2: Deploy AWX Operator

# Create namespace
kubectl create namespace awx

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

# Checkout latest stable release
git checkout tags/2.19.1

# Deploy the operator
export NAMESPACE=awx
make deploy

# Verify operator is running
kubectl get pods -n awx

Step 3: Create AWX Instance

Create a file named 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_access_mode: ReadWriteOnce

# Apply the configuration
kubectl apply -f awx-instance.yaml -n awx

# Watch the deployment progress
kubectl get pods -n awx -w

# Wait for all pods to be Running (takes 5-10 minutes)

Step 4: Get Admin Password

# Retrieve the admin password
kubectl get secret awx-admin-password -n awx -o jsonpath="{.data.password}" | base64 --decode
echo

Step 5: Access AWX

# Get the URL
minikube service awx-service -n awx --url

# Or use port forwarding
kubectl port-forward svc/awx-service 8080:80 -n awx

Open your browser to the URL and login with:

• Username: admin
• Password: (from step 4)

Initial Configuration

1. Create an Organization

Organizations group users, teams, and resources:

1. Go to Access → Organizations
2. Click Add
3. Enter name (e.g., “My Company”)
4. Save

2. Add Credentials

Create credentials for SSH access:

1. Go to Resources → Credentials
2. Click Add
3. Select Machine credential type
4. Enter SSH username and key/password
5. Save

3. Create an Inventory

Add your managed hosts:

1. Go to Resources → Inventories
2. Click Add → Add inventory
3. Name it (e.g., “Production Servers”)
4. Save, then click Hosts tab
5. Add your server hostnames or IPs

4. Create a Project

Projects link to Git repositories containing playbooks:

1. Go to Resources → Projects
2. Click Add
3. Select Git as source control type
4. Enter your repository URL
5. Add credentials if private repo
6. Save

5. Create a Job Template

Job templates define what playbook to run:

1. Go to Resources → Templates
2. Click Add → Add job template
3. Select your inventory, project, and playbook
4. Add credentials
5. Save

Running Your First Job

1. Navigate to your job template
2. Click the Launch button
3. Watch the job output in real-time
4. Review the results and any failures

Best Practices

• Use Git for playbooks – Always store playbooks in version control
• Limit admin users – Use RBAC to grant minimal permissions
• Regular backups – Back up the PostgreSQL database
• Monitor resources – AWX can consume significant memory
• Update regularly – Keep AWX updated for security fixes

Conclusion

AWX transforms Ansible from a command-line tool into a full automation platform. While it lacks the enterprise support of Ansible Automation Platform, it is an excellent choice for learning, development, and smaller deployments. The web interface makes it easy to collaborate with teams and the scheduling features enable true automation of routine tasks.

Start with AWX to learn the concepts, and consider migrating to Ansible Automation Platform when you need enterprise support and stability guarantees.