Skip to content

AAP Bridge

A production-grade Python tool for migrating Ansible Automation Platform (AAP) installations from one version to another, designed to handle large-scale migrations (e.g., 80,000+ hosts).

Key Features

  • Flexible Setup - Run AAP Bridge directly on the host or use the optional containerized CLI workflow
  • Web UI - Add a browser-based workflow for connections, previews, and migration runs with live log streaming
  • Bulk Operations - Leverages AAP bulk APIs for high-performance migrations
  • State Management - PostgreSQL-backed state tracking with checkpoint/resume capability
  • Idempotency - Safely resume interrupted migrations without creating duplicates
  • Professional Progress Display - Rich-based live progress with real-time metrics
  • Flexible Output Modes - Normal, quiet, CI/CD, and detailed modes
  • Comprehensive Logging - Structured logging with separate console and file levels
  • Split-File Export/Import - Automatic file splitting for large datasets

Architecture Overview

AAP Bridge follows an ETL (Export, Transform, Load) architecture. The CLI/TUI can run directly on the host or inside the optional containerized workflow, and the web UI layers a FastAPI engine plus React frontend on top of that core:

graph LR
    A[Source AAP<br/>2.3/2.4] -->|Export| B[AAP Bridge<br/>ETL Engine]
    B -->|Load| C[Target AAP<br/>2.6+]
    B <-->|State<br/>Management| D[(PostgreSQL<br/>State Database)]

    style A fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    style B fill:#fff9c4,stroke:#f57f17,stroke-width:3px
    style C fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style D fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px

Components:

  • Client Layer - HTTP clients for source AAP, target AAP, and HashiCorp Vault
  • Migration Layer - ETL pipeline with exporters, transformers, and importers
  • State Management - Database-backed progress tracking and ID mapping
  • CLI / TUI - User-friendly command-line interface for host or container use
  • Web UI / API - Optional FastAPI + React interface for browser-based runs

Migration Order

Resources are migrated in dependency order:

  1. Organizations, Labels, Users, Teams
  2. Credential Types, Credentials
  3. Execution Environments
  4. Inventories, Inventory Sources, Inventory Groups
  5. Hosts (bulk operations)
  6. Instances, Instance Groups
  7. Projects
  8. Job Templates, Workflows
  9. Schedules

License

This project is licensed under the GNU General Public License v3.0.

Support