AnsibleByExample

amazon.aws 12.0.0 Released - Breaking Changes, ansible-core 2.18+ Requirement and New Module Features

Advanced
2024-01-014By Luca Berton

Lesson 1 of 25 in AWS Automation

AWS with Ansible — full curriculum
  1. 1. AWS Basics for Ansible
  2. 2. Installing the amazon.aws Collection and boto3
  3. 3. AWS Credentials and Profiles: Safe Configuration
  4. 4. Your First AWS Playbook: Regions, Tags and Idempotency
  5. 5. AWS Dynamic Inventory with the aws_ec2 Plugin
  6. 6. Grouping and Filtering Hosts with keyed_groups and Filters
  7. 7. Provisioning EC2 Instances
  8. 8. AMIs and Launch Templates
  9. 9. Building VPC Networks with Ansible
  10. 10. Security Groups and Network Access Control
  11. 11. Elastic IPs and Load Balancers
  12. 12. S3 Buckets and Object Management
  13. 13. IAM Users, Roles and Policies
  14. 14. RDS Databases with Ansible
  15. 15. Route 53 DNS Automation
  16. 16. CloudWatch Monitoring and Alarms
  17. 17. Managing Secrets: Secrets Manager, SSM Parameter Store and Ansible Vault
  18. 18. Post-Provisioning Configuration with Roles
  19. 19. Bridging Provisioning and Configuration: add_host and wait_for
  20. 20. Auto Scaling Groups and Rolling Updates
  21. 21. Validating Infrastructure with Assertions and Health Checks
  22. 22. Error Handling and Rollback in AWS Playbooks
  23. 23. Structuring a Reusable AWS Automation Project
  24. 24. Cost Control and Teardown Playbooks
  25. 25. Capstone: Provision and Configure a Multi-Tier AWS Application
View path overview →

Introduction

amazon.aws is the core Ansible collection for managing AWS resources, providing modules such as ec2_instance, cloudformation, autoscaling_group, and the aws_ec2 inventory plugin, along with shared module_utils used by many other AWS-related collections. Version 12.0.0 has been published on Ansible Galaxy, moving up from 11.5.0, and it is a major release that introduces breaking changes to minimum requirements and removes several long-deprecated parameters.

Whats New

Breaking Changes and Requirements

The headline change in this release is a bump in minimum supported versions:

  • Minimum ansible-core requirement raised to >= 2.18.0, which in turn requires Python >= 3.11.
  • Minimum boto3 and botocore versions raised to 1.38.0.
  • Deprecated parameters placement_group and tenancy removed from the ec2_instance module.
  • Deprecated parameter template removed from the cloudformation module.

Anyone still running older ansible-core, Python, or boto3/botocore versions will need to upgrade their control node environment before pulling in amazon.aws 12.0.0, or pin to the 11.x series.

Module Refactoring and Bugfixes

This release also includes bugfixes for route53_zone and a round of internal refactoring across autoscaling, RDS, and ELB modules aimed at reducing cognitive complexity and standardizing error handling via decorator patterns (RDSErrorHandler, LookupErrorHandler).

Minor Changes

AreaChangeReference
CITest matrices updated against ansible-core 2.21, in addition to 2.18, 2.19, 2.20PR #3142
Collection depsAdded aiobotocore 2.23.0 as a dependency for event source pluginsPR #2952
autoscaling_groupRefactored to reduce complexity, improve error handling, replace manual wait loops with waiter-based implementationsPR #2938
autoscaling_groupStandardized return values with autoscaling_group_info via shared transformation logic in module_utilsPR #2938
autoscaling_group_infoSame refactor and waiter-based implementation as autoscaling_groupPR #2938
autoscaling_group_infoStandardized return values with autoscaling_groupPR #2938
aws_account_attributeAdded on_denied parameter (error default, skip, warn) to control behavior when access to account attributes is deniedPR #2914
aws_ec2 inventory pluginAdded availability_zone_id to the placement block in host variablesIssue #1550
aws_ec2 inventory pluginReduced cognitive complexity in hostname processing methods (SonarCloud code-smells)PR #2936
ec2_tagAdded resource_tags as an alias for tags, matching ec2_instance conventionPR #3085
elb_application_lbRefactored to reduce cognitive complexity and improve maintainabilityPR #2946
elb_application_lbAdded http_xff_header_processing_mode to control how the load balancer appends, preserves, or removes the X-Forwarded-For headerIssue #3098
Lookup pluginsCentralized LookupErrorHandler decorator pattern to reduce code duplicationPR #2914
Lookup pluginsUpdated deprecated text converter imports from ansible.module_utils._text to ansible.module_utils.common.text.convertersPR #2914
module_utils/_rds/apiAdded shared utility functions for DB parameter group operations, decorated with @RDSErrorHandlerPR #3065
module_utils/_rds/commonAdded DBParameterGroupNotFoundFault to the not-found error codes handled by RDSErrorHandlerPR #3065
module_utils/rdsAdded describe_db_clusters centralized wrapper with @RDSErrorHandler and @AWSRetry decoratorsPR #3065

How to Test

Before installing 12.0.0, verify that the control node meets the new minimum requirements: ansible-core >= 2.18.0, Python >= 3.11, and boto3/botocore >= 1.38.0.

# Check current ansible-core and Python versions
ansible --version
python3 --version

# Check current boto3/botocore versions
pip show boto3 botocore

# Install or upgrade amazon.aws to 12.0.0
ansible-galaxy collection install amazon.aws:12.0.0 --force

# Verify the installed version
ansible-galaxy collection list amazon.aws

# If needed, upgrade boto3/botocore to satisfy the new minimum
pip install --upgrade 'boto3>=1.38.0' 'botocore>=1.38.0'

# Run a quick sanity check against a playbook using ec2_instance_info
ansible-playbook -i inventory check_ec2.yml --check

Conclusion

Teams relying on ec2_instance with the now-removed placement_group or tenancy parameters, or on cloudformation with the template parameter, must update their playbooks before moving to 12.0.0. Everyone else should confirm ansible-core, Python, boto3, and botocore versions meet the new minimums, then test the upgrade in a non-production environment given the scope of the autoscaling, RDS, and ELB refactoring work included in this release.

All Tutorials