AAP Configuration as Code Demo

📖 Table of Contents

• 🧐 What is This Tool?
• ✨ Why Use "Configuration as Code" (CaSC)?
• 🚀 Core Features
• ⚙️ How It Works
• 🛠️ Prerequisites
• 🏁 Step 1: Setup & Configuration
• 👟 Step 2: Usage / Examples
  • Exporting Configuration
  • Importing Configuration
• 💡 Tips and Advanced Usage
  • Environment vars.yml
• 📚 Documentation
• 🤝 Contributing
• 📦 Supported AAP Versions
• 📜 License

🧐 What is This Tool?

This project is a set of Ansible playbooks and helper scripts designed to help you manage your Ansible Automation Platform (AAP) setup like code.

It has two primary functions:

1. EXPORT: Read the current configuration from your AAP instance (like Job Templates, Credentials, Inventories, Projects, etc.) and save them as human-readable YAML files.
2. IMPORT: Take those YAML configuration files and apply them to an AAP instance, automatically creating or updating resources to match what's in the files.

This process is often called Configuration as Code (CaSC).

✨ Why Use "Configuration as Code" (CaSC)?

If you're new to CaSC, here's why it's so powerful:

• Version Control: You can store your entire AAP configuration in Git. This lets you see a full history of who changed what and when.
• Migration: Easily move your setup from one environment to another (e.g., from a 'test' server to a 'production' server).
• Consistency: Ensure your 'dev' and 'prod' environments are configured identically, reducing "it worked in test" problems.
• Disaster Recovery: If a server fails, you can rebuild it and re-apply your configuration from code in minutes.
• Auditing & Review: You can use "Pull Requests" to review and approve changes to your AAP configuration before they are applied.

🚀 Core Features

• Export from AAP: Dumps your live AAP configuration into structured YAML files.
• Import to AAP: Configures an AAP instance based on your YAML files.
• Version-Aware: Includes different logic for different versions of AAP (e.g., 2.4, 2.5, 2.6).
• Granular Control: Uses Ansible tags to let you export or import only specific pieces of your configuration (e.g., just controller_projects or eda_credentials).

⚙️ How It Works

This tool provides two main wrapper scripts, export.sh and import.sh, which are the easiest way to get started.

These scripts are user-friendly wrappers for the underlying Ansible playbooks (import_export.yml in export or import mode). They automatically:

1. Read your environment's AAP version from orgs_vars/<org_name>/<env_name>/vars.env.
2. Read your environment's credentials from an encrypted Ansible Vault.
3. Validate your command-line tags against the version-specific list in script_vars/<version>/.
4. Run the playbook using ansible-playbook by default (with versioned collections from collections/<version>/), or ansible-navigator with an Execution Environment if you pass --navigator.

You don't need to be an Ansible expert to use them, but you do need the prerequisite tools installed.

🛠️ Prerequisites

Before you begin, you must have the following installed on your local machine:

1. Ansible (for ansible-playbook, the default): Used with versioned collections in collections/<version>/. Install collections per AAP version with ./install_collections.sh (see Tips).
2. Bash 4.3+: Required for script features (associative arrays and namerefs).
3. Git: To clone this repository.

Optional (for Execution Environment runs): If you prefer to run with ansible-navigator and an EE, you need ansible-navigator and Podman or Docker. You must create the Execution Environments yourself (e.g. build or pull images that include the required collections and dependencies). You must also update the config so the scripts use your EE: set the execution_environment variable in the version-specific script vars file (see Using ansible-navigator (EE) below). Then pass --navigator to export.sh or import.sh.

🏁 Step 1: Setup & Configuration

1. Clone this repository:

   git clone https://github.com/lennysh/aap-casc-demo.git
   cd aap-casc-demo

2. Run the Initialization Script:
   This tool now includes an interactive script to get you started. Run the start_here.sh script and provide an organization name and environment name (e.g., OCP0Lab and my_prod).

   chmod +x start_here.sh
   ./start_here.sh OCP0Lab my_prod

3. What This Script Does:
   The start_here.sh script will automatically:

   • Create the organization directory if it doesn't exist (e.g., orgs_vars/OCP0Lab/).
   • Ask you to select an AAP version (e.g., 2.6, 2.5) for this environment.
   • Create the full directory structure: orgs_vars/OCP0Lab/my_prod/imports and orgs_vars/OCP0Lab/my_prod/exports.
   • Create the common directory: orgs_vars/OCP0Lab/common/ for shared configurations.
   • Save your version choice to orgs_vars/OCP0Lab/my_prod/vars.env.
   • Copy templates/vars.yml to orgs_vars/OCP0Lab/my_prod/vars.yml (export/import behavior options; see Environment vars.yml below).
   • Copy the templates/vault.yml to orgs_vars/OCP0Lab/my_prod/vault.yml.
   • Encrypt the new vault.yml using ansible-vault. (It will ask you to create a new vault password.)
   • Open the new vault.yml in your editor so you can add your AAP hostname and credentials.

4. (Optional) Edit Your Vault Later:
   If you need to edit your encrypted vault file again later, you can use the vault-edit.sh script:

   chmod +x vault-edit.sh
   ./vault-edit.sh OCP0Lab my_prod

👟 Step 2: Usage / Examples

The two main scripts are ./export.sh and ./import.sh. You must make them executable first:

chmod +x export.sh import.sh

Exporting Configuration

This command reads from your AAP instance and saves the files locally. Note that you no longer need to provide the version number.

• Command: ./export.sh <org_name> <environment_name> [--playbook|--navigator] [options]
• Arguments:
  • <org_name>: The name of your organization (e.g., OCP0Lab, TAMLab, HomeLab).
  • <environment_name>: The name of your config directory (e.g., my_prod, AAP25).
  • --playbook: Use ansible-playbook with versioned collections (default if CASC_USE_PLAYBOOK is set).
  • --navigator: Use ansible-navigator with the Execution Environment.
  • [options]:
    • -a or --all: Export all supported configurations.
    • -t "tag1,tag2": Export only the specific items you list.

Example: Export only Projects and Credentials

./export.sh OCP0Lab my_prod -t "controller_projects,controller_credentials"

• What this does:
  1. Reads orgs_vars/OCP0Lab/my_prod/vars.env to find this env is for AAP 2.6 (or whichever version you selected).
  2. Reads connection details from your encrypted orgs_vars/OCP0Lab/my_prod/vault.yml.
  3. Connects to your AAP instance.
  4. Saves the result into a new, timestamped directory: orgs_vars/OCP0Lab/my_prod/exports/ocp0lab_my_prod_export_YYYYMMDD_HHMMSS/. Export always produces both flat_version/ (single-file-per-resource YAML) and filetree_version/ (hierarchical layout). Which one you copy into imports for a later import is determined by the flatten_output setting in vars.yml (see Importing and Environment vars.yml).

Importing Configuration

This command reads from your local files and configures your AAP instance.

• Command: ./import.sh <org_name> <environment_name> [--playbook|--navigator] [options]
• Arguments:
  • <org_name> and <environment_name>: Same as export.
  • --playbook / --navigator: Same as export (default is playbook with versioned collections).
  • [options]:
    • -a or --all: Import all configurations from the environment's imports directory and the organization's common directory.
    • -t "tag1,tag2": Import only the specific items you list.

Example: Import only Projects

1. First, copy your config files: Before you can import, place your configuration files into the imports directory for your environment. Export always produces both flat_version/ and filetree_version/. Which of those two folders you copy from depends on the flatten_output setting in your environment's vars.yml (e.g. orgs_vars/OCP0Lab/my_prod/vars.yml):

   • flatten_output: true → Copy from the export's flat_version/ folder. When importing with flat layout, the import process reads every YAML file it finds recursively under imports (and under common when import_common is true). You can put YAML files in the root of imports/ or in any subfolders—both work.
   • flatten_output: false → Copy from the export's filetree_version/ folder. The import expects the filetree layout (e.g. controller_projects.d/, gateway_teams.d/, etc.); keep that structure when copying.

   # Example (flatten_output: true): copy from flat_version
   # cp orgs_vars/OCP0Lab/my_prod/exports/ocp0lab_my_prod_export_*/flat_version/controller_projects.yml orgs_vars/OCP0Lab/my_prod/imports/
   
   # Example (flatten_output: false): copy the filetree_version layout
   # cp -r orgs_vars/OCP0Lab/my_prod/exports/ocp0lab_my_prod_export_*/filetree_version/* orgs_vars/OCP0Lab/my_prod/imports/

2. Run the import script:

   ./import.sh OCP0Lab my_prod -t "controller_projects"

• What this does:
  1. Reads orgs_vars/OCP0Lab/my_prod/vars.env to get the version.
  2. Reads connection details from your encrypted orgs_vars/OCP0Lab/my_prod/vault.yml.
  3. Connects to your AAP instance.
  4. Applies only the configurations found that match the controller_projects tag from both the environment's imports directory and the organization's common directory.

💡 How to find all available tags?

The available tags are different for each AAP version and are now defined in the script_vars/ directory.

To see a full list of supported tags, run the script with just an organization name and environment name and no options (like -a or -t).

./export.sh OCP0Lab my_prod

This will show the Usage: help text, which dynamically lists all valid tags for the version associated with my_prod.

💡 Tips and Advanced Usage

ansible-playbook vs ansible-navigator

By default, the scripts use ansible-playbook with versioned collections from collections/<version>/ (e.g. collections/2.5/). You must install those collections first:

./install_collections.sh

To use ansible-navigator with an Execution Environment instead (no local collections), pass --navigator:

./export.sh OCP0Lab my_prod --navigator -t "controller_projects"

Using ansible-navigator (EE)

If you use --navigator, you are responsible for:

1. Creating the Execution Environments ahead of time. The scripts do not build or pull an EE for you. You must build (or otherwise obtain) container images that include the required Ansible collections and dependencies for each AAP version you use (e.g. infra.aap_configuration, infra.aap_configuration_extended, platform collections).

2. Pointing the scripts at your EE image. Set the execution_environment variable in the script vars file for each AAP version:

   • File: script_vars/<version>/vars.env (e.g. script_vars/2.5/vars.env, script_vars/2.6/vars.env).
   • Variable: execution_environment="<your-ee-image>" (e.g. a Quay or registry URL, or a local image name).
   • The scripts pass this value to ansible-navigator as --execution-environment-image. If execution_environment is missing when you run with --navigator, the scripts will error.

You can set the environment variable CASC_USE_PLAYBOOK to 1, true, or yes to prefer playbook; leave it unset or set to something else to prefer navigator. The --playbook and --navigator flags override the environment variable.

Avoid Typing Your Vault Password

By default, these scripts will securely prompt you for your vault password every time they run.

If you are in a trusted environment and want to avoid this, you can tell Ansible where to find your password in a file.

1. Create a simple text file containing only your vault password (e.g., .vault_pass.txt).

2. Secure this file: chmod 600 .vault_pass.txt

3. Tell Ansible to use it. You have two common options:

   • Option 1 (Environment Variable): Set an environment variable in your .bashrc or .zshrc:

      export ANSIBLE_VAULT_PASSWORD_FILE=.vault_pass.txt

   • Option 2 (ansible.cfg): Create a file named ansible.cfg (or cp ansible.cfg.example ansible.cfg) in this repository's root directory with the following content:

     [defaults]
     vault_password_file = .vault_pass.txt

4. Important: If you create this ansible.cfg file, make sure to add it to your .gitignore file so you don't accidentally commit it!

Environment vars.yml

Each environment has a vars.yml (e.g. orgs_vars/OCP0Lab/my_prod/vars.yml) created from templates/vars.yml. It controls import behavior and optional export filters. Export always produces both flat_version/ and filetree_version/; flatten_output only affects which layout import expects. All options in the template are:

📚 Documentation

Additional guides and references in the docs/ directory:

• Migration guide: Controller to AAP — Migrating from infra.controller_configuration (AAP 2.4 and earlier) to infra.aap_configuration / infra.aap_configuration_extended (AAP 2.5+).

🤝 Contributing

We welcome feedback and contributions.

• Feature requests, bugs, documentation: Open a GitHub Issue and choose the appropriate template (Feature request, Bug report, or Documentation).
• Questions, usage help, or chat: Join the Matrix channel.
• Code or doc changes: Open a Pull Request. The repo uses a pull request template to capture description, type of change, and a short checklist.

📦 Supported AAP Versions

This tool is explicitly designed to support multiple AAP versions by loading different tasks and tag lists for each. Supported versions include:

• AAP 2.6
• AAP 2.5
• AAP 2.4

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

Copyright (c) 2025 Lenny Shirley.