Configuration

Overview

AWX provides extensive configuration options through settings files, environment variables, and the REST API. Configuration settings control system behavior, authentication, logging, capacity, and more.

Configuration Methods

Database Settings

AWX stores most configuration settings in the database, allowing runtime changes without restarts. Access settings via the REST API:

# View all setting categories
curl -X GET https://awx.example.org/api/v2/settings/ \
  -H "Authorization: Bearer <token>"

# View system settings
curl -X GET https://awx.example.org/api/v2/settings/system/ \
  -H "Authorization: Bearer <token>"

# Update a setting
curl -X PATCH https://awx.example.org/api/v2/settings/system/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"SCHEDULE_MAX_JOBS": 20}'

File-Based Settings

Settings defined in Python files take precedence over database settings. File-based settings are marked as read-only in the API. Location: /etc/tower/conf.d/*.py Example configuration file:

# /etc/tower/conf.d/custom.py
ALLOWED_HOSTS = ['awx.example.org', 'localhost']
DEBUG = False
SESSION_COOKIE_AGE = 3600

Environment Variables

Many settings can be configured via environment variables:

# Container group settings
export MY_POD_NAMESPACE=awx
export AWX_CONTAINER_GROUP_DEFAULT_JOB_LABEL=ansible_job

# Custom secret key
export TOWER_SECRET_KEY=<your-secret-key>

Key Configuration Settings

System Settings

SECRET_KEY

Location: /etc/tower/SECRET_KEY
Purpose: Encrypts sensitive data in the database (credentials, tokens, etc.)

# Generate a new secret key
python3 -c "import base64, os; print(base64.encodebytes(os.urandom(32)).decode().rstrip())"

# Store in file
echo "<generated-key>" > /etc/tower/SECRET_KEY
chmod 600 /etc/tower/SECRET_KEY

Changing SECRET_KEY requires re-encrypting all secrets in the database. Use the regenerate_secret_key management command.

ALLOWED_HOSTS

Default: []
Description: List of valid hostnames/domains for AWX

ALLOWED_HOSTS = ['awx.example.org', '*.internal.example.com']

TIME_ZONE

Default: 'UTC'
Description: System timezone

TIME_ZONE = 'America/New_York'

Session Settings

SESSION_COOKIE_AGE

Default: 1800 (30 minutes)
Description: Session lifetime in seconds

SESSION_COOKIE_AGE = 3600  # 1 hour

SESSIONS_PER_USER

Default: -1 (unlimited)
Description: Maximum concurrent sessions per user

SESSIONS_PER_USER = 5

SESSION_COOKIE_SECURE

Default: True
Description: Send session cookies only over HTTPS

SESSION_COOKIE_SECURE = True

Database Settings

PostgreSQL Configuration

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'awx',
        'USER': 'awx',
        'PASSWORD': os.environ.get('DATABASE_PASSWORD'),
        'HOST': 'postgres.example.org',
        'PORT': '5432',
        'ATOMIC_REQUESTS': True,
        'OPTIONS': {
            'sslmode': 'verify-full',
            'sslrootcert': '/etc/pki/tls/certs/ca-bundle.crt',
        },
    }
}

Connection Pool Settings

LISTENER_DATABASES = {
    'default': {
        'OPTIONS': {
            'keepalives': 1,
            'keepalives_idle': 5,
            'keepalives_interval': 5,
            'keepalives_count': 5,
        },
    }
}

Job Settings

JOB_EVENT_WORKERS

Default: 4
Description: Number of processes for processing job events

JOB_EVENT_WORKERS = 8  # Increase for high-throughput systems

JOB_EVENT_BUFFER_SECONDS

Default: 1
Description: Time to buffer events before database write

JOB_EVENT_BUFFER_SECONDS = 2

SCHEDULE_MAX_JOBS

Default: 10
Description: Maximum pending jobs from a single schedule

SCHEDULE_MAX_JOBS = 20

Task Manager Settings

START_TASK_LIMIT

Default: 100
Description: Maximum jobs to start per task manager cycle

START_TASK_LIMIT = 200

TASK_MANAGER_TIMEOUT

Default: 300 (5 minutes)
Description: Task manager timeout in seconds

TASK_MANAGER_TIMEOUT = 600  # 10 minutes

Logging Settings

LOG_ROOT

Default: /var/log/tower/
Description: Directory for AWX log files

LOG_ROOT = '/var/log/awx/'

Logging Configuration

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': '/var/log/tower/tower.log',
            'maxBytes': 1024 * 1024 * 100,  # 100 MB
            'backupCount': 10,
        },
    },
    'loggers': {
        'awx': {
            'handlers': ['file'],
            'level': 'INFO',
        },
    },
}

Proxy and Network Settings

PROXY_IP_ALLOWED_LIST

Default: []
Description: Trusted proxy IPs for X-Forwarded-For headers

PROXY_IP_ALLOWED_LIST = ['10.0.1.100', '10.0.1.101']
REMOTE_HOST_HEADERS = ['HTTP_X_FORWARDED_FOR', 'REMOTE_ADDR', 'REMOTE_HOST']

CSRF_TRUSTED_ORIGINS

Default: []
Description: Trusted origins for CSRF protection

CSRF_TRUSTED_ORIGINS = ['https://awx.example.org', 'https://awx-lb.example.org']

Execution Environment Settings

GLOBAL_JOB_EXECUTION_ENVIRONMENTS

Description: Default execution environments for jobs

GLOBAL_JOB_EXECUTION_ENVIRONMENTS = [
    {
        'name': 'Custom EE',
        'image': 'registry.example.org/ee:latest'
    }
]

CONTROL_PLANE_EXECUTION_ENVIRONMENT

Description: Execution environment for project updates

CONTROL_PLANE_EXECUTION_ENVIRONMENT = 'quay.io/ansible/awx-ee:latest'

Container Group Settings

AWX_CONTAINER_GROUP_K8S_API_TIMEOUT

Default: 10
Description: Kubernetes API timeout in seconds

export AWX_CONTAINER_GROUP_K8S_API_TIMEOUT=30

AWX_CONTAINER_GROUP_POD_PENDING_TIMEOUT

Default: "2h"
Description: Maximum time for pod to enter running state

AWX_CONTAINER_GROUP_POD_PENDING_TIMEOUT = "4h"

Configuration Best Practices

1. Use File-Based Settings for Critical Config

Store infrastructure settings in files to prevent accidental changes:

# /etc/tower/conf.d/production.py
DATABASES = {...}  # Database connection
ALLOWED_HOSTS = [...]  # Valid hostnames
SESSION_COOKIE_SECURE = True  # Security settings

2. Environment-Specific Configuration

Organize settings by environment:

/etc/tower/conf.d/
├── production.py      # Production-specific settings
├── database.py        # Database configuration
└── security.py        # Security settings

3. Secrets Management

Never commit secrets to version control
Use environment variables for sensitive data
Rotate SECRET_KEY regularly
Use external secret management (Vault, AWS Secrets Manager)

4. Configuration Version Control

Track non-sensitive configuration:

# Track configuration files
cd /etc/tower/conf.d
git init
git add *.py
git commit -m "Initial AWX configuration"

5. Validate Configuration Changes

Test settings before applying:

# Check for configuration errors
awx-manage check

# Test database connectivity
awx-manage check_db

# Validate migrations
awx-manage check_migrations

Management Commands

View Current Settings

# List all settings
awx-manage shell -c "from django.conf import settings; print(dir(settings))"

# Check specific setting
awx-manage shell -c "from django.conf import settings; print(settings.ALLOWED_HOSTS)"

Regenerate Secret Key

Re-encrypt all database secrets with a new key:

# Generate and apply new key
awx-manage regenerate_secret_key

# Use custom key from environment
export TOWER_SECRET_KEY=<new-key>
awx-manage regenerate_secret_key --use-custom-key

This operation is irreversible and affects all encrypted data. Backup your database first.

Database Management

# Check database connection
awx-manage check_db

# Run migrations
awx-manage migrate

# Create preload data
awx-manage create_preload_data

Troubleshooting

Setting Not Taking Effect

Check if setting is file-defined (read-only):

curl https://awx.example.org/api/v2/settings/system/ | jq '.SETTING_NAME'

Verify setting category:

curl https://awx.example.org/api/v2/settings/

Clear cache and restart services:

awx-manage shell -c "from django.core.cache import cache; cache.clear()"
systemctl restart awx-service

Database Connection Issues

# Test PostgreSQL connection
awx-manage check_db

# Check database settings
awx-manage shell -c "from django.conf import settings; print(settings.DATABASES)"

Permission Errors

# Verify file permissions
chown awx:awx /etc/tower/SECRET_KEY
chmod 600 /etc/tower/SECRET_KEY

# Check directory permissions
chown -R awx:awx /var/lib/awx
chmod -R 750 /var/lib/awx

Capacity Planning - Configure instance capacity
Security Configuration - Security hardening
Metrics Configuration - Monitoring setup
Backup and Restore - Data protection

​Overview

​Configuration Methods

​Database Settings

​File-Based Settings

​Environment Variables

​Key Configuration Settings

​System Settings

​SECRET_KEY

​ALLOWED_HOSTS

​TIME_ZONE

​Session Settings

​SESSION_COOKIE_AGE

​SESSIONS_PER_USER

​SESSION_COOKIE_SECURE

​Database Settings

​PostgreSQL Configuration

​Connection Pool Settings

​Job Settings

​JOB_EVENT_WORKERS

​JOB_EVENT_BUFFER_SECONDS

​SCHEDULE_MAX_JOBS

​Task Manager Settings

​START_TASK_LIMIT

​TASK_MANAGER_TIMEOUT

​Logging Settings

​LOG_ROOT

​Logging Configuration

​Proxy and Network Settings

​PROXY_IP_ALLOWED_LIST

​CSRF_TRUSTED_ORIGINS

​Execution Environment Settings

​GLOBAL_JOB_EXECUTION_ENVIRONMENTS

​CONTROL_PLANE_EXECUTION_ENVIRONMENT

​Container Group Settings

​AWX_CONTAINER_GROUP_K8S_API_TIMEOUT

​AWX_CONTAINER_GROUP_POD_PENDING_TIMEOUT

​Configuration Best Practices

​1. Use File-Based Settings for Critical Config

​2. Environment-Specific Configuration

​3. Secrets Management

​4. Configuration Version Control

​5. Validate Configuration Changes

​Management Commands

​View Current Settings

​Regenerate Secret Key

​Database Management

​Troubleshooting

​Setting Not Taking Effect

​Database Connection Issues

​Permission Errors

​Related Resources

Overview

Configuration Methods

Database Settings

File-Based Settings

Environment Variables

Key Configuration Settings

System Settings

SECRET_KEY

ALLOWED_HOSTS

TIME_ZONE

Session Settings

SESSION_COOKIE_AGE

SESSIONS_PER_USER

SESSION_COOKIE_SECURE

Database Settings

PostgreSQL Configuration

Connection Pool Settings

Job Settings

JOB_EVENT_WORKERS

JOB_EVENT_BUFFER_SECONDS

SCHEDULE_MAX_JOBS

Task Manager Settings

START_TASK_LIMIT

TASK_MANAGER_TIMEOUT

Logging Settings

LOG_ROOT

Logging Configuration

Proxy and Network Settings

PROXY_IP_ALLOWED_LIST

CSRF_TRUSTED_ORIGINS

Execution Environment Settings

GLOBAL_JOB_EXECUTION_ENVIRONMENTS

CONTROL_PLANE_EXECUTION_ENVIRONMENT

Container Group Settings

AWX_CONTAINER_GROUP_K8S_API_TIMEOUT

AWX_CONTAINER_GROUP_POD_PENDING_TIMEOUT

Configuration Best Practices

1. Use File-Based Settings for Critical Config

2. Environment-Specific Configuration

3. Secrets Management

4. Configuration Version Control

5. Validate Configuration Changes

Management Commands

View Current Settings

Regenerate Secret Key

Database Management

Troubleshooting

Setting Not Taking Effect

Database Connection Issues

Permission Errors

Related Resources