Ansible is simple, flexible, and powerful. Like any powerful tool, there are many ways to use it, some better than others.
This document aims to gather good practices from the field of Ansible practitioners at Red Hat, consultants, developers, and others. And thus it strives to give any Red Hat employee, partner or customer (or any Ansible user) a guideline from which to start in good conditions their automation journey.
Those are opinionated guidelines based on the experience of many people. They are not meant to be followed blindly if they don’t fit the reader’s specific use case, organization or needs; there is a reason why they are called good and not best practices.
The reader of this document is expected to have working practice of Ansible. If they are new to Ansible, the Getting started section of the official Ansible documentation is a better place to start.
This document covers not just coding practices but the full spectrum of Ansible-related good practices, including naming conventions, AAP configuration management, Git workflow and versioning, testing, CI/CD, and security. It is organized into four parts:
Part I — Foundations covers the overarching principles, structural decisions, and naming conventions that should be established before writing any code.
Part II — Developing Ansible Content covers good practices for writing roles, collections, playbooks, inventories, plugins, and general coding style.
Part III — AAP and Configuration as Code covers managing Ansible Automation Platform configuration declaratively through Git.
Part IV — Lifecycle and Operations covers the operational aspects of automation: Git workflow, testing, CI/CD, promotion, and security.
Each section is made of guidelines, one sentence hopefully easy to remember, followed by description, rationale and examples. The HTML version of this document makes the content collapsable so that all guidelines can be seen at once in a very overseeable way, for the reader to uncollapse the content of guidelines they are interested in.
A rationale is expected for each good practice, with a reference if applicable. It is really helpful to know not only how to do certain things, but why to do them in this way. It will also help with further revisions of the standards as some items may become obsolete or no longer applicable. If the reason is not included, there is a risk of keeping items that are no longer applicable, or alternatively blindly removing items that should be kept. It also has great educational value for understanding how things actually work (or how they don’t).
This document is published to https://redhat-cop.github.io/automation-good-practices/, it is open source and its source code is maintained at https://github.com/redhat-cop/automation-good-practices/.