Projects and Inventories

Managing 15 Git Repositories and 300+ Hosts

When we hit 15 different Git repositories containing our Ansible playbooks and 300+ servers spread across AWS, Azure, and on-premises datacenters, our simple static inventory file approach collapsed.

Manual inventory maintenance consumed 4 hours weekly. Servers were added to AWS but forgotten in inventories. Dynamic inventory scripts ran locally but weren't centralized. Different teams had different inventory files that conflicted.

Implementing AAP's advanced project and inventory features changed everything. We consolidated 15 projects into organized SCM-backed resources, implemented cloud dynamic inventories that auto-sync every 5 minutes, created smart inventories for complex filtering, and built a single source of truth for all infrastructure.

Manual inventory maintenance: 4 hours/week → 0 hours/week. Inventory accuracy: 75% → 99%. Time saved: 200+ hours annually.

This article shares the project and inventory patterns that made it possible.

What You'll Learn

• Multi-repository project management strategies

• Git branch and tag workflows in AAP

• Collections and Execution Environments in projects

• Cloud dynamic inventory sources (AWS, Azure, GCP, VMware)

• Smart inventories with advanced filters

• Inventory plugins and custom sources

• Performance optimization for large inventories

• Inventory variable management at scale

Advanced Project Management

Multi-Environment Project Strategy

Pattern 1: Multiple Branches, Single Project

Project Configuration:
  Name: Infrastructure-Production
  SCM URL: https://github.com/company/ansible-infrastructure.git
  SCM Branch: main
  Update on Launch: true

Project Configuration:
  Name: Infrastructure-Staging
  SCM URL: https://github.com/company/ansible-infrastructure.git
  SCM Branch: staging
  Update on Launch: true

Pattern 2: Git Tags for Releases

Project Configuration:
  Name: Infrastructure-Release-1.0
  SCM Branch/Tag: refs/tags/v1.0.0
  Update on Launch: false  # Pinned to specific release

Pattern 3: Multiple Repositories

# Different repos for different concerns
Projects:
  - Name: Network-Automation
    SCM URL: https://github.com/company/network-playbooks.git
    
  - Name: Application-Deployments
    SCM URL: https://github.com/company/app-deploy.git
    
  - Name: Security-Hardening
    SCM URL: https://github.com/company/security-playbooks.git

Real-world implementation: We use Pattern 3 with separate repos per domain, and Pattern 1 within each repo for environment separation.

Collections in Projects

Modern Ansible uses Collections. AAP handles this elegantly.

requirements.yml in Project:

# requirements.yml in your Git repo
collections:
  - name: ansible.posix
    version: ">=1.5.0"
  
  - name: community.general
    version: ">=5.0.0"
  
  - name: amazon.aws
    version: ">=5.2.0"
  
  - name: azure.azcollection
    version: ">=1.15.0"
  
  # Private collection from Automation Hub
  - name: mycompany.infrastructure
    source: https://hub.example.com/api/galaxy/
    version: ">=2.0.0"

Project Configuration:

AAP Project Settings:
  Update on Launch: true
  Delete on Update: true
  
Process:
  1. AAP syncs Git repo
  2. Detects requirements.yml
  3. Installs collections into project environment
  4. Collections available to job runs

Real-world benefit: Collections auto-update from Automation Hub. No manual installation on execution nodes.

Execution Environments in Projects

Projects can specify required Execution Environment:

Job Template Configuration:
  Project: Network-Automation
  Execution Environment: network-ee:1.2
  
# This EE contains:
# - ansible-core 2.15
# - ansible.netcommon collection
# - napalm, paramiko libraries
# - Custom Python packages for network automation

Cloud Dynamic Inventories

AWS EC2 Inventory

Configuration:

Inventory Source:
  Name: AWS-Production-Servers
  Source: Amazon EC2
  Credential: AWS-ReadOnly-IAM
  Source Variables:
    regions:
      - us-east-1
      - us-west-2
      - eu-west-1
    filters:
      tag:Environment: production
      instance-state-name: running
    keyed_groups:
      - key: tags.Role
        prefix: role
      - key: tags.Application
        prefix: app
      - key: placement.availability_zone
        prefix: az
    compose:
      ansible_host: public_ip_address
  Update on Launch: Yes
  Overwrite: Yes
  Update Cache Timeout: 300  # 5 minutes

Resulting Inventory Groups:

# Auto-generated groups from tags
role_webserver:
  - ec2-instance-1
  - ec2-instance-2

app_wordpress:
  - ec2-instance-1

az_us_east_1a:
  - ec2-instance-1
  
# Host variables auto-populated:
ec2-instance-1:
  ansible_host: 54.123.45.67
  ec2_instance_type: t3.medium
  ec2_region: us-east-1
  tags:
    Environment: production
    Role: webserver
    Application: wordpress

Real-world AWS example:

# Our AWS inventory config
filters:
  tag:ManagedBy: ansible
  tag:Environment: production
  instance-state-name: running

keyed_groups:
  # Group by environment
  - key: tags.Environment
    prefix: env
  
  # Group by application
  - key: tags.Application
    prefix: app
  
  # Group by instance type
  - key: instance_type
    prefix: type

hostnames:
  - tag:Name
  - private-ip-address

Azure Resource Manager Inventory

Configuration:

Inventory Source:
  Name: Azure-Production-VMs
  Source: Microsoft Azure Resource Manager
  Credential: Azure-Service-Principal
  Source Variables:
    resource_groups:
      - production-*
      - webapp-prod-*
    locations:
      - eastus
      - westeurope
    tags:
      - Environment:production
    keyed_groups:
      - prefix: tag
        key: tags
      - prefix: location
        key: location
    hostvar_expressions:
      ansible_host: private_ipv4_addresses[0]
  Update on Launch: Yes
  Overwrite: Yes

Real-world Azure pattern:

# Resource group naming convention
production-networking-eastus
production-webservers-eastus
production-databases-westeurope

# Inventory automatically groups by:
location_eastus:
  - all eastus VMs
location_westeurope:
  - all westeurope VMs
tag_Environment_production:
  - all VMs with Environment=production tag

GCP Compute Inventory

Configuration:

Inventory Source:
  Name: GCP-Production
  Source: Google Compute Engine
  Credential: GCP-Service-Account
  Source Variables:
    projects:
      - my-production-project
    filters:
      - labels.environment=production
      - status=RUNNING
    zones:
      - us-central1-a
      - us-east1-b
    keyed_groups:
      - key: labels.role
        prefix: role
      - key: zone
        prefix: zone
    hostnames:
      - name
    compose:
      ansible_host: networkInterfaces[0].accessConfigs[0].natIP

VMware vCenter Inventory

Configuration:

Inventory Source:
  Name: VMware-Production
  Source: VMware vCenter
  Credential: vCenter-ReadOnly
  Source Variables:
    hostnames:
      - name
    filters:
      - summary.runtime.powerState == "poweredOn"
      - "'production' in customValue"
    properties:
      - name
      - guest.ipAddress
      - summary.runtime.powerState
      - customValue
    keyed_groups:
      - key: customValue.environment
        prefix: env

Real-world VMware insight: We use custom attributes in vCenter (Environment, Application, Owner) which automatically become inventory groups in AAP.

Smart Inventories

Smart Inventories are dynamic subsets of other inventories based on filters.

Creating Smart Inventories

Use Case: All Web Servers Across All Clouds

Smart Inventory:
  Name: All-WebServers
  Organization: Engineering
  Host Filter:
    role_webserver or
    tags.Role="webserver" or
    name__contains="web"
  
# This automatically includes:
# - AWS EC2 instances tagged Role=webserver
# - Azure VMs in role_webserver group
# - GCP instances with role label
# - VMware VMs with web in name

Advanced Smart Inventory Filters

Filter Syntax:

# Simple equality
name="web01"

# Contains
name__contains="web"

# Multiple conditions (OR)
role_webserver or role_application

# Multiple conditions (AND)
environment_production and role_database

# Negation
not environment_development

# Complex combinations
(role_webserver or role_app) and environment_production and not location_deprecated

Real-world smart inventories:

Production-Critical:
  Filter: environment_production and priority_critical
  Use: Emergency patching

Development-All:
  Filter: environment_development or environment_test
  Use: Mass updates safely

High-Memory-Servers:
  Filter: instance_type__contains="xlarge" or instance_type__contains="2xlarge"
  Use: Performance monitoring

Windows-Servers:
  Filter: ansible_os_family="Windows"
  Use: Windows-specific automation

Linux-Servers:
  Filter: ansible_os_family="RedHat" or ansible_os_family="Debian"
  Use: Linux-specific automation

Inventory Variables at Scale

Variable Precedence

# From lowest to highest precedence
1. Inventory variables (inventory-level)
2. Group variables (all groups)
3. Group variables (specific group)
4. Host variables (host-level)
5. Extra variables (job template)
6. Extra variables (prompt on launch)

Example:
  Inventory vars:    http_port: 80
  Group vars:        http_port: 8080
  Host vars:         http_port: 9090
  Extra vars:        http_port: 3000
  
  Result: http_port = 3000

Variable Organization Patterns

Pattern 1: Group Variables for Common Config

# Group: webservers
variables:
  http_port: 80
  ssl_port: 443
  max_connections: 1000
  nginx_version: "1.20"

Pattern 2: Host Variables for Specific Config

# Host: web01.example.com
variables:
  ansible_host: 10.0.1.10
  server_id: 1
  cache_size_mb: 2048

Pattern 3: Inventory Source Variables

# From AWS tags, automatically populated
variables:
  ec2_instance_type: t3.large
  ec2_region: us-east-1
  tags:
    Environment: production
    Application: frontend
    Owner: webteam

Pattern 4: Constructed Variables

# Use compose in inventory source
compose:
  ansible_host: public_ip_address
  data_center: "{{ placement.availability_zone }}"
  is_production: "{{ tags.Environment == 'production' }}"

Real-world variable strategy:

Group Variables:
  - Application-wide settings
  - Environment-specific config
  
Host Variables:
  - Server-specific config
  - Custom attributes
  
Inventory Source Variables:
  - Cloud metadata
  - Auto-discovered info
  
Job Template Extra Vars:
  - Run-time parameters
  - Version numbers
  - Feature flags

Performance Optimization

Large Inventory Best Practices

Challenge: 500+ host inventory taking 2 minutes to sync

Solution:

Inventory Source Configuration:
  Update Cache Timeout: 300  # Don't sync more than every 5 min
  
  # Use filters to reduce scope
  filters:
    instance-state-name: running  # Exclude stopped instances
    tag:ManagedBy: ansible       # Only managed servers
  
  # Limit regions
  regions:
    - us-east-1  # Only active region
  
  # Parallel updates
  Enable Concurrent Updates: Yes

Results:

• Sync time: 2 minutes → 15 seconds

• Host count: 800 → 520 (excluded irrelevant hosts)

• Job launch delay: Eliminated

Inventory Update Strategies

Strategy 1: Update on Launch

When: Job runs frequently (> 10/hour)
Update on Launch: Yes
Cache Timeout: 300

Benefit: Always current
Trade-off: Job launch delay

Strategy 2: Scheduled Updates

When: Job runs infrequently
Update on Launch: No
Schedule: Every 5 minutes

Benefit: Fast job launch
Trade-off: Might be slightly stale

Strategy 3: Manual Updates

When: Static or rarely changing
Update on Launch: No
Schedule: None

Benefit: Fastest
Trade-off: Manual sync required

Our approach: Scheduled updates every 5 minutes for cloud inventories, on-launch for critical inventories.

Custom Inventory Scripts

For sources AAP doesn't support natively:

Example: Custom CMDB Integration

#!/usr/bin/env python3
# custom_cmdb_inventory.py

import json
import requests

def get_cmdb_inventory():
    # Fetch from internal CMDB API
    response = requests.get(
        "https://cmdb.example.com/api/servers",
        headers={"Authorization": "Bearer TOKEN"}
    )
    
    servers = response.json()
    
    inventory = {
        "_meta": {"hostvars": {}},
        "all": {"hosts": []},
    }
    
    for server in servers:
        hostname = server["hostname"]
        inventory["all"]["hosts"].append(hostname)
        
        # Create groups by application
        app = server.get("application", "ungrouped")
        if app not in inventory:
            inventory[app] = {"hosts": []}
        inventory[app]["hosts"].append(hostname)
        
        # Set host variables
        inventory["_meta"]["hostvars"][hostname] = {
            "ansible_host": server["ip_address"],
            "environment": server["environment"],
            "owner": server["owner"],
            "application": server["application"]
        }
    
    return inventory

if __name__ == "__main__":
    print(json.dumps(get_cmdb_inventory(), indent=2))

AAP Configuration:

Inventory Source:
  Source: Sourced from a Project
  Project: Custom-Inventory-Scripts
  Inventory File: custom_cmdb_inventory.py
  Credential: CMDB-API-Token
  Update on Launch: No
  Scheduled Update: Every 15 minutes

Key Takeaways

✅ Multi-project strategy - separate by concern or environment ✅ Cloud dynamic inventories - auto-sync from AWS/Azure/GCP ✅ Smart inventories - powerful filtering across all sources ✅ Variable precedence - understand the hierarchy ✅ Performance optimization - cache, filter, schedule wisely ✅ Custom scripts - integrate any data source

What's Next

The next article covers Job Templates and Workflows - building parameterized automation, visual workflow designer, approval gates, and complex multi-step automation orchestration.

---

Next Article: Job Templates and Workflows →

Additional Resources

• Dynamic Inventory Guide

• Smart Inventory Documentation

• Inventory Plugins

---

Part of the Ansible Automation Platform 101 Series