Setting Up AAP Environment

The Installation That Taught Me Everything

My first AAP installation took three attempts over two days. The first attempt failed because I underestimated resource requirements. The second failed because I didn't understand the inventory file configuration. The third succeeded, but I had to rebuild it a week later because I skipped SSL certificate setup and backup configuration.

What I learned: AAP installation isn't difficult, but it requires careful planning and attention to detail. Skip steps, and you'll rebuild. Understand the components, and you'll have a production-ready environment in hours, not days.

This article is the guide I wish I had for that first installation - everything you need to know to set up AAP correctly the first time.

What You'll Learn

• System requirements and prerequisite planning

• Installation methods: containerized vs RPM-based

• Configuring the inventory file for different topologies

• SSL/TLS certificate setup for production

• Authentication sources (LDAP, SAML, OAuth)

• Post-installation configuration and verification

• Backup and recovery setup

• Common installation pitfalls and solutions

Prerequisites and Planning

System Requirements

Before installing AAP, ensure your infrastructure meets these minimum requirements:

For Single-Node POC/Development

Operating System:
  - Red Hat Enterprise Linux 8.6+ or 9.2+
  - Or supported RHEL derivatives (Rocky, Alma)

Compute Resources:
  - CPU: 4 cores minimum (8 cores recommended)
  - RAM: 16 GB minimum (32 GB recommended)
  - Disk: 40 GB minimum (60 GB recommended)
  - Fast SSD storage preferred

Network:
  - Fully qualified domain name (FQDN)
  - Static IP address
  - Firewall rules allowing ports: 443, 80, 5432, 27199

Software Prerequisites:
  - Python 3.9+
  - Ansible core 2.14+
  - podman or docker (for containerized install)

For Production HA Deployment

Automation Controller Nodes (3 nodes):
  - CPU: 8 cores per node
  - RAM: 64 GB per node
  - Disk: 80 GB per node

Database Server:
  - CPU: 8 cores
  - RAM: 32 GB minimum
  - Disk: 500 GB+ (grows with job history)
  - IOPS: 3000+ (SSD recommended)

Automation Hub (if separate):
  - CPU: 4 cores
  - RAM: 16 GB
  - Disk: 100 GB+ (grows with content)

Execution Nodes (scale as needed):
  - CPU: 4 cores per node
  - RAM: 16 GB per node
  - Disk: 40 GB per node

Real-world insight: We started with 32 GB RAM per controller node and hit memory pressure during peak job execution. Upgrading to 64 GB resolved all performance issues.

Subscription and Licensing

Before installation, obtain your AAP subscription:

Getting a Trial Subscription

# 1. Visit Red Hat to request trial
https://www.redhat.com/en/technologies/management/ansible/trial

# 2. You'll receive via email:
#    - Subscription manifest file (manifest_*.zip)
#    - Red Hat Customer Portal credentials
#    - Access to Red Hat support

# 3. Download the manifest file
#    This file contains your node licenses

Understanding the Manifest

The manifest file contains:

• Number of managed node licenses (e.g., 100, 250, 500 nodes)

• Subscription expiration date

• Entitled products and versions

• Support level

Important: Keep the manifest file safe - you'll upload it during AAP setup.

Network Planning

Plan your network configuration carefully:

# DNS Requirements
controller.example.com    → Primary Automation Controller
controller2.example.com   → Secondary Controller (HA)
hub.example.com          → Automation Hub
eda.example.com          → Event-Driven Ansible Controller

# Firewall Rules
Inbound to Automation Controller:
  - 443/tcp (HTTPS - Web UI and API)
  - 80/tcp (HTTP - redirects to HTTPS)

Internal Between AAP Components:
  - 5432/tcp (PostgreSQL)
  - 6379/tcp (Redis)
  - 27199/tcp (Receptor - Automation Mesh)

Outbound from Automation Controller:
  - 443/tcp (Git repos, Automation Hub, cloud APIs)
  - 22/tcp (SSH to managed nodes)
  - 5985-5986/tcp (WinRM for Windows nodes)

Installation Methods

AAP 2.4+ offers two installation approaches:

Method 1: Containerized Installation (Recommended)

Advantages:

• Easier upgrades and updates

• Better resource isolation

• Consistent across environments

• Faster deployments

Requirements:

• podman or docker installed

• Container registry access

Method 2: RPM-Based Installation (Traditional)

Advantages:

• Traditional Linux package management

• Familiar to sysadmins

• No container overhead

Requirements:

• RHEL subscription

• Access to Red Hat repositories

My recommendation: Use containerized for new deployments. It's the future direction for AAP.

Step-by-Step Installation

Step 1: Prepare the System

# Update system packages
sudo dnf update -y

# Install required packages
sudo dnf install -y ansible-core wget tar

# For containerized install, ensure podman is available
sudo dnf install -y podman

# Verify Python version (3.9+ required)
python3 --version

# Set hostname properly
sudo hostnamectl set-hostname controller.example.com

# Verify DNS resolution
host controller.example.com

Step 2: Download AAP Installer

# Download from Red Hat Customer Portal
# Or use the provided link from your trial email

# For AAP 2.4 containerized bundle
wget https://access.redhat.com/downloads/content/480/ver=2.4/rhel---9/2.4/x86_64/product-software

# Or download manually and transfer to server

# Extract the bundle
tar xvzf ansible-automation-platform-setup-bundle-2.4-*.tar.gz
cd ansible-automation-platform-setup-bundle-2.4

Step 3: Configure the Inventory File

This is the most critical step. The inventory file defines your AAP topology.

Single-Node Configuration (POC/Development)

# inventory - Single node, all-in-one deployment

[automationcontroller]
controller.example.com ansible_connection=local

[automationhub]
controller.example.com ansible_connection=local

[database]
controller.example.com ansible_connection=local

[all:vars]
# General configuration
admin_password='YourSecurePassword123!'
pg_host=''
pg_port=5432
pg_database='awx'
pg_username='awx'
pg_password='YourPostgresPassword123!'

# SSL Configuration (self-signed for POC)
web_server_ssl_cert=/tmp/controller.crt
web_server_ssl_key=/tmp/controller.key

# Hub configuration
automationhub_admin_password='YourHubPassword123!'

# Container registry (for Execution Environments)
registry_username='admin'
registry_password='YourRegistryPassword123!'

Real-world note: This works for POC, but don't use for production. No HA, single point of failure.

Production HA Configuration

# inventory - High Availability production deployment

[automationcontroller]
controller1.example.com
controller2.example.com
controller3.example.com

[automationcontroller:vars]
peers=execution_nodes

[automationhub]
hub.example.com

[execution_nodes]
exec1.example.com receptor_listener_port=27199
exec2.example.com receptor_listener_port=27199
exec3.example.com receptor_listener_port=27199
exec4.example.com receptor_listener_port=27199

[database]
# External PostgreSQL - managed RDS or self-hosted HA cluster
pg-primary.example.com

[all:vars]
# Admin credentials
admin_password='{{ vault_admin_password }}'
pg_password='{{ vault_pg_password }}'

# Database connection
pg_host='pg-primary.example.com'
pg_port=5432
pg_database='awx'
pg_username='awx'
pg_sslmode='require'

# SSL certificates (from Let's Encrypt or corporate CA)
web_server_ssl_cert=/etc/ssl/certs/controller.crt
web_server_ssl_key=/etc/ssl/private/controller.key
web_server_ssl_cert_chain=/etc/ssl/certs/chain.crt

# Hub configuration
automationhub_admin_password='{{ vault_hub_password }}'
automationhub_pg_host='pg-primary.example.com'
automationhub_pg_database='automationhub'
automationhub_pg_username='automationhub'
automationhub_pg_password='{{ vault_hub_pg_password }}'

# Container registry
registry_username='admin'
registry_password='{{ vault_registry_password }}'

# Redis (for HA)
redis_mode='cluster'

Real-world configuration: This is similar to our production setup, with external managed PostgreSQL (AWS RDS) and Let's Encrypt certificates.

Step 4: SSL/TLS Certificate Setup

Never use HTTP for AAP in production. Always configure SSL/TLS.

Option 1: Self-Signed Certificates (Development Only)

# Generate self-signed certificate
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /tmp/controller.key \
  -out /tmp/controller.crt \
  -subj "/C=US/ST=State/L=City/O=Company/CN=controller.example.com"

# Set permissions
chmod 600 /tmp/controller.key
chmod 644 /tmp/controller.crt

Option 2: Let's Encrypt (Recommended for Internet-Facing)

# Install certbot
sudo dnf install -y certbot

# Obtain certificate (DNS or HTTP challenge)
sudo certbot certonly --standalone -d controller.example.com

# Certificates will be in:
# /etc/letsencrypt/live/controller.example.com/fullchain.pem
# /etc/letsencrypt/live/controller.example.com/privkey.pem

# Update inventory file:
# web_server_ssl_cert=/etc/letsencrypt/live/controller.example.com/fullchain.pem
# web_server_ssl_key=/etc/letsencrypt/live/controller.example.com/privkey.pem

Option 3: Corporate CA Certificate

# Use certificates from your organization's CA
# Copy cert, key, and chain files to server

# Update inventory:
# web_server_ssl_cert=/etc/ssl/certs/controller.crt
# web_server_ssl_key=/etc/ssl/private/controller.key
# web_server_ssl_cert_chain=/etc/ssl/certs/ca-chain.crt

Real-world practice: We use Let's Encrypt with automated renewal for external-facing controllers, and corporate CA for internal deployments.

Step 5: Run the Installation

# Navigate to installer directory
cd ansible-automation-platform-setup-bundle-2.4

# Verify inventory file syntax
ansible-playbook -i inventory --syntax-check

# Run preflight checks (optional but recommended)
ansible-playbook -i inventory preflight.yml

# Run the installation
./setup.sh

# Installation will:
# 1. Validate prerequisites
# 2. Configure database
# 3. Install AAP components
# 4. Configure networking and SSL
# 5. Start services

# Typical installation time: 15-30 minutes

Common installation output:

PLAY RECAP *****************************************************
controller.example.com     : ok=247  changed=98   unreachable=0    failed=0
database.example.com       : ok=56   changed=23   unreachable=0    failed=0

Installation completed successfully!
Access Automation Controller at: https://controller.example.com

Step 6: Post-Installation Verification

# Check service status
sudo systemctl status automation-controller

# Verify web access
curl -k https://controller.example.com
# Should return HTML (login page)

# Check database connectivity
sudo awx-manage check_db

# Verify Redis
redis-cli ping
# Should return: PONG

# Check logs if issues
sudo journalctl -u automation-controller -f

Initial Configuration

Step 1: First Login and Subscription Upload

# Access AAP web interface
https://controller.example.com

# Login with:
# Username: admin
# Password: (from inventory file admin_password)

# You'll be prompted to upload subscription manifest
# Upload the manifest_*.zip file from Red Hat

Screenshot workflow:

1. Login → Subscription page appears

2. Click "Browse" → Select manifest file

3. Click "Upload" → License information displayed

4. Verify node count matches subscription

Step 2: Configure Authentication

AAP supports multiple authentication backends.

LDAP/Active Directory Integration

# In AAP UI: Settings → LDAP
{
    "AUTH_LDAP_SERVER_URI": "ldap://ldap.example.com:389",
    "AUTH_LDAP_BIND_DN": "cn=ansible,ou=ServiceAccounts,dc=example,dc=com",
    "AUTH_LDAP_BIND_PASSWORD": "password",
    "AUTH_LDAP_USER_SEARCH": [
        "ou=Users,dc=example,dc=com",
        "SCOPE_SUBTREE",
        "(sAMAccountName=%(user)s)"
    ],
    "AUTH_LDAP_USER_DN_TEMPLATE": null,
    "AUTH_LDAP_USER_ATTR_MAP": {
        "first_name": "givenName",
        "last_name": "sn",
        "email": "mail"
    },
    "AUTH_LDAP_GROUP_SEARCH": [
        "ou=Groups,dc=example,dc=com",
        "SCOPE_SUBTREE",
        "(objectClass=group)"
    ],
    "AUTH_LDAP_GROUP_TYPE": "MemberDNGroupType",
    "AUTH_LDAP_REQUIRE_GROUP": "cn=AAP-Users,ou=Groups,dc=example,dc=com",
    "AUTH_LDAP_USER_FLAGS_BY_GROUP": {
        "is_superuser": "cn=AAP-Admins,ou=Groups,dc=example,dc=com"
    }
}

Real-world setup: Our LDAP integration allows all employees to login, but RBAC within AAP controls who can actually do anything.

SAML 2.0 Integration

# Settings → SAML
{
    "SOCIAL_AUTH_SAML_SP_ENTITY_ID": "https://controller.example.com/sso/metadata/saml/",
    "SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "-----BEGIN CERTIFICATE-----\n...",
    "SOCIAL_AUTH_SAML_SP_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...",
    "SOCIAL_AUTH_SAML_ORG_INFO": {
        "en-US": {
            "displayname": "Example Corp",
            "name": "example",
            "url": "https://www.example.com"
        }
    },
    "SOCIAL_AUTH_SAML_ENABLED_IDPS": {
        "okta": {
            "entity_id": "http://www.okta.com/exk...",
            "url": "https://example.okta.com/app/.../sso/saml",
            "x509cert": "-----BEGIN CERTIFICATE-----\n..."
        }
    }
}

Step 3: Create Organizations and Teams

# Using awx CLI (install: pip install awxkit)
awx organizations create --name "Engineering" --description "Engineering Team"
awx teams create --name "DevOps" --organization "Engineering"

# Or via API
curl -X POST https://controller.example.com/api/v2/organizations/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Engineering Team"
  }'

Step 4: Configure Project and First Inventory

# Via UI or API - create a project pointing to Git repo

Project:
  Name: "Infrastructure Playbooks"
  SCM Type: Git
  SCM URL: https://gitlab.example.com/ansible/infrastructure.git
  SCM Credential: GitLab-Readonly
  Update on Launch: true

Inventory:
  Name: "Production Servers"
  Organization: Engineering
  
  # Add hosts manually or use inventory source
  Source:
    Type: Amazon EC2
    Credential: AWS-ReadOnly
    Regions: us-east-1, us-west-2
    Instance Filters: tag:Environment=production

Backup and Recovery Configuration

Critical: Configure backups BEFORE you start using AAP in production.

What to Backup

Critical Data (must backup):
  - PostgreSQL database (all AAP state)
  - Inventory file (installation config)
  - /etc/tower/ directory (configuration files)
  - SECRET_KEY (encryption key for credentials)

Optional (nice to have):
  - Job logs and artifacts
  - Custom Execution Environments (if not in external registry)

Automated Database Backup Script

#!/bin/bash
# /usr/local/bin/backup-aap-database.sh

BACKUP_DIR="/backups/aap"
RETENTION_DAYS=30
DATE=$(date +%Y%m%d_%H%M%S)

# Backup PostgreSQL
pg_dump -h localhost -U awx -d awx -F c -f "$BACKUP_DIR/awx_${DATE}.dump"

# Backup Tower config
tar czf "$BACKUP_DIR/tower_config_${DATE}.tar.gz" /etc/tower/

# Cleanup old backups
find $BACKUP_DIR -name "*.dump" -mtime +$RETENTION_DAYS -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +$RETENTION_DAYS -delete

# Upload to S3 (optional)
aws s3 cp "$BACKUP_DIR/awx_${DATE}.dump" s3://aap-backups/

# Schedule via cron
# crontab -e
0 2 * * * /usr/local/bin/backup-aap-database.sh

Real-world practice: We backup to local disk and replicate to S3 with versioning enabled. Database backups are also handled by AWS RDS automated backups.

Disaster Recovery Test

Don't wait for a disaster to test recovery!

# Test restoration procedure

# 1. Restore database backup
pg_restore -h localhost -U awx -d awx_test /backups/aap/awx_20260105.dump

# 2. Restore configuration
tar xzf /backups/aap/tower_config_20260105.tar.gz -C /tmp/restore/

# 3. Verify SECRET_KEY matches
grep SECRET_KEY /etc/tower/conf.d/secret_key.py
grep SECRET_KEY /tmp/restore/etc/tower/conf.d/secret_key.py

# 4. Test access and verify data

Real-world lesson: We test recovery quarterly. The first test revealed our SECRET_KEY wasn't being backed up - credentials would have been unrecoverable!

Common Installation Issues and Solutions

Issue 1: Installation Fails - Insufficient Resources

Error:

TASK [Installing packages] ************************************
fatal: [controller.example.com]: FAILED! => {
  "msg": "Insufficient memory"
}

Solution:

# Check available resources
free -h
df -h

# AAP needs minimum 16 GB RAM
# Upgrade instance or adjust deployment

Issue 2: Database Connection Fails

Error:

TASK [check database connection] ******************************
fatal: could not connect to database

Solution:

# Verify PostgreSQL is running
sudo systemctl status postgresql

# Check firewall
sudo firewall-cmd --list-all
sudo firewall-cmd --add-port=5432/tcp --permanent
sudo firewall-cmd --reload

# Test connection
psql -h localhost -U awx -d awx

Issue 3: SSL Certificate Errors

Error: Browser shows "Not Secure" or certificate warnings

Solution:

# Verify certificate chain
openssl s_client -connect controller.example.com:443 -showcerts

# Check certificate expiration
openssl x509 -in /etc/ssl/certs/controller.crt -noout -dates

# Ensure full certificate chain in inventory
# web_server_ssl_cert_chain=/path/to/chain.crt

Issue 4: Execution Capacity Shows Zero

Error: No jobs execute, capacity = 0

Solution:

# Check execution nodes registration
awx-manage list_instances

# Verify receptor connectivity
receptor --node-id controller status

# Restart services
sudo systemctl restart automation-controller

Performance Tuning Post-Install

PostgreSQL Tuning

# /var/lib/pgsql/data/postgresql.conf

# Memory settings (for 32 GB RAM system)
shared_buffers = 8GB
effective_cache_size = 24GB
maintenance_work_mem = 2GB
work_mem = 64MB

# Connection settings
max_connections = 1000
superuser_reserved_connections = 3

# Write performance
wal_buffers = 16MB
checkpoint_completion_target = 0.9

# Restart PostgreSQL
sudo systemctl restart postgresql

Redis Optimization

# /etc/redis.conf

# Memory
maxmemory 4GB
maxmemory-policy allkeys-lru

# Persistence (can disable for cache use)
save ""

# Restart Redis
sudo systemctl restart redis

Key Takeaways

✅ Plan before installing - sizing, network, certificates ✅ Use containerized installation for new deployments ✅ Configure SSL/TLS from the start ✅ Set up authentication early (LDAP/SAML) ✅ Configure backups immediately - test restoration ✅ Document your configuration - especially inventory file ✅ Test disaster recovery before you need it

What's Next

With AAP installed and configured, the next article dives into Automation Controller basics - creating organizations, teams, projects, inventories, credentials, and running your first job template.

---

Next Article: Automation Controller Basics →

Additional Resources

• AAP Installation Guide

• Database Sizing Guide

• LDAP Configuration Examples

• Backup and Restore Procedures

---

Part of the Ansible Automation Platform 101 Series