Skip to main content
Starting in version 18.0, the AWX Operator is the preferred and recommended way to install AWX. The operator provides automated deployment, configuration, and lifecycle management for AWX on Kubernetes and OpenShift platforms.
The AWX Operator is designed for production deployments and provides enterprise-grade reliability, scalability, and high availability.

​
Overview

The AWX Operator is a Kubernetes operator that manages the complete lifecycle of AWX deployments. It handles:
  • Automated Deployment: Deploys all AWX components as Kubernetes resources
  • Configuration Management: Manages AWX configuration through Kubernetes Custom Resources
  • Upgrades: Automates AWX upgrades with minimal downtime
  • Scaling: Supports horizontal scaling of AWX components
  • High Availability: Enables multi-replica deployments for reliability
  • Backup & Restore: Provides mechanisms for data backup and recovery

​
Prerequisites

Before installing the AWX Operator, ensure you have:
A running Kubernetes (1.21+) or OpenShift cluster with:
  • Sufficient resources for AWX components (minimum 4GB RAM, 2 CPU cores)
  • A storage class for persistent volumes
  • Network access to container registries
  • LoadBalancer or Ingress capability for external access
The Kubernetes command-line tool (kubectl) or OpenShift CLI (oc) installed and configured to access your cluster.
# Verify cluster access
kubectl cluster-info

# Or for OpenShift
oc cluster-info
Administrator-level permissions on the cluster to:
  • Create namespaces
  • Install Custom Resource Definitions (CRDs)
  • Create RBAC roles and bindings
  • Deploy the operator
Kustomize for customizing Kubernetes manifests. Kustomize is built into kubectl version 1.14 and later.

​
Installation Methods

The AWX Operator can be installed using multiple methods. Choose the one that best fits your environment:

​
Deploying AWX

Once the operator is installed, you can deploy an AWX instance:
1

Create AWX custom resource

Create a file named awx-instance.yaml with your AWX configuration:
awx-instance.yaml
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx
  namespace: awx
spec:
  service_type: LoadBalancer
  # Optional: Specify AWX version
  # image_version: "24.6.1"
  
  # Ingress configuration (if using Ingress instead of LoadBalancer)
  # ingress_type: Ingress
  # hostname: awx.example.com
Customize the AWX deployment by adding additional spec fields. See the AWX Operator documentation for all available options.
2

Deploy AWX

Apply the custom resource:
kubectl apply -f awx-instance.yaml
The operator will begin deploying AWX components.
3

Monitor the deployment

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

# Check AWX resource status
kubectl get awx -n awx

# View operator logs
kubectl logs -f deployment/awx-operator-controller-manager \
  -c awx-manager -n awx
The deployment typically takes 5-10 minutes. You’ll see pods for:
  • PostgreSQL database
  • AWX web interface
  • AWX task executor
  • Redis cache
4

Retrieve admin password

Once deployment is complete, retrieve the admin password:
kubectl get secret awx-admin-password -n awx \
  -o jsonpath="{.data.password}" | base64 --decode
The default admin username is admin.

​
Accessing AWX

After deployment, access the AWX web interface:
If you configured service_type: LoadBalancer:
# Get the external IP
kubectl get svc awx-service -n awx
Access AWX at http://<EXTERNAL-IP> in your browser.

​
Configuration Options

The AWX Operator supports extensive configuration through the AWX custom resource spec:
Configure CPU and memory limits:
spec:
  web_resource_requirements:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi
  task_resource_requirements:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 1000m
      memory: 2Gi
Configure persistent storage:
spec:
  postgres_storage_class: fast-ssd
  postgres_storage_requirements:
    requests:
      storage: 20Gi
  projects_persistence: true
  projects_storage_class: standard
  projects_storage_size: 10Gi
Use an external PostgreSQL database:
spec:
  postgres_configuration_secret: awx-postgres-configuration
Create the secret:
kubectl create secret generic awx-postgres-configuration \
  --from-literal=host=postgres.example.com \
  --from-literal=port=5432 \
  --from-literal=database=awx \
  --from-literal=username=awx \
  --from-literal=password=<password> \
  --from-literal=type=managed \
  -n awx
Use custom AWX or Redis images:
spec:
  image: quay.io/ansible/awx
  image_version: "24.6.1"
  redis_image: redis:7-alpine
Configure multiple replicas for high availability:
spec:
  replicas: 3
  web_replicas: 2
  task_replicas: 2

​
Upgrading AWX

To upgrade AWX to a new version:
1

Update operator

First, upgrade the AWX Operator to a compatible version by updating your kustomization or Helm chart.
2

Update AWX version

Modify your AWX custom resource to specify the new version:
spec:
  image_version: "24.6.1"  # New version
3

Apply changes

Apply the updated configuration:
kubectl apply -f awx-instance.yaml
The operator will perform a rolling upgrade with minimal downtime.
4

Monitor upgrade

Watch the upgrade process:
kubectl get pods -n awx -w
kubectl logs -f deployment/awx-operator-controller-manager \
  -c awx-manager -n awx
Always review the release notes before upgrading to understand breaking changes and migration requirements.

​
Backup and Restore

The AWX Operator provides built-in backup and restore capabilities:

​
Creating a Backup

awxbackup.yaml
apiVersion: awx.ansible.com/v1beta1
kind: AWXBackup
metadata:
  name: awx-backup-$(date +%Y%m%d)
  namespace: awx
spec:
  deployment_name: awx
Apply the backup: 
kubectl apply -f awxbackup.yaml

​
Restoring from Backup

awxrestore.yaml
apiVersion: awx.ansible.com/v1beta1
kind: AWXRestore
metadata:
  name: awx-restore
  namespace: awx
spec:
  deployment_name: awx
  backup_name: awx-backup-20240101
Apply the restore: 
kubectl apply -f awxrestore.yaml

​
Troubleshooting

Check operator logs:
kubectl logs -n awx deployment/awx-operator-controller-manager
Common issues:
  • Insufficient RBAC permissions
  • Resource constraints
  • CRD installation failures
Check resource availability:
kubectl describe pod <pod-name> -n awx
Common causes:
  • Insufficient cluster resources
  • Storage provisioning issues
  • Image pull failures
Verify PostgreSQL pod and service:
kubectl get pods -n awx -l app.kubernetes.io/name=postgres
kubectl logs -n awx <postgres-pod-name>
Check database credentials in secrets:
kubectl get secret awx-postgres-configuration -n awx -o yaml
Verify service and ingress configuration:
kubectl get svc -n awx
kubectl get ingress -n awx
Check AWX pod logs:
kubectl logs -n awx -l app.kubernetes.io/name=awx-web

​
Additional Resources

For the most up-to-date installation instructions and configuration options, always refer to the official AWX Operator documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us