Ansible AAP 2.6 Architecture: Gateway, Controller, Hub

Introduction

Ansible Automation Platform (AAP) 2.6 is Red Hat's enterprise automation solution, built from a set of integrated components that handle everything from content management to event-driven automation. The most significant architectural change in AAP 2.x is the Platform Gateway — a unified entry point that fronts all platform services. This article covers every component, how they interact, deployment topologies, and when to use each piece.

Architecture Overview

                         ┌─────────────────────────┐
                         │    Platform Gateway      │
                         │  (Single Entry Point)    │
                         │  • Authentication/AuthZ  │
                         │  • Unified UI            │
                         │  • Service Routing       │
                         └────────┬────────────────┘
                                  │
              ┌───────────────────┼───────────────────┐
              │                   │                     │
   ┌──────────▼──────┐  ┌───────▼────────┐  ┌────────▼─────────┐
   │   Automation     │  │  Private       │  │  Event-Driven    │
   │   Controller     │  │  Automation    │  │  Ansible         │
   │                  │  │  Hub           │  │  Controller      │
   │  • Job Templates │  │  • Collections │  │  • Rulebooks     │
   │  • Workflows     │  │  • EE Images   │  │  • Event Sources │
   │  • Inventories   │  │  • Namespaces  │  │  • Actions       │
   │  • Credentials   │  │  • Signing     │  │  • Decision Envs │
   │  • RBAC          │  │               │  │                  │
   └────────┬─────────┘  └───────────────┘  └──────────────────┘
            │
   ┌────────▼─────────────────────────────┐
   │         Automation Mesh              │
   │  • Control Nodes ←→ Execution Nodes  │
   │  • Hop Nodes (network bridging)      │
   │  • Peer-to-peer mesh routing         │
   └────────┬─────────────────────────────┘
            │
   ┌────────▼─────────┐     ┌──────────────────────┐
   │  Execution        │     │  PostgreSQL           │
   │  Environments     │     │  (Shared Database)    │
   │  • Container      │     │  • Controller DB      │
   │    images with    │     │  • Hub DB             │
   │    dependencies   │     │  • EDA DB             │
   └───────────────────┘     │  • Gateway DB         │
                             └──────────────────────┘

Platform Gateway

The Platform Gateway is the most important architectural change in AAP 2.x. It provides:

Single entry point — one URL for all platform services
Unified authentication — SSO across Controller, Hub, and EDA
Authorization — centralized RBAC and organization management
Platform UI — unified dashboard for all components
Service routing — proxies requests to the appropriate backend

How It Works

User → https://aap.example.com → Platform Gateway
                                      │
                                      ├─→ /api/v2/          → Automation Controller
                                      ├─→ /api/galaxy/      → Automation Hub
                                      ├─→ /api/eda/         → EDA Controller
                                      └─→ /api/gateway/     → Gateway APIs

Before Platform Gateway, each component had its own URL and login. Now users authenticate once and access everything through a single interface.

Key Configuration

# Gateway environment variables
GATEWAY_MAIN_URL: https://aap.example.com
GATEWAY_AUTH_BACKEND: ldap     # ldap, saml, oidc, local
GATEWAY_SESSION_TIMEOUT: 28800 # 8 hours

Automation Controller

The traditional control plane for Ansible automation. Handles:

Capability	Description
Job Templates	Define what playbook runs on which inventory with which credentials
Workflows	Chain multiple job templates with conditional logic
Inventories	Static and dynamic inventory sources (AWS, Azure, VMware, etc.)
Credentials	Encrypted storage for SSH keys, cloud tokens, vault passwords
RBAC	Role-based access control — who can run what, where
Scheduling	Cron-like job scheduling
Notifications	Email, Slack, webhook notifications on job events
Job Execution	Orchestrates playbook runs across Automation Mesh
Surveys	Prompt users for variables at launch time
Instance Groups	Assign jobs to specific execution capacity pools

Job Template Example

# Equivalent API call to create a job template
POST /api/v2/job_templates/
{
  "name": "Deploy Web Application",
  "inventory": 1,
  "project": 3,
  "playbook": "deploy.yml",
  "credential": 5,
  "execution_environment": 2,
  "ask_variables_on_launch": true,
  "extra_vars": "---\nenv: production"
}

Automation Mesh

Automation Mesh separates control capacity from execution capacity, enabling distributed automation across networks, sites, and security zones.

Node Types

Node Type	Role	Description
Control Node	Control plane	Runs Controller services, dispatches jobs
Execution Node	Worker	Runs playbooks inside Execution Environments
Hop Node	Relay	Routes traffic between control and execution nodes across network boundaries
Hybrid Node	Both	Acts as both control and execution (small deployments)

Mesh Topology Examples

Simple (Small Team)

Control Node ←→ Execution Node

Multi-Site (Enterprise)

┌─ Data Center A ─────────────┐     ┌─ Data Center B ─────────────┐
│  Control Node 1              │     │  Execution Node 3           │
│  Control Node 2              │     │  Execution Node 4           │
│  Execution Node 1            │     │                             │
│  Execution Node 2            │     └────────────▲────────────────┘
└──────────┬───────────────────┘                  │
           │                                       │
           └──────► Hop Node ◄────────────────────┘
                  (DMZ / firewall)

Edge Computing

Central DC                     Remote Sites
┌──────────────┐              ┌──────────────┐
│ Control Node │──Hop Node──►│ Exec Node    │  (Factory floor)
└──────────────┘     │        └──────────────┘
                     │        ┌──────────────┐
                     └──────►│ Exec Node    │  (Retail store)
                              └──────────────┘

Mesh Configuration

# inventory file for AAP installer
[automationcontroller]
controller1.example.com
controller2.example.com

[execution_nodes]
exec1.example.com
exec2.example.com
exec3.dc2.example.com peers=hop1.example.com

[automationcontroller:vars]
node_type=control

[execution_nodes:vars]
node_type=execution

[hop_nodes]
hop1.example.com

[hop_nodes:vars]
node_type=hop

Event-Driven Ansible (EDA) Controller

EDA connects external event sources to Ansible automation — when something happens, Ansible responds automatically.

Core Concepts

Concept	Description
Event Source	External system generating events (webhook, Kafka, alertmanager, etc.)
Rulebook	YAML file defining conditions and actions
Condition	Logic that matches incoming events
Action	What to do when conditions match (run playbook, debug, etc.)
Decision Environment	Container image with rulebook dependencies
Activation	A running instance of a rulebook

Rulebook Example

---
- name: Respond to webhook events
  hosts: all
  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000

  rules:
    - name: Restart failed service
      condition: event.payload.alert == "service_down"
      action:
        run_job_template:
          name: "Restart Service"
          organization: "Default"
          job_args:
            extra_vars:
              service_name: "{{ event.payload.service }}"
              target_host: "{{ event.payload.host }}"

    - name: Scale up on high CPU
      condition: event.payload.metric == "cpu" and event.payload.value > 90
      action:
        run_job_template:
          name: "Scale Application"
          organization: "Default"

Common Event Sources

Source Plugin	Use Case
`ansible.eda.webhook`	Generic HTTP webhooks
`ansible.eda.kafka`	Kafka topic events
`ansible.eda.alertmanager`	Prometheus alerts
`ansible.eda.aws_sqs_queue`	AWS SQS messages
`ansible.eda.url_check`	URL monitoring
`ansible.eda.file_watch`	File system changes

Private Automation Hub / HA Automation Hub

The content layer for AAP — a private, on-premise registry for:

Certified Collections — synced from Red Hat CDN
Custom Collections — your organization's internal content
Community Collections — curated from Galaxy
Execution Environment Images — container images for job execution
Collection/Container Signing — cryptographic signing for content integrity

High Availability

HA Automation Hub provides:

Multiple Hub instances behind a load balancer
Shared object storage (S3, Azure Blob, or shared filesystem)
Database replication
No single point of failure for content delivery

Content Approval Workflow

Developer uploads collection
        │
        ▼
  Staging Repository
        │
        ▼
  Admin reviews + approves
        │
        ▼
  Published Repository ← Automation Controller pulls from here

Automation Execution Environments (EEs)

Execution Environments are container images that package:

ansible-core
Ansible collections
Python dependencies
System packages

Why EEs?

Before (virtualenvs)	After (EEs)
Python dependency conflicts	Isolated containers per job
Drift between environments	Immutable, versioned images
Manual dependency management	Defined in `execution-environment.yml`
Hard to reproduce	Built with `ansible-builder`

Building a Custom EE

# execution-environment.yml
---
version: 3
dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

images:
  base_image:
    name: registry.redhat.io/ansible-automation-platform-25/ee-minimal-rhel9:latest

additional_build_steps:
  append_final:
    - RUN pip install --upgrade pip

# Build the EE
ansible-builder build --tag my-custom-ee:1.0 --container-runtime podman

# Push to Private Automation Hub
podman push my-custom-ee:1.0 ah.example.com/my-custom-ee:1.0

Ansible Galaxy

The public community hub for Ansible content:

Collections — community-maintained modules, plugins, roles
Roles — standalone reusable automation units
Free and open — anyone can publish

In AAP, Galaxy serves as a fallback source when content isn't available in Private Automation Hub.

Automation Content Navigator (ansible-navigator)

A TUI (terminal user interface) for developing and testing Ansible content:

# Run a playbook inside an EE
ansible-navigator run site.yml --eei my-custom-ee:1.0 --mode stdout

# Explore an EE's contents
ansible-navigator images --eei my-custom-ee:1.0

# Browse collection docs
ansible-navigator collections

# Replay a previous run
ansible-navigator replay artifact.json

Mode	Description
`--mode interactive`	TUI with navigation (default)
`--mode stdout`	Traditional ansible-playbook output

PostgreSQL

All AAP components share a PostgreSQL database (or separate databases):

Database	Used By
`awx`	Automation Controller
`automationhub`	Private Automation Hub
`eda`	Event-Driven Ansible Controller
`gateway`	Platform Gateway

Requirements

PostgreSQL 15+ (AAP 2.6)
Minimum 20 GB storage for Controller
Separate database instances recommended for production
HA via streaming replication or managed PostgreSQL (RDS, Azure Database)

Deployment Topologies

Single Node (Development/Lab)

All components on one server:

[automationcontroller]
aap.example.com

[automationhub]
aap.example.com

[automationeda]
aap.example.com

[automationgateway]
aap.example.com

[database]
aap.example.com

Distributed (Production)

[automationgateway]
gateway1.example.com
gateway2.example.com

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

[automationhub]
hub1.example.com
hub2.example.com

[automationeda]
eda1.example.com

[execution_nodes]
exec1.example.com
exec2.example.com
exec3.example.com

[database]
db1.example.com

Containerized (OpenShift)

AAP deploys as an Operator on OpenShift:

apiVersion: aap.ansible.com/v1alpha1
kind: AnsibleAutomationPlatform
metadata:
  name: aap
  namespace: aap
spec:
  controller:
    replicas: 2
  hub:
    replicas: 2
  eda:
    replicas: 1
  gateway:
    replicas: 2

Component Interaction Summary

From	To	Purpose
User	Gateway	Authentication, UI, API access
Gateway	Controller	Job management, inventory, credentials
Gateway	Hub	Collection browsing, EE management
Gateway	EDA	Rulebook activations, event monitoring
Controller	Mesh	Dispatch jobs to execution nodes
Controller	Hub	Pull collections and EE images
EDA	Controller	Trigger job templates from events
Exec Nodes	Hub	Pull EE images at job runtime
All	PostgreSQL	Persistent data storage

Ansible Automation Platform Enterprise Guide
Ansible Execution Environments
Integrate Private Automation Hub with Automation Controller
Containerized Ansible Automation Platform 2024
Ansible Event-Driven Automation Controller

Conclusion

AAP 2.6 is built from ten integrated components: Platform Gateway provides the single entry point with unified authentication; Automation Controller handles job orchestration; Automation Mesh distributes execution across sites; Event-Driven Ansible adds reactive automation; Private Automation Hub manages content and EE images; Execution Environments provide isolated, reproducible runtime; and PostgreSQL stores all persistent data. Understanding how these components interact is essential for planning deployment topology, sizing infrastructure, and operating AAP at enterprise scale.

Ansible AAP 2.6 Architecture: Gateway, Controller, Hub

Introduction

Architecture Overview

Platform Gateway

How It Works

Key Configuration

Automation Controller

Job Template Example

Automation Mesh

Node Types

Mesh Topology Examples

Mesh Configuration

Event-Driven Ansible (EDA) Controller

Core Concepts

Rulebook Example

Common Event Sources

Private Automation Hub / HA Automation Hub

High Availability

Content Approval Workflow

Automation Execution Environments (EEs)

Why EEs?

Building a Custom EE

Ansible Galaxy

Automation Content Navigator (ansible-navigator)

PostgreSQL

Requirements

Deployment Topologies

Single Node (Development/Lab)

Distributed (Production)

Containerized (OpenShift)

Component Interaction Summary

Related Articles

Conclusion