Getting Started with AWX

This guide walks you through installing AWX and running your first automation job, from zero to executing an Ansible playbook in under 30 minutes.

This guide uses the AWX Operator for installation on Kubernetes. For development setups using Docker Compose, see the Docker Compose documentation.

Prerequisites

Before installing AWX, ensure you have:

Kubernetes Cluster

A running Kubernetes cluster (1.21+) or OpenShift cluster. Options include:

Minikube (local development): minikube start --cpus=4 --memory=8g --addons=ingress
K3s (lightweight Kubernetes)
EKS/AKS/GKE (managed cloud Kubernetes)
OpenShift (Red Hat’s Kubernetes distribution)

kubectl CLI

Install kubectl to interact with your cluster:

# Verify kubectl is installed and cluster is accessible
kubectl cluster-info
kubectl get nodes

Kustomize

Install kustomize (3.5.1+) for deploying AWX:

# Install kustomize
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
sudo mv kustomize /usr/local/bin/

Cluster Requirements

Minimum resources: 4 CPU cores and 8GB RAM for a basic AWX deployment. Production deployments need significantly more resources depending on workload.

Installation

Step 1: Deploy the AWX Operator

The AWX Operator manages AWX installations on Kubernetes using a Custom Resource Definition (CRD).

# Create a namespace for AWX
export NAMESPACE=awx
kubectl create namespace $NAMESPACE

# Deploy the AWX Operator
export OPERATOR_VERSION=2.19.1
kubectl apply -k "https://github.com/ansible/awx-operator/config/default?ref=$OPERATOR_VERSION"

Check the AWX Operator releases page for the latest version.

Verify the operator is running:

kubectl get pods -n awx
# You should see the awx-operator pod running

Step 2: Configure AWX Instance

Create a configuration file for your AWX instance:

awx-instance.yaml

apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx
  namespace: awx
spec:
  # Service type - use NodePort for local/minikube, LoadBalancer for cloud
  service_type: NodePort
  
  # Optional: Set admin user password (otherwise randomly generated)
  admin_user: admin
  admin_password_secret: awx-admin-password
  
  # PostgreSQL configuration
  postgres_configuration_secret: awx-postgres-configuration
  
  # Optional: Resource limits
  web_resource_requirements:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi
  
  task_resource_requirements:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 2000m
      memory: 2Gi

Step 3: Create Required Secrets

Create secrets for admin password and PostgreSQL:

# Create admin password secret
kubectl create secret generic awx-admin-password \
  --from-literal=password='MySecurePassword123!' \
  -n awx

# Create PostgreSQL configuration secret
kubectl create secret generic awx-postgres-configuration \
  --from-literal=host=awx-postgres-15 \
  --from-literal=port=5432 \
  --from-literal=database=awx \
  --from-literal=username=awx \
  --from-literal=password='PostgresPassword123!' \
  --from-literal=type=managed \
  -n awx

In production, use strong, randomly generated passwords and store them securely. Never commit passwords to version control.

Step 4: Deploy AWX

Apply the AWX instance configuration:

kubectl apply -f awx-instance.yaml

Watch the deployment progress:

# Watch operator logs
kubectl logs -f deployment/awx-operator-controller-manager -n awx -c awx-manager

# Watch AWX pods
kubectl get pods -n awx -w

The deployment typically takes 5-10 minutes. You’ll see pods starting:

awx-postgres-* - PostgreSQL database
awx-web-* - Django web server and API
awx-task-* - Task engine for job execution

Step 5: Access AWX UI

Once all pods are running, access the AWX web interface:

NodePort (Minikube)
LoadBalancer (Cloud)
Port Forward

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

# Or manually get the port
kubectl get svc awx-service -n awx
# Access at http://<node-ip>:<node-port>

# Get the LoadBalancer IP/hostname
kubectl get svc awx-service -n awx
# Access at the EXTERNAL-IP shown

# Forward local port 8080 to AWX
kubectl port-forward svc/awx-service 8080:80 -n awx
# Access at http://localhost:8080

Username: admin
Password: The password you set in the secret (or retrieve it with kubectl get secret awx-admin-password -n awx -o jsonpath="{.data.password}" | base64 -d)

First login may take a moment as the UI assets load. You’ll see the AWX dashboard once authentication succeeds.

Your First Automation Job

Now let’s run a simple Ansible playbook through AWX.

Step 1: Create an Organization

Navigate to Organizations

In the AWX UI, click Organizations in the left navigation menu.

Create Organization

Click the Add button and fill in:

Name: Demo Organization
Description: My first AWX organization

Click Save.

Step 2: Add a Project

Projects link AWX to your Ansible playbook repositories.

Navigate to Projects

Click Projects in the left navigation.

Create Project

Click Add and configure:

Name: Demo Project
Organization: Select Demo Organization
Source Control Type: Git
Source Control URL: https://github.com/ansible/ansible-tower-samples.git
Update Revision on Launch: Check this box

Click Save.

Wait for Sync

AWX will automatically sync the playbooks from Git. Watch the Last Job Status indicator turn green.

The ansible-tower-samples repository contains demo playbooks perfect for testing AWX functionality.

Step 3: Create an Inventory

Inventories define the hosts your playbooks will run against.

Navigate to Inventories

Click Inventories in the left navigation.

Create Inventory

Click Add → Add inventory and configure:

Name: Demo Inventory
Organization: Select Demo Organization

Click Save.

Add a Host

In the inventory details, click the Hosts tab, then Add:

Name: localhost
Variables (in YAML):

ansible_connection: local
ansible_python_interpreter: /usr/bin/python3

Click Save.

Step 4: Create a Credential

For localhost connections, we’ll create a basic machine credential.

Navigate to Credentials

Click Credentials in the left navigation.

Create Credential

Click Add and configure:

Name: Demo Credential
Organization: Select Demo Organization
Credential Type: Machine

For localhost, leave all authentication fields empty.Click Save.

Step 5: Create a Job Template

Job templates tie everything together: project, inventory, and credentials.

Navigate to Templates

Click Templates in the left navigation.

Create Job Template

Click Add → Add job template and configure:

Name: Demo Job Template
Job Type: Run
Inventory: Select Demo Inventory
Project: Select Demo Project
Playbook: Select hello_world.yml
Credentials: Select Demo Credential
Verbosity: 1 (Verbose)

Click Save.

Step 6: Launch Your First Job!

Launch the Job

From the job template details page, click the Launch button (rocket icon).

Watch Real-time Output

You’ll be redirected to the job details page showing real-time output as the playbook executes. You should see:

PLAY [Hello World Sample] *************************************

TASK [Gathering Facts] ****************************************
ok: [localhost]

TASK [Hello Message] ******************************************
ok: [localhost] => {
    "msg": "Hello World!"
}

PLAY RECAP ****************************************************
localhost : ok=2 changed=0 unreachable=0 failed=0

Explore Job Details

After completion, explore the job details:

Output tab: Full Ansible playbook output
Details tab: Job metadata and statistics
Host Events tab: Per-host task results

Congratulations! You’ve successfully installed AWX and executed your first automation job. 🎉

Using the AWX CLI

The AWX CLI (awxkit) provides command-line access to AWX functionality.

Install the CLI

pip3 install awxkit
awx --version

Configure CLI Authentication

# Set environment variables
export TOWER_HOST=https://your-awx-hostname
export TOWER_USERNAME=admin
export TOWER_PASSWORD=YourPassword123!
export TOWER_VERIFY_SSL=false  # Only for testing with self-signed certs

# Or use a config file at ~/.tower_cli.cfg
cat > ~/.tower_cli.cfg <<EOF
[general]
host = https://your-awx-hostname
username = admin
password = YourPassword123!
verify_ssl = false
EOF

Common CLI Operations

# List job templates
awx job_template list

# Launch a job
awx job_template launch <template-id> --monitor

# List recent jobs
awx job list --order_by=-id --limit=10

# Get job output
awx job stdout <job-id>

# List inventories
awx inventory list

# Create a host
awx host create --name webserver01 --inventory <inventory-id>

Use awx --help to explore all available commands and options. The CLI mirrors the REST API structure.

Next Steps

Now that you have AWX running, explore these advanced features:

Configure RBAC

Set up teams, users, and granular permissions for your organization

Dynamic Inventories

Automatically populate inventories from AWS, Azure, GCP, or other sources

Workflow Jobs

Chain multiple job templates together with conditional logic

Job Scheduling

Schedule jobs to run automatically at specific times or intervals

Notifications

Configure Slack, email, or webhook notifications for job results

Execution Environments

Use custom container images with specific Ansible versions and dependencies

Troubleshooting

Pods not starting

Check pod logs for errors:

kubectl logs -n awx <pod-name>
kubectl describe pod -n awx <pod-name>

Common issues:

Insufficient cluster resources (CPU/memory)
PostgreSQL connection failures (check secrets)
Image pull errors (check network connectivity)

Can't access AWX UI

Verify the service is running:

kubectl get svc -n awx
kubectl get endpoints -n awx

Check if pods are ready:

kubectl get pods -n awx

Review web pod logs:

kubectl logs -n awx deployment/awx-web

Job fails to run

Common causes:

Missing or invalid credentials
Network connectivity issues from AWX to target hosts
Inventory configuration errors
Playbook syntax errors

Check job output in the AWX UI for specific error messages. From the source code (awx/main/models/unified_jobs.py), job status can be:

new - Job created but not started
pending - Waiting for task manager
waiting - Assigned to node, about to run
running - Currently executing
successful - Completed successfully
failed - Completed with failures
error - Unable to run
canceled - Canceled before completion

Database migrations pending indefinitely

If you see repeating “Waiting for postgres to be ready” messages:

# Delete AWX-related containers and volumes
kubectl delete namespace awx
kubectl create namespace awx

# Redeploy from scratch
kubectl apply -f awx-instance.yaml

Additional Resources

AWX Documentation

Official AWX documentation with comprehensive guides

AWX Operator Docs

AWX Operator documentation and configuration options

Ansible Forum

Community support and discussions

Architecture Guide

Deep dive into AWX architecture and components

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

​Getting Started with AWX

​Prerequisites

​Cluster Requirements

​Installation

​Step 1: Deploy the AWX Operator

​Step 2: Configure AWX Instance

​Step 3: Create Required Secrets

​Step 4: Deploy AWX

​Step 5: Access AWX UI

​Your First Automation Job

​Step 1: Create an Organization

​Step 2: Add a Project

​Step 3: Create an Inventory

​Step 4: Create a Credential

​Step 5: Create a Job Template

​Step 6: Launch Your First Job!

​Using the AWX CLI

​Install the CLI

​Configure CLI Authentication

​Common CLI Operations

​Next Steps

Configure RBAC

Dynamic Inventories

Workflow Jobs

Job Scheduling

Notifications

Execution Environments

​Troubleshooting

​Additional Resources

AWX Documentation

AWX Operator Docs

Ansible Forum

Architecture Guide

Build docs developers (and LLMs) love

Getting Started with AWX

Prerequisites

Cluster Requirements

Installation

Step 1: Deploy the AWX Operator

Step 2: Configure AWX Instance

Step 3: Create Required Secrets

Step 4: Deploy AWX

Step 5: Access AWX UI

Your First Automation Job

Step 1: Create an Organization

Step 2: Add a Project

Step 3: Create an Inventory

Step 4: Create a Credential

Step 5: Create a Job Template

Step 6: Launch Your First Job!

Using the AWX CLI

Install the CLI

Configure CLI Authentication

Common CLI Operations

Next Steps

Troubleshooting

Additional Resources