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
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
Task Manager Settings
START_TASK_LIMIT
Default: 100
Description: Maximum jobs to start per task manager cycle
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
