Worried Your Salt States Are a Liability? Migrate to Ansible!

If you’ve been using Salt for a while, you might be getting a little antsy.

Maybe you’re worried about Salt’s current owners continuing to support the project.

Or perhaps the only developer at your company who knew Salt moved on.

Or you just want to add a more marketable skill on your résumé.

Take that antsiness and turn it into some Ansible tasks. This guide shows you how.

Jude brings 35 years in software development and 7 years of hands-on Salt work to the Salt to Ansible Migration Guide. The book is a practical, recipe-driven walkthrough of a real Salt-to-Ansible migration. No padding, no toy examples. This is what a working migration really looks like.

Who’s This Book For?

Salt users porting their own states. You know Salt well. You don’t need it explained. You need someone to tell you how to do the same thing in Ansible, and where the gotchas are.

Users who inherited Salt code. You have a pile of .sls files and have to migrate them to Ansible. If you’re not already a Salt expert, the appendix has you covered with a concise Salt introduction.

Ansible beginners coming from Salt. The guide assumes you know Salt and Jinja2. It focuses on explaining the Ansible side: the restrictions, the idioms, and the places where Ansible deliberately does things differently.

What’s Covered

• Migration workflow: a step-by-step process from auditing your existing Salt repos through running Ansible in production, including how to handle emergency Salt fixes mid-migration.
• Major Salt/Ansible differences: SSH-based provisioning, YAML-first templating, task ordering issues, descriptive-only naming convention, host_vars vs. pillar files
• How to migrate Jinja2 code: variables, conditionals, loops, and macros, with side-by-side Salt and Ansible examples for each
• How to migrate Salt prerequisite attributes: watch_in, onlyif/unless, require/require_in, and order: last, with Ansible equivalents
• Over 50 migration recipes: a reference table covering the most common Salt states:
  • cmd.run (single command, shell commands, wget/curl)
  • file.directory, file.absent, file.exists, file.managed (5 variants), file.missing, file.recurse, file.replace, file.touch, file.symlink
  • pkg.installed, service.running, sysctl.present
  • user.present, git.cloned, git.latest
  • Converting Salt’s pillar, external pillar, and grains access to Ansible inventory lookups.
• Data validation: JSON Schema validation for host_vars data, argument_specs.yml for role arguments
• Ansible file layout: the full directory structure, annotated with the Salt version for each file

What You Won’t Get From the Online Documentation

The Ansible documentation is good, but it doesn’t tell you what you, as a Salt user, need to watch out for. For example:

• Replicating Salt’s file_tree external pillar lookup in Ansible
• Working around Ansible’s inability to loop over blocks
• Handling Ansible’s more limited use of Jinja2

This guide calls out those gotchas explicitly, with the context of someone who has already run into them.

About the Author

Jude has spent over 35 years in software development with the last 7 working with Salt, and the 7 years before that working with Puppet.

He wrote this guide while migrating his home lab infrastructure from Salt to Ansible. The guide was originally going to be a blog post, but then it ended up being over 60 pages.

Get the Book

Pay what you want for the Salt to Ansible Migration Guide on LeanPub and Gumroad.

You can download the table of contents and first few chapters free of charge.

First edition: January 2026. Covers Salt 3007.10 and Ansible 2.18.6.