The deployment of AWX on Kubernetes represents the architectural gold standard for implementing Ansible automation at scale. AWX, serving as the open-source upstream project for Ansible Tower, provides a sophisticated orchestration layer over the Ansible engine. By integrating a comprehensive web-based user interface, a robust REST API, and granular role-based access control (RBAC), AWX transforms Ansible from a command-line tool into a centralized automation platform. The transition to Kubernetes as the primary deployment target is not merely a trend but a strategic shift in how automation controllers are managed. By utilizing the AWX Operator, administrators can move away from brittle, manual installations toward a declarative lifecycle management model. This approach ensures that the automation controller itself is treated as code, allowing for seamless scaling, self-healing, and consistent deployments across diverse environments, ranging from local development clusters like minikube and k3s to enterprise-grade cloud distributions such as Amazon Elastic Kubernetes Service (EKS), Google Kubernetes Engine (GKE), and Azure Kubernetes Service (AKS).

Architectural Analysis: Kubernetes vs. Docker for Production

Determining the appropriate runtime environment for AWX is a critical decision for infrastructure engineers. While it is technically possible to run AWX within Docker containers, there is a stark divide between development-oriented and production-oriented deployment paths.

The Docker installation path is explicitly recommended only for development or test-oriented scenarios. This path lacks an official published release and does not provide the native orchestration capabilities required for high availability. Although some third-party vendors may offer AWX-based images in marketplaces such as the Azure Marketplace, these are not provided by the official AWX developers. Relying on these third-party Docker installations introduces risks regarding updates, security patching, and architectural consistency.

In contrast, Kubernetes is the only recommended method for running AWX in any environment beyond basic development. The shift toward Kubernetes, specifically through the AWX Operator, allows for the implementation of multiple execution nodes and sophisticated control plane management. The operator pattern solves the complexity of managing the AWX lifecycle by automating the deployment of the web interface, the task engine, and the database backend. For production environments, this ensures that the automation platform can scale dynamically and recover from pod failures without manual intervention, providing a level of resilience that standalone Docker deployments cannot match.

Technical Prerequisites and Cluster Validation

Before initiating the deployment of AWX, the underlying Kubernetes cluster must meet specific hardware and software requirements to ensure stability and performance.

The hardware requirements are non-negotiable for a functional installation. A minimum of 2 CPU cores and 4GB of free memory must be available. These resources are required to handle the simultaneous operation of the AWX Operator, the AWX web pod, the task pod, and the PostgreSQL database instance. Insufficient resources will lead to pod crash-looping or severe performance degradation of the REST API.

From a software and configuration perspective, the environment must have kubectl installed and correctly configured to communicate with the cluster. Furthermore, a StorageClass that supports dynamic provisioning is mandatory. AWX relies on PostgreSQL for its state management; without a functional StorageClass to provision Persistent Volume Claims (PVCs), the database cannot persist data, leading to total data loss upon pod restart.

To verify that the environment is ready, the following diagnostic commands must be executed:

Verify cluster access and connectivity

kubectl cluster-info

Analyze current resource utilization across nodes

kubectl top nodes

Confirm the presence of a valid StorageClass for dynamic provisioning

kubectl get storageclass

The AWX Operator: Lifecycle Management and Deployment

The AWX Operator is the central mechanism for installing and managing AWX instances. Originally developed in 2019 by Jeff Geerling and currently maintained by the official Ansible Team, the operator implements the Kubernetes Operator pattern. This means it extends the Kubernetes API to introduce a custom resource definition (CRD) for AWX, allowing users to manage the entire application lifecycle—including installation, upgrades, and backups—through declarative YAML files.

Manual Installation Workflow

The standard installation process involves deploying the operator first, which then watches for an AWX instance specification to trigger the deployment of the actual application components. Once the operator is active, the following pods should be observed in the cluster:

• awx-operator-controller-manager-xxx: The manager that handles the logic of the AWX deployment.
• awx-postgres-13-0: The PostgreSQL database providing the backend storage.
• awx-web-xxx: The web interface and API server.
• awx-task-xxx: The task engine responsible for executing Ansible playbooks.

To verify the status of these components, the following command is used:

kubectl -n awx get pods

Nutanix-Specific Integration and Automated Deployment

For environments utilizing Nutanix, a specialized deployment path is provided via the Ansible Automation Platform (AAP) integration guides. This process is streamlined through a dedicated deployment script located in the deploy/nutanix/scripts/ directory.

The deployment process begins by preparing the script for execution:

cd deploy/nutanix/scripts/
chmod +x awx_deploy.sh
./awx_deploy.sh

The awx_deploy.sh script automates several critical tasks:
1. Verification of kubectl and Helm installation.
2. Detection of available storage classes within the cluster.
3. Deployment of the AWX operator via Helm.
4. Creation of the AWX instance with mandatory persistent storage.
5. Monitoring the deployment until all pods reach a ready state.

The script supports two distinct operational modes to accommodate different storage requirements:

Interactive Mode: This is the default mode triggered by running ./awx_deploy.sh, where the user is guided through the configuration.

Automated Mode: This mode allows the operator to override the storage class via environment variables, which is essential for targeting specific storage backends like local-path or NFS.

Example: Deploying using local-path storage

STORAGE_CLASS_OVERRIDE=local-path ./awx_deploy.sh

Example: Deploying using NFS storage

STORAGE_CLASS_OVERRIDE=nfs-client ./awx_deploy.sh

Post-Deployment Verification and Access

Once the deployment process concludes, administrators must verify the health of the pods and retrieve the initial administrative credentials.

Pod and Service Validation

The following commands are used to ensure that the network and compute layers are functioning as expected:

Verify the status of all AWX related pods in the aap namespace

kubectl get pods -n aap

Verify the status of the AWX services

kubectl get svc -n aap

Administrative Credential Retrieval

The AWX Operator automatically generates a secret containing the initial admin password. Because this password is stored as a base64 encoded string within the Kubernetes secret, it must be decoded for human use.

Retrieve and decode the admin password for the AWX instance

kubectl get secret ansible-awx-admin-password -n aap -o jsonpath='{.data.password}' | base64 -d

Alternatively, in a standard awx namespace deployment, the command is:

kubectl -n awx get secret awx-admin-password -o jsonpath='{.data.password}' | base64 --decode

Network Configuration and Web Interface Access

Accessing the AWX web interface depends on the environment's network architecture and the type of Kubernetes service exposed.

Local and Development Access (NodePort)

For local clusters such as minikube, the NodePort service type is typically used. This exposes the service on a specific port on the node's IP address.

Get the assigned NodePort for the awx-service

kubectl -n awx get svc awx-service

For minikube users, generate the direct access URL

minikube service awx-service -n awx --url

Cloud Access (LoadBalancer)

In cloud environments (EKS, GKE, AKS), a LoadBalancer service is preferred. The administrator must wait for the cloud provider to assign an external IP address.

Check for the external IP assigned to the LoadBalancer

kubectl -n awx get svc awx-service

Production Access (Ingress)

For production-grade deployments, using a NodePort or LoadBalancer directly is insufficient. An Ingress controller (such as NGINX) should be used to manage SSL termination, host-based routing, and request timeouts. This requires the creation of an Ingress resource.

The following configuration fragment demonstrates a production-ready Ingress setup:

yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: awx-ingress namespace: awx annotations: nginx.ingress.kubernetes.io/proxy-body-size: "0" nginx.ingress.kubernetes.io/proxy-read-timeout: "600" nginx.ingress.kubernetes.io/proxy-send-timeout: "600" spec: ingressClassName: nginx rules: - host: awx.example.com http: paths: - path: / pathType: Prefix backend: service: name: awx-service port: number: 80 tls: - hosts: - awx.example.com secretName: awx-tls

When implementing an Ingress, the AWX instance must be updated to use ClusterIP instead of NodePort to ensure that traffic flows securely through the Ingress controller.

Maintenance, Troubleshooting, and Data Protection

Maintaining a production AWX instance requires a strategy for log analysis, database health checks, and a rigorous backup regime.

Troubleshooting Common Failures

When the AWX instance fails to start or behaves erratically, the task pod logs provide the most critical diagnostic information, especially during migration issues.

Analyze the last 100 lines of the task pod logs for migration errors

kubectl -n awx logs deployment/awx-task -c awx-task --tail=100

Database connectivity issues can be diagnosed by executing a direct query against the PostgreSQL pod.

Test database connectivity and execute a simple SQL query

kubectl -n awx exec -it awx-postgres-13-0 -- psql -U awx -d awx -c "SELECT 1"

Disaster Recovery with AWXBackup

The AWX Operator provides a native way to handle backups through the AWXBackup custom resource. This allows the administrator to define backup schedules and storage requirements.

The following YAML configuration defines a daily backup:

yaml apiVersion: awx.ansible.com/v1beta1 kind: AWXBackup metadata: name: awx-backup-daily namespace: awx spec: deployment_name: awx backup_pvc: awx-backup-claim backup_pvc_namespace: awx backup_storage_class: standard backup_storage_requirements: requests: storage: 10Gi

To initiate the backup process:

kubectl apply -f awx-backup.yml

The status of the backup operation can be monitored using:

kubectl -n awx get awxbackup

Summary Comparison of Deployment Methods

The following table provides a detailed comparison between the Docker-based approach and the Kubernetes Operator-based approach for deploying AWX.

Conclusion

The deployment of AWX on Kubernetes represents a significant evolution in the delivery of automation controllers. By leveraging the AWX Operator, organizations move from a static installation model to a dynamic, operator-led lifecycle. The technical requirements—specifically the 2 CPU core and 4GB RAM minimum, alongside a dynamic StorageClass—ensure that the platform remains performant under load. The ability to transition from a simple NodePort setup to a sophisticated NGINX Ingress configuration allows AWX to integrate into enterprise network security policies seamlessly. While Docker remains an option for those in the initial prototyping phase, the Kubernetes path is the only viable strategy for those seeking to implement multiple execution nodes and high-availability control planes. Ultimately, the use of the operator ensures that the automation infrastructure is as scalable and resilient as the systems it is designed to manage.

Sources

1. OneUptime - Install AWX on Kubernetes
2. Juniper Networks - Deploy AWX on Kubernetes
3. GitHub - AWX Operator
4. Ansible Forum - Best approach for implementing AWX in production