The Complete Guide to Ansible Upgrade and Migration

Upgrading your Ansible environment is not something you can postpone indefinitely.

Eventually, outdated playbooks slow you down. Things break. Security risks emerge. What once worked perfectly becomes difficult to maintain or even understand.

If you are planning to move to Red Hat Ansible Automation Platform 2+ or simply upgrading your playbooks to a newer Ansible version, you are likely facing both technical uncertainty and operational pressure.

This guide consolidates everything you need in one place. It will help you understand how to approach upgrades, identify where the real complexity lies, and make the process faster, safer, and more predictable.

Why Ansible upgrades are challenging

On paper, upgrading seems straightforward. In reality, it rarely is. Over time, many things change:

• Modules are renamed or moved into collections
• Parameters are deprecated or restructured
• Best practices evolve
• Execution environments replace older setups

And the biggest challenge of all: you often do not know the original intent behind older playbooks. This makes upgrades less about syntax and more about interpretation.

Ansible versions explained: which version are you upgrading to?

Before you start, decide which version you’re upgrading to. Ansible comes in two packages, and they use different version numbers. ansible-core is the engine with the built-in modules, and it keeps the classic 2.x numbering, such as 2.19, 2.20 and 2.21. Ansible, the community package, is ansible-core plus a curated set of collections, and it has its own numbering, such as 12, 13 and 14. Ansible 14, the current release, runs on ansible-core 2.21.

A new ansible-core release ships every May and November, and only the three newest get fixes. If you’re on ansible-core 2.18 or older, including Ansible 2.9, your automation no longer receives security updates. Python is often the first blocker, so check the control node and the managed nodes before you upgrade. The official Ansible releases and maintenance page lists which Python versions each release supports.

Every major release can include breaking changes, and they add up. If you’re jumping several versions, read each porting guide between your current and target version, not only the last one.

What breaks between Ansible versions, with examples

The porting guides are long, but a few changes cause most upgrade failures. Here’s what they look like in real code.

Modules moved into collections and renamed

Since Ansible 2.10, most modules live in collections and need their fully qualified collection name (FQCN). Some were also renamed along the way, so searching the docs for the old name finds nothing.

# Before (Ansible 2.9) 
- openssl_certificate: 
    path: /etc/ssl/crt/app.crt 
 
# After 
- community.crypto.x509_certificate: 
    path: /etc/ssl/crt/app.crt

include replaced by include_tasks and import_tasks

The include keyword was removed in ansible-core 2.16. Use include_tasks to load a file at runtime, or import_tasks to load it when the playbook is parsed.

# Before 
- include: setup.yml 
 
# After 
- ansible.builtin.include_tasks: setup.yml 

Conditionals must return a real boolean (ansible-core 2.19)

A when: that returns a non-empty string or list used to count as true. Since ansible-core 2.19, it’s an error.

# Before 
when: services_to_restart 
 
# After 
when: services_to_restart | length > 0 

Facts as top-level variables (deprecated in ansible-core 2.20)

Variables like ansible_distribution will stop working by default in ansible-core 2.24. Use the ansible_facts dictionary instead, where the ansible_ prefix is dropped.

# Before 
when: ansible_distribution == "Ubuntu" 
 
# After 
when: ansible_facts['distribution'] == "Ubuntu" 

The 3 phases of a successful upgrade and migration

A smooth upgrade always follows the same pattern, which can be divided into three phases.

Phase 1: Plan your migration

Before making any changes to your playbooks, you need a clear plan. This includes:

• Understanding your current environment
• Defining your target architecture (AAP 2+)
• Aligning stakeholders and timelines
• Reviewing technical requirements
• Assessing your automation content

A structured planning phase helps you avoid delays, misalignment, and last-minute surprises. For more detailed breakdown of what to consider, read this guide on planning your upgrade:

👉 Ansible Automation Platform 2 Upgrade: Preparation and Planning

Phase 2: Upgrade your playbooks

This is where most teams get stuck. Playbooks written years ago often include:

• Deprecated modules
• Outdated parameters
• Missing collection references
• Implicit assumptions that no longer apply

There are several ways to address this:

• Basic checks such as syntax validation
• Linting tools to identify common issues
• Manual refactoring
• Automated analysis and fixes

A good starting point is to understand the available methods and when to use them:

👉 3 ways to update Ansible Playbooks to the latest version

The key takeaway: Manual upgrades do not scale well. The more playbooks you have, the more complexity increases.

Phase 3: Validate, test, and deploy

Once your playbooks are upgraded, you need to ensure everything works as expected. This includes:

• Preparing execution environments
• Testing in staging
• Validating functionality and security
• Rolling out to production

A structured process makes this phase predictable and repeatable:

👉 Automate your Ansible upgrade and migration process

A practical step-by-step upgrade workflow

Let us bring everything together into a simple workflow you can follow.

Step 1: Assess and scan your playbooks

Start by understanding what you have.

Some playbooks can be reused as they are. Some need small adjustments. Others require significant refactoring. Use tools to scan for:

• Deprecated modules
• Missing dependencies
• Version incompatibilities

Step 2: Automate what you can

This is where you achieve the greatest time savings. Automation tools can:

• Update syntax
• Fix fully qualified collection names
• Detect compatibility issues
• Highlight only what needs manual attention

Instead of reviewing everything manually, you focus only on what truly matters.

Step 3: Fix what automation cannot

Not everything can or should be automated. You still need to:

• Make decisions about behavior changes
• Update complex logic
• Resolve environment-specific issues

The difference is that now your effort is focused and efficient.

Step 4: Re-run checks and validate

Upgrades are iterative. Run your checks multiple times:

• After automated fixes
• After manual changes
• Before final validation

This helps catch small issues before they become production problems.

Step 5: Install dependencies and test

Make sure:

• Required collections are installed
• Execution environments are aligned
• Playbooks run correctly in check mode

Only then move to production.

See a complete upgrade example

If you want to see how this works in practice, including real errors and fixes, this step-by-step walkthrough shows the entire process:

👉 Upgrading Ansible Playbooks from 2.4 to 2.17

It demonstrates how a complex upgrade can shift from hours of manual work to a much faster, more structured process.

Common pitfalls to avoid

Across all upgrades, the same issues tend to arise.

• Ignoring deprecated modules until they break
• Missing collection dependencies
• Assuming default values remain unchanged
• Skipping proper validation
• Underestimating environment differences

These issues are not always obvious at first, but they are the main sources of delays and failures.

The modern approach to Ansible upgrades

The most effective teams today do not rely solely on manual upgrades. They combine:

• Linting tools for basic validation
• Automated analysis for deeper insights
• Targeted manual fixes where needed

This layered approach provides:

• Speed
• Accuracy
• Confidence

Instead of reacting to errors, you proactively manage the upgrade process.

What results can you expect

When you follow a structured and automated approach, the impact is significant.

• Faster upgrades
• Reduced manual effort
• Fewer errors and inconsistencies
• More reliable automation
• Easier future upgrades

Teams that adopt this approach move from reactive maintenance to scalable automation.

Start your upgrade with confidence

Upgrading Ansible Playbooks and migrating to AAP 2+ does not have to be overwhelming. With the right structure, tools, and approach, it becomes a predictable and manageable process. If you want to accelerate your upgrade, reduce risk, and ensure nothing is overlooked, the next step is simple.

Start by assessing your current playbooks or exploring how automation can help you move faster with less effort.

Make your upgrade smooth, efficient, and future-ready. Watch this webinar to learn how an enterprise company saved over 17,000 hours with automated upgrade and migration.

Frequently Asked Questions

How do I upgrade Ansible?

Create a new Python virtual environment and run pip install --upgrade ansible, or pip install --upgrade ansible-core if you manage collections yourself. Before you switch, scan your playbooks against the new version with a platform like Steampunk Spotter, which flags deprecated modules and breaking changes and fixes many of them automatically. Then install the collections your playbooks need and run them in check mode. Keep the old environment until the new one passes, so you can roll back.

How do I upgrade an Ansible collection?

Collections are versioned separately from ansible-core, so upgrade them on their own. Run ansible-galaxy collection install --upgrade community.general for a single collection, or ansible-galaxy collection install --upgrade -r requirements.yml for everything your project lists.

How do I upgrade to Ansible Automation Platform 2.x?

Follow Red Hat’s upgrade guide for your version. For AAP 2.7, RPM-based installations first have to move to a containerized or OpenShift deployment. Plan your playbooks separately, because each one has to run on the newer ansible-core inside an execution environment. Steampunk Spotter checks your playbooks against the target version before the migration, so you know what needs fixing up front.