Overview
This section documents our opinionated approach to writing, organizing, and operating Ansible code. It covers naming conventions, structural guidelines, state management, and everyday best practices that every engineer working on infrastructure automation should follow.
Project Structure
A consistent directory layout makes repositories predictable and reduces onboarding friction. All Ansible projects must follow the structure below.
Naming Conventions
Consistent naming reduces cognitive load and makes automation discoverable across the organization.
Module Design
Modules are the building blocks of Ansible automation. Following consistent guidelines for writing and consuming modules keeps playbooks readable and maintainable.
State Management
Unlike Terraform, Ansible does not maintain a state file. Correctness depends on idempotent task design and understanding how Ansible determines whether a change is needed.
Variables & Outputs
Ansible has a complex variable precedence system. Understanding and respecting that system prevents subtle bugs and makes playbooks easier to reason about.
Provider Configuration
Ansible connects to managed nodes and cloud APIs through a combination of inventory configuration, connection plugins, and collection-specific settings. This page covers the canonical way to configure each.
Anti-Patterns
The following patterns are banned in this codebase. Each one introduces fragility, security risk, or maintenance burden that outweighs any short-term convenience.
CI/CD Pipeline
All Ansible changes must pass through a CI/CD pipeline before reaching any managed environment. No playbook may be run manually against staging or production.
Security & Compliance
Security is not optional. Every Ansible project must follow the controls below from day one.