AWX Operator Installation

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:

Kubernetes or OpenShift Cluster

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

kubectl or oc CLI

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

Cluster Admin Permissions

Administrator-level permissions on the cluster to:

Create namespaces
Install Custom Resource Definitions (CRDs)
Create RBAC roles and bindings
Deploy the operator

Kustomize (Optional)

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:

Kustomize (Recommended)
Operator Lifecycle Manager
Helm Chart

Install using Kustomize

This is the most flexible installation method and is recommended for most users.

Create namespace

Create a dedicated namespace for the AWX Operator:

kubectl create namespace awx

Create kustomization file

Create a kustomization.yaml file:

kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: awx

resources:
  # Find the latest release tag from:
  # https://github.com/ansible/awx-operator/releases
  - github.com/ansible/awx-operator/config/default?ref=2.19.1

# Set the image tags to match the release version
images:
  - name: quay.io/ansible/awx-operator
    newTag: 2.19.1

Replace 2.19.1 with the latest stable release version from the AWX Operator releases page.

Deploy the operator

Apply the kustomization to deploy the operator:

kubectl apply -k .

Verify the operator is running:

kubectl get pods -n awx

You should see the operator pod in a Running state:

NAME                                               READY   STATUS    RESTARTS   AGE
awx-operator-controller-manager-68d787cfbd-kjfg7   2/2     Running   0          30s

Install using OLM

If your cluster has Operator Lifecycle Manager (OLM) installed, you can install the AWX Operator from OperatorHub.

Access OperatorHub

In the OpenShift web console or Kubernetes dashboard, navigate to OperatorHub.

Search for AWX Operator

Search for “AWX” in the operator catalog and select the AWX Operator.

Install the operator

Click “Install” and follow the prompts to:

Select the installation namespace
Choose the update approval strategy
Confirm the installation

Verify installation

Check that the operator is installed and running:

kubectl get csv -n operators

Install using Helm

If you prefer using Helm for package management:

Add the Helm repository

helm repo add awx-operator https://ansible.github.io/awx-operator/
helm repo update

Install the chart

helm install awx-operator awx-operator/awx-operator \
  --namespace awx \
  --create-namespace

Verify installation

helm list -n awx
kubectl get pods -n awx

Deploying AWX

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

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.

Deploy AWX

Apply the custom resource:

kubectl apply -f awx-instance.yaml

The operator will begin deploying AWX components.

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

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:

LoadBalancer
Ingress
Port Forward

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.

If you configured an Ingress:

# Check Ingress configuration
kubectl get ingress -n awx

Access AWX at the configured hostname (e.g., https://awx.example.com).

For testing or local access:

kubectl port-forward svc/awx-service -n awx 8080:80

Access AWX at http://localhost:8080 in your browser.

Configuration Options

The AWX Operator supports extensive configuration through the AWX custom resource spec:

Resource Requirements

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

Storage Configuration

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

External Database

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

Custom Images

Use custom AWX or Redis images:

spec:
  image: quay.io/ansible/awx
  image_version: "24.6.1"
  redis_image: redis:7-alpine

Replicas and Scaling

Configure multiple replicas for high availability:

spec:
  replicas: 3
  web_replicas: 2
  task_replicas: 2

Upgrading AWX

To upgrade AWX to a new version:

Update operator

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

Update AWX version

Modify your AWX custom resource to specify the new version:

spec:
  image_version: "24.6.1"  # New version

Apply changes

Apply the updated configuration:

kubectl apply -f awx-instance.yaml

The operator will perform a rolling upgrade with minimal downtime.

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

Operator pod not starting

Check operator logs:

kubectl logs -n awx deployment/awx-operator-controller-manager

Common issues:

Insufficient RBAC permissions
Resource constraints
CRD installation failures

AWX pods in pending state

Check resource availability:

kubectl describe pod <pod-name> -n awx

Common causes:

Insufficient cluster resources
Storage provisioning issues
Image pull failures

Database connection issues

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

Cannot access AWX web interface

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.

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

AWX Operator Installation

Overview

Prerequisites

Installation Methods

Install using Kustomize

Install using OLM

Install using Helm

Deploying AWX

Accessing AWX

Configuration Options

Upgrading AWX

Backup and Restore

Creating a Backup

Restoring from Backup

Troubleshooting

Additional Resources

​Overview

​Prerequisites

​Installation Methods

​Install using Kustomize

​Install using OLM

​Install using Helm

​Deploying AWX

​Accessing AWX

​Configuration Options

​Upgrading AWX

​Backup and Restore

​Creating a Backup

​Restoring from Backup

​Troubleshooting

​Additional Resources

Overview

Prerequisites

Installation Methods

Install using Kustomize

Install using OLM

Install using Helm

Deploying AWX

Accessing AWX

Configuration Options

Upgrading AWX

Backup and Restore

Creating a Backup

Restoring from Backup

Troubleshooting

Additional Resources