Ansible – Solving my Documentation Pet Peeve

September 13, 2021
10:30 am

Charl Barkhuizen | Marketing Plug-in

I'm the marketing plug-in and resident golden retriever at LSD Open. You can find me making a lot of noise about how cool Cloud Native is or catch me at a Tech This Out Meetup event!

As a DevOps engineer, I find myself far more comfortable iterating over lists or writing conditional statements than finding fancy words to document my code. Since Ansible is designed to be easy to read and understand, you can almost get away without documenting anything…except ‘Variables’.

As with any code, there are best practices that make it easier for teams to collaborate on the same code like keeping your playbooks readable and following conventions for naming variables. One thing that I see skipped over all too often is documenting your variables so that the next person that wants to use them understands what is going on.

Ansible has a staggering amount of places where you can define variables, each having its own precedence rules over the other. If another DevOps engineer has to inherit your plays and roles, it can be time-consuming to find and figure out all the variables.

In an effort to help you to properly document variables, I personally recommend three things:

1. CREATE A ‘README.MD’ FILE THAT EXPLAINS NOT ONLY HOW TO USE THE PLAY OR ROLE, BUT ALSO EVERY SINGLE VARIABLE USED, THEIR LOCATION, PURPOSE AND WHETHER I CAN EXPECT TO HAVE THE VARIABLE VALUE OVERWRITTEN.

Vars:
Name: “{{ home_address }}”
Location: ./roles/defaults/main.yml
Overwrite: true
Purpose: used in the jinja2 template, customer_info.j2
This is a default variable with a low precedence designed to be
overwritten by variables defined in your playbook.

2. ADD COMMENTS IN YOUR PLAYS AND ROLES WHEREVER YOU DECLARE A VARIABLE.

# file: group_vars/all
# For data synchronisation from the server to localhost
local_source_folder: /users/sitedev
remote_production_folder: /home/site/prod
# app name to look for in the local registry
app_name: dingbat
# image name to search for in the local image registry
image_name: “wingman/{{ app_name }}”
# version to search for in the local image registry
version: 4

3. FINALLY, TRY TO MINIMIZE WHERE YOU DECLARE YOUR VARIABLES.

The fewer places they are declared in, the easier it will be for the next person to find and keep track of them. These are some easy ways to document your variables and solves a pet peeve of mine. Do you have any documentation tips? Please share them with me in the comments below!

QUICK LINKS

Home
About us
Contact us
Newsletter
Blog
Careers

Facebook-square Linkedin-in X-twitter Youtube Instagram Github

Get in Touch

Click on the button below to start a conversation with LSD Open:

Click here

SUPPORT

24/7 Support
Submit a Ticket

Privacy Policy
Terms of Service
Cookies Policy

Charl Barkhuizen | Marketing Plug-in

QUICK LINKS

Get in Touch

SUPPORT

LSD Open | Copyright 2026| All rights reserved.

South Africa | United Arab Emirates (UAE) | Mauritius