I Have Been Writing Ansible Playbook for 5 Years. Here’s Why the stat Module Is Always Top of Mind

The iterative process indicates that we should get our proof of concept out of the door as fast as possible — I call that having a working role or playbook. Usually that playbook or role is only tested in one target machine in the development environment. And that gives us a clear understanding of that machine’s state.

It’s easy to overlook potential problems when we’re rushing or become complacent. However, various scenarios can arise when working with systems.

In this article, I want to caution about assumption that we, System Administrators and Engineers, often have — a blind trust that a file or directory is always present.

Now, imagine this: you’ve crafted an Ansible playbook to deploy a critical application across your company’s servers. Generally you’d test in the development environment in one or two target servers. The test went fine.

Next, you pushed it out to all development servers, and as expected, it’s a sweet roll out. The dev systems installation completed successfully.

But when you deploy it on the production servers, it’s total chaos.

What happened?

While Ansible is not a programming language, to work with with it successfully, it’s a good idea to keep in mind some programming best practices. Ultimately, the goal is to achieve consistent success and minimize errors. This means avoiding assumptions about the existence of files, directories, or variables throughout the system’s lifecycle.

Environments are constantly changing, and unexpected issues can arise. Fortunately, Ansible’s stat module provides a simple yet effective way to safeguard against these automation pitfalls.

Get file system status with the stat module

The stat module is part of the ansible-core and it gathers crucial information about files and directories. Information such as:

• Existence: Does it exist at all?

• Type: Is it a file, a directory, or something else?

• Permissions: Who can read, write, and execute it?

• Ownership: Who owns it?

• Size and Timestamps: How big is it, and when was it modified?

With this information, you can make informed decisions in your playbook, preventing those “but it worked in the dev servers!” moments.

A Simple Example

Let’s say you need to ensure a log file exists before configuring a service. Here’s how you’d use stat:

- name: Check if log file exists  
  ansible.builtin.stat:    
    path: /var/log/myapp.log  
  register: log_file

- name: Create log file if it does not exist  
  ansible.builtin.file:    
    path: /var/log/myapp.log    
    state: touch  
  when: not log_file.stat.exists

In this example, we use stat to check for /var/log/myapp.log and store the results in a variable called log_file. Then, we use a conditional (when) to create the file only if it doesn't exist.

Handling Error Gracefully

The stat module is particularly useful in these situations:

• Conditional Execution: Need to install a package only if a specific configuration file is present? stat can help you make that decision.

• Dynamic File Paths: Dealing with user-provided paths or files generated at runtime? Use stat with registered variables to handle the uncertainty.

• Error Handling: Want to gracefully handle missing files instead of crashing your playbook? stat lets you define alternative actions or display informative error messages.

I’ve decided to write this piece because I encounter this issue quite often. If the expectation is that the playbook will work in most servers and fail in some, then you have to do the due diligence to skip that specific step that’s incompatible with those failed servers.

Get More out of the stat Module.

stat isn't just about checking if something exists. It can provide a wealth of information to make your automation smarter:

• File Size: Need to ensure a downloaded file is the correct size? stat can tell you.

• Modification Time: Want to only copy a file if it’s newer than the existing one? stat can help you compare timestamps.

• Permissions: Need to verify that a file has the correct permissions before proceeding? stat can check that for you.

Best Practices and Tips

• Be proactive: Don’t assume anything about the file system. Use stat to verify your assumptions.

• Combine with other modules: Use stat in conjunction with modules like file, copy, and template for more robust automation.

• Read the Docs: The official Ansible documentation is your friend. Refer to it for detailed information about the stat module and its options.

To sum it up

Ansible’s stat module is a powerful tool for eliminating uncertainty about the file system. By proactively checking for files and directories, you can prevent automation disasters and create more reliable and robust playbook

.