Project

General

Profile

Wiki » Ansible »

Ansible Directory Structure & Conventions

Overview

This document provides a detailed reference for the organization of the Ansible repository. It explains the purpose of each directory, outlines naming conventions, and includes a visual diagram to help contributors quickly understand the hierarchy.

Top-Level Files

File Purpose
README.md Project overview and usage instructions
all.yml Global variables applied across inventories and playbooks
ansible.cfg Core Ansible configuration (defaults, paths, privilege escalation)
dynamic_inventory.py Script for generating dynamic inventory data
generate_role_docs.py Utility to auto-generate documentation for roles

Key Directories

Directory Purpose
filter_plugins/ Custom Jinja2 filters for inventory and playbook logic
inventory/ Environment- and service-specific inventories (e.g., dns, grafana, jenkins)
playbooks/ Task orchestration grouped by service or platform
roles/ Modular building blocks for automation (service-specific setups)
roles/global/ Shared tasks and variables used across multiple roles
roles/users/ User and group management tasks

Examples

  • Inventory: inventory/dns → DNS server definitions
  • Playbook: playbooks/provision_vm.yml → VM provisioning workflow
  • Role: roles/nginx_setup/ → Configures Nginx reverse proxy

Naming Conventions

To ensure clarity and maintainability, the following conventions are applied:

  • Inventories: lowercase, named after service/environment (dns, jenkins, truenas)
  • Playbooks: action + target (provision_vm.yml, deploy_vscode_server.yml)
  • Roles: service + _setup suffix (nginx_setup, redis_setup)
  • Scripts: snake_case (create_linux_master_inventory.py)

Each role must include a README.md for documentation.

Visual Diagram

Here’s a simplified view of the repository hierarchy:

ansible/
├── ansible.cfg          # Core configuration
├── all.yml              # Global variables
├── inventory/           # Service & environment inventories
│   ├── dns/             # DNS servers
│   ├── jenkins/         # Jenkins nodes
│   └── ...
├── playbooks/           # Automation workflows
│   ├── provision_vm.yml # VM provisioning
│   ├── nginx/           # Reverse proxy setup
│   └── ...
├── roles/               # Modular service setups
│   ├── nginx_setup/     # Nginx role
│   ├── docker_setup/    # Docker role
│   └── ...
└── filter_plugins/      # Custom Jinja2 filters