Run a Web UI for Ansible Automation with AWX

// Before you start

What you need

A Linux machine (Ubuntu 20.04+ recommended) with at least 4 CPU cores and 8 GB RAM
Docker installed and running (docker --version works)
kubectl installed (kubectl version --client works)
Minikube installed for a local Kubernetes cluster
Basic comfort running commands in a terminal
Stable internet connection for pulling container images

Step 1 of 6

Start a local Kubernetes cluster with Minikube

5 min

AWX runs inside Kubernetes — a system that manages containers. Minikube creates a small, self-contained Kubernetes cluster on your own machine so you do not need a cloud account. The flags below give it enough memory and CPU to actually run AWX without crashing.

Terminal · mac

$ minikube start --cpus=4 --memory=6g --addons=ingress

What you should see

A series of lines ending with 'Done! kubectl is now configured to use "minikube" cluster'

This might happen

Minikube fails to start because Docker is not running

Run 'sudo systemctl start docker' then retry the command

Step 2 of 6

Install the AWX Operator into Kubernetes

5 min

The AWX Operator is a helper program that lives inside Kubernetes and knows how to install and manage AWX for you. 'kustomize' is a tool that applies a configuration file to Kubernetes. The command below points it at the official AWX Operator release and applies it. Replace '2.19.1' with the latest tag shown at https://github.com/ansible/awx-operator/releases if a newer one exists.

Terminal · mac

$ kubectl apply -k "https://github.com/ansible/awx-operator/config/default?ref=2.19.1"

What you should see

Several lines saying 'created' or 'configured', ending with 'deployment.apps/awx-operator-controller-manager created'

This might happen

'unable to recognize' or 'no matches for kind' errors appear

Wait 30 seconds for the cluster to settle, then run the command again

Step 3 of 6

Create the AWX instance definition file

3 min

You need to create two small text files that tell the operator what to build. The first file (kustomization.yaml) lists resources to apply. The second file (awx-demo.yaml) names your AWX instance. You WILL need to create these files — open a plain text editor (like nano or gedit), paste each block, and save with the exact filename shown.

Terminal · mac

$ mkdir -p ~/awx-install && cat > ~/awx-install/awx-demo.yaml << 'EOF'

$ apiVersion: awx.ansible.com/v1beta1

$ kind: AWX

$ metadata:

$ name: awx-demo

$ spec:

$ service_type: nodeport

$ EOF

$ cat > ~/awx-install/kustomization.yaml << 'EOF'

$ apiVersion: kustomize.config.k8s.io/v1beta1

$ kind: Kustomization

$ resources:

$ - awx-demo.yaml

$ EOF

What you should see

No output — the files are created silently. Confirm with: ls ~/awx-install/

This might happen

The heredoc (EOF) syntax pastes incorrectly in some terminals

Create the files manually in a text editor instead, copying the content between the EOF markers

Step 4 of 6

Deploy AWX using the definition files

2 min

Now you point Kubernetes at the folder you just created and tell it to build everything. The operator reads your awx-demo.yaml file and starts pulling the AWX containers and setting up the database automatically.

Terminal · mac

$ kubectl apply -k ~/awx-install/

What you should see

'awx.awx.ansible.com/awx-demo created'

Step 5 of 6

Wait for AWX to finish starting up

15 min

AWX pulls several large container images and initialises a PostgreSQL database. This genuinely takes 10–20 minutes on a first run. The command below watches the pods in real time. You are waiting until you see a pod named 'awx-demo-web-...' with STATUS 'Running' and READY showing '1/1'. Press Ctrl+C once you see that.

Terminal · mac

$ kubectl get pods -l "app.kubernetes.io/managed-by=awx-operator" -w

What you should see

Eventually: awx-demo-web-[random] 1/1 Running 0 [age]

This might happen

A pod stays in 'Pending' or 'CrashLoopBackOff' for more than 20 minutes

Run 'kubectl describe pod [pod-name]' to see the error. Most often it is not enough memory — stop Minikube and restart it with --memory=8g

Step 6 of 6

Retrieve the admin password and open the UI

3 min

AWX generates a random admin password and stores it as a Kubernetes secret. The first command below fetches and decodes it. The second command asks Minikube for the URL where the AWX web interface is reachable. Open that URL in your browser and log in with username 'admin' and the password you retrieved.

Terminal · mac

$ echo "Admin password:" && kubectl get secret awx-demo-admin-password -o jsonpath="{.data.password}" | base64 --decode && echo ""

$ minikube service awx-demo-service --url

What you should see

A random password string on one line, then a URL like http://192.168.49.2:XXXXX

This might happen

'awx-demo-admin-password' secret not found

The pods may still be initialising. Wait another 5 minutes and try again

// Status

cooked. baked. worked.

A running AWX web dashboard accessible in your browser where you can add Ansible inventories, credentials, and playbooks, then run and schedule them through a point-and-click interface — no command line needed for day-to-day use.

// the honest bit

The honest part

AWX releases are currently paused while the project undergoes a large architectural refactoring (as of mid-2024). The version you install today may not receive updates for a while. This setup uses Minikube and is for local testing only — it is not production-ready. Running AWX in production requires a real Kubernetes cluster, persistent storage, and TLS configuration, all of which need developer-level knowledge. Minikube also stops working when your machine restarts; you would need to run 'minikube start' again each time.