diff options
Diffstat (limited to 'ansible_collections/amazon/aws/docs')
5 files changed, 1168 insertions, 37 deletions
diff --git a/ansible_collections/amazon/aws/docs/docsite/links.yml b/ansible_collections/amazon/aws/docs/docsite/links.yml index ce667b367..6bdcc680b 100644 --- a/ansible_collections/amazon/aws/docs/docsite/links.yml +++ b/ansible_collections/amazon/aws/docs/docsite/links.yml @@ -7,12 +7,12 @@ # functionality for your collection. edit_on_github: repository: ansible-collections/amazon.aws - branch: main + branch: stable-7 # If your collection root (the directory containing galaxy.yml) does not coincide with your # repository's root, you have to specify the path to the collection root here. For example, # if the collection root is in a subdirectory ansible_collections/community/REPO_NAME # in your repository, you have to set path_prefix to 'ansible_collections/community/REPO_NAME'. - path_prefix: '' + path_prefix: "" # Here you can add arbitrary extra links. Please keep the number of links down to a # minimum! Also please keep the description short, since this will be the text put on @@ -34,8 +34,8 @@ edit_on_github: communication: matrix_rooms: - topic: General usage and support questions - room: '#aws:ansible.im' + room: "#aws:ansible.im" irc_channels: - topic: General usage and support questions network: Libera - channel: '#ansible-aws' + channel: "#ansible-aws" diff --git a/ansible_collections/amazon/aws/docs/docsite/rst/CHANGELOG.rst b/ansible_collections/amazon/aws/docs/docsite/rst/CHANGELOG.rst index 6e07527c1..3e5dc1c2c 100644 --- a/ansible_collections/amazon/aws/docs/docsite/rst/CHANGELOG.rst +++ b/ansible_collections/amazon/aws/docs/docsite/rst/CHANGELOG.rst @@ -5,6 +5,557 @@ amazon.aws Release Notes .. contents:: Topics +v7.4.0 +====== + +Release Summary +--------------- + +This release brings several bugfixes and minor changes. It also introduces a deprecation for the ``iam_role_info`` plugin. + +Minor Changes +------------- + +- AnsibeAWSModule - added ``fail_json_aws_error()`` as a wrapper for ``fail_json()`` and ``fail_json_aws()`` when passed an ``AnsibleAWSError`` exception (https://github.com/ansible-collections/amazon.aws/pull/1997). +- iam_access_key - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_access_key_info - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_group - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_instance_profile - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_instance_profile_info - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_managed_policy - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_mfa_device_info - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_role - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_role_info - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_user - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). +- iam_user_info - refactored code to use ``AnsibleIAMError`` and ``IAMErrorHandler`` as well as moving shared code into module_utils.iam (https://github.com/ansible-collections/amazon.aws/pull/1998). + +Deprecated Features +------------------- + +- iam_role_info - in a release after 2026-05-01 paths must begin and end with ``/`` (https://github.com/ansible-collections/amazon.aws/pull/1998). + +Bugfixes +-------- + +- cloudwatchevent_rule - Fix to avoid adding quotes to JSON input for provided input_template (https://github.com/ansible-collections/amazon.aws/pull/1883). +- lookup/secretsmanager_secret - fix the issue when the nested secret is missing and on_missing is set to warn, the lookup was raising an error instead of a warning message (https://github.com/ansible-collections/amazon.aws/issues/1781). +- module_utils/elbv2 - Fix issue when creating or modifying Load balancer rule type authenticate-oidc using ``ClientSecret`` parameter and ``UseExistingClientSecret=true`` (https://github.com/ansible-collections/amazon.aws/issues/1877). + +v7.3.0 +====== + +Release Summary +--------------- + +The amazon.aws 7.3.0 release includes a number of minor bugfixes, some new features and improvements. + +Minor Changes +------------- + +- backup_plan - Let user to set ``schedule_expression_timezone`` for backup plan rules when when using botocore >= 1.31.36 (https://github.com/ansible-collections/amazon.aws/issues/1952). +- iam_user - refactored error handling to use a decorator (https://github.com/ansible-collections/amazon.aws/pull/1951). +- lambda - added support for using ECR images for the function (https://github.com/ansible-collections/amazon.aws/pull/1939). +- module_utils.errors - added a basic error handler decorator (https://github.com/ansible-collections/amazon.aws/pull/1951). +- rds_cluster - Add support for ServerlessV2ScalingConfiguration to create and modify cluster operations (https://github.com/ansible-collections/amazon.aws/pull/1839). +- s3_bucket_info - add parameter ``bucket_versioning`` to return the versioning state of a bucket (https://github.com/ansible-collections/amazon.aws/pull/1919). +- s3_object_info - fix exception raised when listing objects from empty bucket (https://github.com/ansible-collections/amazon.aws/pull/1919). + +Bugfixes +-------- + +- backup_plan - Fix idempotency issue when using botocore >= 1.31.36 (https://github.com/ansible-collections/amazon.aws/issues/1952). +- plugins/inventory/aws_ec2 - Fix failure when retrieving information for more than 40 instances with use_ssm_inventory (https://github.com/ansible-collections/amazon.aws/issues/1713). + +v7.2.0 +====== + +Release Summary +--------------- + +This release includes new features and a bugfix. + +Minor Changes +------------- + +- ec2_instance - Add support for modifying metadata options of an existing instance (https://github.com/ansible-collections/amazon.aws/pull/1918). +- iam_group - Basic testing of ``name`` and ``path`` has been added to improve error messages (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_group - ``group_name`` has been added as an alias to ``name`` for consistency with other IAM modules (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_instance_profile - Basic testing of ``name`` and ``path`` has been added to improve error messages (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_instance_profile - Basic testing of ``name`` and ``path`` has been added to improve error messages (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_instance_profile - attempting to change the ``path`` for an existing profile will now generate a warning, previously this was silently ignored (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_instance_profile - the ``prefix`` parameter has been renamed ``path`` for consistency with other IAM modules, ``prefix`` remains as an alias. No change to playbooks is required (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_instance_profile - the default value for ``path`` has been removed. New instances will still be created with a default path of ``/``. No change to playbooks is required (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_managed_policy - Basic testing of ``name`` and ``path`` has been added to improve error messages (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_managed_policy - ``description`` attempting to update the description now results in a warning, previously it was simply ignored (https://github.com/ansible-collections/amazon.aws/pull/1936). +- iam_managed_policy - ``policy`` is no longer a required parameter (https://github.com/ansible-collections/amazon.aws/pull/1936). +- iam_managed_policy - added support for tagging managed policies (https://github.com/ansible-collections/amazon.aws/pull/1936). +- iam_managed_policy - more consistently perform retries on rate limiting errors (https://github.com/ansible-collections/amazon.aws/pull/1936). +- iam_managed_policy - support for setting ``path`` (https://github.com/ansible-collections/amazon.aws/pull/1936). +- iam_managed_policy - the ``policy_description`` parameter has been renamed ``description`` for consistency with other IAM modules, ``policy_description`` remains as an alias. No change to playbooks is required (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_managed_policy - the ``policy_name`` parameter has been renamed ``name`` for consistency with other IAM modules, ``policy_name`` remains as an alias. No change to playbooks is required (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_role - Basic testing of ``name`` and ``path`` has been added to improve error messages (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_role - ``prefix`` and ``path_prefix`` have been added as aliases to ``path`` for consistency with other IAM modules (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_role - ``role_name`` has been added as an alias to ``name`` for consistency with other IAM modules (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_role - attempting to change the ``path`` for an existing profile will now generate a warning, previously this was silently ignored (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_role - the default value for ``path`` has been removed. New roles will still be created with a default path of ``/``. No change to playbooks is required (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_role_info - ``path`` and ``prefix`` have been added as aliases to ``path_prefix`` for consistency with other IAM modules (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_user - Basic testing of ``name`` and ``path`` has been added to improve error messages (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_user - ``user_name`` has been added as an alias to ``name`` for consistency with other IAM modules (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_user - add ``boundary`` parameter to support managing boundary policy on users (https://github.com/ansible-collections/amazon.aws/pull/1912). +- iam_user - add ``path`` parameter to support managing user path (https://github.com/ansible-collections/amazon.aws/pull/1912). +- iam_user - added ``attached_policies`` to return value (https://github.com/ansible-collections/amazon.aws/pull/1912). +- iam_user - refactored code to reduce complexity (https://github.com/ansible-collections/amazon.aws/pull/1912). +- iam_user_info - ``prefix`` has been added as an alias to ``path_prefix`` for consistency with other IAM modules (https://github.com/ansible-collections/amazon.aws/pull/1933). +- iam_user_info - the ``path`` parameter has been renamed ``path_prefix`` for consistency with other IAM modules, ``path`` remains as an alias. No change to playbooks is required (https://github.com/ansible-collections/amazon.aws/pull/1933). + +Bugfixes +-------- + +- iam_managed_policy - fixed an issue where only partial results were returned (https://github.com/ansible-collections/amazon.aws/pull/1936). + +v7.1.0 +====== + +Release Summary +--------------- + +This release brings some new features and several bugfixes. + +Minor Changes +------------- + +- autoscaling_group - minor PEP8 whitespace sanity fixes (https://github.com/ansible-collections/amazon.aws/pull/1846). +- ec2_ami_info - simplify parameters to ``get_image_attribute`` to only pass ID of image (https://github.com/ansible-collections/amazon.aws/pull/1846). +- ec2_eip - use ``ResourceTags`` to set initial tags upon creation (https://github.com/ansible-collections/amazon.aws/issues/1843) +- ec2_instance - add support for AdditionalInfo option when creating an instance (https://github.com/ansible-collections/amazon.aws/pull/1828). +- ec2_security_group - use ``ResourceTags`` to set initial tags upon creation (https://github.com/ansible-collections/amazon.aws/pull/1844) +- ec2_vpc_igw - use ``ResourceTags`` to set initial tags upon creation (https://github.com/ansible-collections/amazon.aws/issues/1843) +- ec2_vpc_route_table - use ``ResourceTags`` to set initial tags upon creation (https://github.com/ansible-collections/amazon.aws/issues/1843) +- ec2_vpc_subnet - the default value for ``tags`` has been changed from ``{}`` to ``None``, to remove tags from a subnet an empty map must be explicitly passed to the module (https://github.com/ansible-collections/amazon.aws/pull/1876). +- ec2_vpc_subnet - use ``ResourceTags`` to set initial tags upon creation (https://github.com/ansible-collections/amazon.aws/issues/1843) +- ec2_vpc_subnet - use ``wait_timeout`` to also control maximum time to wait for initial creation of subnets (https://github.com/ansible-collections/amazon.aws/pull/1848). +- iam_group - add support for setting group path (https://github.com/ansible-collections/amazon.aws/pull/1892). +- iam_group - adds attached_policies return value (https://github.com/ansible-collections/amazon.aws/pull/1892). +- iam_group - code refactored to avoid single long function (https://github.com/ansible-collections/amazon.aws/pull/1892). +- rds_instance_snapshot - minor PEP8 whitespace sanity fixes (https://github.com/ansible-collections/amazon.aws/pull/1846). + +Bugfixes +-------- + +- ec2_vpc_subnet - cleanly handle failure when subnet isn't created in time (https://github.com/ansible-collections/amazon.aws/pull/1848). +- s3_object - Fix typo that caused false deprecation warning when setting ``overwrite=latest`` (https://github.com/ansible-collections/amazon.aws/pull/1847). +- s3_object - when doing a put and specifying ``Content-Type`` in metadata, this module (since 6.0.0) erroneously set the ``Content-Type`` to ``None`` causing the put to fail. Fix now correctly honours the specified ``Content-Type`` (https://github.com/ansible-collections/amazon.aws/issues/1881). + +v7.0.0 +====== + +Release Summary +--------------- + +This major release brings a new set of supported modules that have been promoted from community.aws, several bugfixes, minor changes and deprecated features. We also dropped support for ``botocore<1.29.0`` and ``boto3<1.26.0``. Due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/), support for Python less than 3.7 by this collection was deprecated in release 6.0.0 and removed in this release. + +Major Changes +------------- + +- aws_region_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_region_info``. +- aws_s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_s3_bucket_info``. +- iam_access_key - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key``. +- iam_access_key_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key_info``. +- iam_group - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_group`` (https://github.com/ansible-collections/amazon.aws/pull/1755). +- iam_managed_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_managed_policy`` (https://github.com/ansible-collections/amazon.aws/pull/1762). +- iam_mfa_device_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_mfa_device_info`` (https://github.com/ansible-collections/amazon.aws/pull/1761). +- iam_password_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_password_policy``. +- iam_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role`` (https://github.com/ansible-collections/amazon.aws/pull/1760). +- iam_role_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role_info`` (https://github.com/ansible-collections/amazon.aws/pull/1760). +- s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.s3_bucket_info``. +- sts_assume_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.sts_assume_role``. + +Minor Changes +------------- + +- amazon.aws collection - apply isort code formatting to ensure consistent formatting of code (https://github.com/ansible-collections/amazon.aws/pull/1771). +- ec2_instance - add support for additional ``placement`` options and ``license_specifications`` in run instance spec (https://github.com/ansible-collections/amazon.aws/issues/1824). +- ec2_instance_info - add new parameter ``include_attributes`` to describe instance attributes (https://github.com/ansible-collections/amazon.aws/pull/1577). +- ec2_metadata_facts - use fstrings where appropriate (https://github.com/ansible-collections/amazon.aws/pull/1802). +- ec2_vpc_igw - Add ability to attach/detach VPC to/from internet gateway (https://github.com/ansible-collections/amazon.aws/pull/1786). +- ec2_vpc_igw - Add ability to change VPC attached to internet gateway (https://github.com/ansible-collections/amazon.aws/pull/1786). +- ec2_vpc_igw - Add ability to create an internet gateway without attaching a VPC (https://github.com/ansible-collections/amazon.aws/pull/1786). +- ec2_vpc_igw - Add ability to delete a vpc internet gateway using the id of the gateway (https://github.com/ansible-collections/amazon.aws/pull/1786). +- elb_application_lb_info - add new parameters ``include_attributes``, ``include_listeners`` and ``include_listener_rules`` to optionally speed up module by fetching less information (https://github.com/ansible-collections/amazon.aws/pull/1778). +- module_utils.botocore - migrate from vendored copy of LooseVersion to packaging.version.Version (https://github.com/ansible-collections/amazon.aws/pull/1587). +- rds_cluster - Add support for removing cluster from global db (https://github.com/ansible-collections/amazon.aws/pull/1705). +- rds_cluster - add support for another ``state`` choice called ``started``. This starts the rds cluster (https://github.com/ansible-collections/amazon.aws/pull/1647/files). +- rds_cluster - add support for another ``state`` choice called ``stopped``. This stops the rds cluster (https://github.com/ansible-collections/amazon.aws/pull/1647/files). +- route53 - add a ``wait_id`` return value when a change is done (https://github.com/ansible-collections/amazon.aws/pull/1683). +- route53_health_check - add support for a string list parameter called ``child_health_checks`` to specify health checks that must be healthy for the calculated health check (https://github.com/ansible-collections/amazon.aws/pull/1631). +- route53_health_check - add support for an integer parameter called ``health_threshold`` to specify the minimum number of healthy child health checks that must be healthy for the calculated health check (https://github.com/ansible-collections/amazon.aws/pull/1631). +- route53_health_check - add support for another ``type`` choice called ``CALCULATED`` (https://github.com/ansible-collections/amazon.aws/pull/1631). +- s3_object - Allow recursive copy of objects in S3 bucket (https://github.com/ansible-collections/amazon.aws/issues/1379). +- s3_object - use fstrings where appropriate (https://github.com/ansible-collections/amazon.aws/pull/1802). + +Breaking Changes / Porting Guide +-------------------------------- + +- The amazon.aws collection has dropped support for ``botocore<1.29.0`` and ``boto3<1.26.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/1763). +- amazon.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection wss been deprecated in release 6.0.0 and removed in release 7.0.0. (https://github.com/ansible-collections/amazon.aws/pull/1763). +- module_utils - ``module_utils.urls`` was previously deprecated and has been removed (https://github.com/ansible-collections/amazon.aws/pull/1540). +- module_utils._version - vendored copy of distutils.version has been dropped (https://github.com/ansible-collections/amazon.aws/pull/1587). + +Deprecated Features +------------------- + +- ec2_instance - deprecation of ``tenancy`` and ``placement_group`` in favor of ``placement`` attribute (https://github.com/ansible-collections/amazon.aws/pull/1825). + +Bugfixes +-------- + +- aws_ec2 inventory plugin - fix ``NoRegionError`` when no regions are provided and region isn't specified (https://github.com/ansible-collections/amazon.aws/issues/1551). +- ec2_instance - retry API call if we get ``InvalidInstanceID.NotFound`` error (https://github.com/ansible-collections/amazon.aws/pull/1650). +- ec2_vpc_route_table_info - default filters to empty dictionary (https://github.com/ansible-collections/amazon.aws/issues/1668). +- s3_bucket - fixes issue when deleting a bucket with unversioned objects (https://github.com/ansible-collections/amazon.aws/issues/1533). +- s3_object - fixed ``NoSuchTagSet`` error when S3 endpoint doesn't support tags (https://github.com/ansible-collections/amazon.aws/issues/1607). +- s3_object - fixes regression related to objects with a leading ``/`` (https://github.com/ansible-collections/amazon.aws/issues/1548). + +New Modules +----------- + +- ec2_import_image - Manage AWS EC2 import image tasks +- ec2_import_image_info - Gather information about import virtual machine tasks +- rds_global_cluster_info - Obtain information about Aurora global database clusters + +v6.5.0 +====== + +Release Summary +--------------- + +This release is the last planned minor release of ``amazon.aws`` prior to the release of 7.0.0. +It includes documentation fixes as well as minor changes and bug fixes for the ``ec2_ami`` and ``elb_application_lb_info`` modules. + + +Minor Changes +------------- + +- ec2_ami - add support for ``org_arns`` and ``org_unit_arns`` in launch_permissions (https://github.com/ansible-collections/amazon.aws/pull/1690). +- elb_application_lb_info - drop redundant ``describe_load_balancers`` call fetching ``ip_address_type`` (https://github.com/ansible-collections/amazon.aws/pull/1768). + +Bugfixes +-------- + +- elb_application_lb_info - ensure all API queries use the retry decorator (https://github.com/ansible-collections/amazon.aws/issues/1767). + +v6.4.0 +====== + +Release Summary +--------------- + +This release brings a new module named ``amazon.aws.ec2_key_info``, some documentation improvements, new features and bugfixes. + +Minor Changes +------------- + +- cloudformation - Add support for ``disable_rollback`` to update stack operation (https://github.com/ansible-collections/amazon.aws/issues/1681). +- ec2_key - add support for new parameter ``file_name`` to save private key in when new key is created by AWS. When this option is provided the generated private key will be removed from the module return (https://github.com/ansible-collections/amazon.aws/pull/1704). + +Bugfixes +-------- + +- backup_selection - ensures that updating an existing selection will add new ``Conditions`` if there previously were not any (https://github.com/ansible-collections/amazon.aws/pull/1701). + +New Modules +----------- + +- ec2_key_info - Gather information about EC2 key pairs in AWS + +v6.3.0 +====== + +Release Summary +--------------- + +This release brings some new features and several bugfixes. + +Minor Changes +------------- + +- rds_cluster - add support for another ``state`` choice called ``started``. This starts the rds cluster (https://github.com/ansible-collections/amazon.aws/pull/1647/files). +- rds_cluster - add support for another ``state`` choice called ``stopped``. This stops the rds cluster (https://github.com/ansible-collections/amazon.aws/pull/1647/files). +- route53 - add a ``wait_id`` return value when a change is done (https://github.com/ansible-collections/amazon.aws/pull/1683). +- route53_health_check - add support for a string list parameter called ``child_health_checks`` to specify health checks that must be healthy for the calculated health check (https://github.com/ansible-collections/amazon.aws/pull/1631). +- route53_health_check - add support for an integer parameter called ``health_threshold`` to specify the minimum number of healthy child health checks that must be healthy for the calculated health check (https://github.com/ansible-collections/amazon.aws/pull/1631). +- route53_health_check - add support for another ``type`` choice called ``CALCULATED`` (https://github.com/ansible-collections/amazon.aws/pull/1631). + +Bugfixes +-------- + +- ec2_vpc_route_table_info - default filters to empty dictionary (https://github.com/ansible-collections/amazon.aws/issues/1668). +- rds_cluster - Add ``AllocatedStorage``, ``DBClusterInstanceClass``, ``StorageType``, ``Iops``, and ``EngineMode`` to the list of parameters that can be passed when creating or modifying a Multi-AZ RDS cluster (https://github.com/ansible-collections/amazon.aws/pull/1657). +- rds_cluster - Allow to pass GlobalClusterIdentifier to rds cluster on creation (https://github.com/ansible-collections/amazon.aws/pull/1663). + +v6.2.0 +====== + +Release Summary +--------------- + +This release brings some new modules, features, and several bugfixes. + +Minor Changes +------------- + +- backup_selection - add validation and documentation for all conditions suboptions (https://github.com/ansible-collections/amazon.aws/pull/1633). +- ec2_instance - refactored ARN validation handling (https://github.com/ansible-collections/amazon.aws/pull/1619). +- iam_user - refactored ARN validation handling (https://github.com/ansible-collections/amazon.aws/pull/1619). +- module_utils.arn - add ``resource_id`` and ``resource_type`` to ``parse_aws_arn`` return values (https://github.com/ansible-collections/amazon.aws/pull/1619). +- module_utils.arn - added ``validate_aws_arn`` function to handle common pattern matching for ARNs (https://github.com/ansible-collections/amazon.aws/pull/1619). + +Bugfixes +-------- + +- backup_plan - Use existing ``scrub_none_values`` function from module_utils to remove None values from nested dicts in supplied params. Nested None values were being retained and causing an error when sent through to the boto3 client operation (https://github.com/ansible-collections/amazon.aws/pull/1611). +- backup_vault - fix error when updating tags on a backup vault by using the correct boto3 client methods for tagging and untagging backup resources (https://github.com/ansible-collections/amazon.aws/pull/1610). +- cloudwatchevent_rule - Fixes changed status to report False when no change has been made. The module had incorrectly always reported a change. (https://github.com/ansible-collections/amazon.aws/pull/1589) +- ec2_vpc_nat_gateway - adding a boolean parameter called ``default_create`` to allow users to have the option to choose whether they want to display an error message or create a NAT gateway when an EIP address is not found. The module (ec2_vpc_nat_gateway) had incorrectly failed silently if EIP didn't exist (https://github.com/ansible-collections/amazon.aws/issues/1295). +- ec2_vpc_nat_gateway - fixes to nat gateway so that when the user creates a private NAT gateway, an Elastic IP address should not be allocated. The module had inncorrectly always allocate elastic IP address when creating private nat gateway (https://github.com/ansible-collections/amazon.aws/pull/1632). +- lambda_execute - Fixes to the stack trace output, where it does not contain spaces between each character. The module had incorrectly always outputted extra spaces between each character. (https://github.com/ansible-collections/amazon.aws/pull/1615) +- module_utils.backup - get_selection_details fix empty list returned when multiple backup selections exist (https://github.com/ansible-collections/amazon.aws/pull/1633). + +New Modules +----------- + +- iam_instance_profile - manage IAM instance profiles +- iam_instance_profile_info - gather information on IAM instance profiles + +v6.1.0 +====== + +Release Summary +--------------- + +This release brings some new features, several bugfixes, and deprecated features are also included. + +Minor Changes +------------- + +- ec2_snapshot - Add support for modifying createVolumePermission (https://github.com/ansible-collections/amazon.aws/pull/1464). +- ec2_snapshot_info - Add createVolumePermission to output result (https://github.com/ansible-collections/amazon.aws/pull/1464). + +Deprecated Features +------------------- + +- s3_object - support for passing object keys with a leading ``/`` has been deprecated and will be removed in a release after 2025-12-01 (https://github.com/ansible-collections/amazon.aws/pull/1549). + +Bugfixes +-------- + +- autoscaling_group - fix ValidationError when describing an autoscaling group that has more than 20 target groups attached to it by breaking the request into chunks (https://github.com/ansible-collections/amazon.aws/pull/1593). +- autoscaling_group_info - fix ValidationError when describing an autoscaling group that has more than 20 target groups attached to it by breaking the request into chunks (https://github.com/ansible-collections/amazon.aws/pull/1593). +- ec2_instance - fix check_mode issue when adding network interfaces (https://github.com/ansible-collections/amazon.aws/issues/1403). +- ec2_metadata_facts - Handle decompression when EC2 instance user-data is gzip compressed. The fetch_url method from ansible.module_utils.urls does not decompress the user-data unless the header explicitly contains ``Content-Encoding: gzip`` (https://github.com/ansible-collections/amazon.aws/pull/1575). +- elb_application_lb - fix missing attributes on creation of ALB. The ``create_or_update_alb()`` was including ALB-specific attributes when updating an existing ALB but not when creating a new ALB (https://github.com/ansible-collections/amazon.aws/issues/1510). +- module_utils.acm - fixes list_certificates returning only RSA_2048 certificates (https://github.com/ansible-collections/amazon.aws/issues/1567). +- rds_instance - add support for CACertificateIdentifier to create/update rds instance (https://github.com/ansible-collections/amazon.aws/pull/1459). + +v6.0.1 +====== + +Release Summary +--------------- + +This is a patch release that includes some bug fixes for the aws_ec2 inventory plugin and the s3_bucket and s3_object modules. + +Bugfixes +-------- + +- aws_ec2 inventory plugin - fix ``NoRegionError`` when no regions are provided and region isn't specified (https://github.com/ansible-collections/amazon.aws/issues/1551). +- s3_bucket - fixes issue when deleting a bucket with unversioned objects (https://github.com/ansible-collections/amazon.aws/issues/1533). +- s3_object - fixes regression related to objects with a leading ``/`` (https://github.com/ansible-collections/amazon.aws/issues/1548). + +v6.0.0 +====== + +Release Summary +--------------- + +This release brings some new plugins and features. Several bugfixes, breaking changes and deprecated features are also included. The amazon.aws collection has dropped support for ``botocore<1.25.0`` and ``boto3<1.22.0``. Support for Python 3.6 has also been dropped. + +Minor Changes +------------- + +- Add github actions to run unit and sanity tests.(https://github.com/ansible-collections/amazon.aws/pull/1393). +- AnsibleAWSModule - add support to the ``client`` and ``resource`` methods for overriding the default parameters (https://github.com/ansible-collections/amazon.aws/pull/1303). +- CONTRIBUTING.md - refactors and adds to contributor documentation (https://github.com/ansible-collections/amazon.aws/issues/924) +- Refactor inventory plugins and add aws_rds inventory unit tests (https://github.com/ansible-collections/amazon.aws/pull/1218). +- Refactor module_utils/cloudfront_facts.py and add unit tests (https://github.com/ansible-collections/amazon.aws/pull/1265). +- The ``black`` code formatter has been run across the collection to improve code consistency (https://github.com/ansible-collections/amazon.aws/pull/1465). +- amazon.aws inventory plugins - additional refactorization of inventory plugin connection handling (https://github.com/ansible-collections/amazon.aws/pull/1271). +- amazon.aws lookup plugins - ``aws_access_key`` has been renamed to ``access_key`` for consistency between modules and plugins, ``aws_access_key`` remains as an alias. This change should have no observable effect for users outside the module/plugin documentation (https://github.com/ansible-collections/amazon.aws/pull/1225). +- amazon.aws lookup plugins - ``aws_profile`` has been renamed to ``profile`` for consistency between modules and plugins, ``aws_profile`` remains as an alias. This change should have no observable effect for users outside the module/plugin documentation (https://github.com/ansible-collections/amazon.aws/pull/1225). +- amazon.aws lookup plugins - ``aws_secret_key`` has been renamed to ``secret_key`` for consistency between modules and plugins, ``aws_secret_key`` remains as an alias. This change should have no observable effect for users outside the module/plugin documentation (https://github.com/ansible-collections/amazon.aws/pull/1225). +- amazon.aws lookup plugins - ``aws_security_token`` has been renamed to ``session_token`` for consistency between modules and plugins, ``aws_security_token`` remains as an alias. This change should have no observable effect for users outside the module/plugin documentation (https://github.com/ansible-collections/amazon.aws/pull/1225). +- amazon.aws modules - bulk update of import statements following various refactors (https://github.com/ansible-collections/amazon.aws/pull/1310). +- autoscaling_group - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- aws_account_attribute - the ``aws_account_attribute`` lookup plugin has been refactored to use ``AWSLookupBase`` as its base class (https://github.com/ansible-collections/amazon.aws/pull/1225). +- aws_ec2 inventory - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- aws_secret - the ``aws_secret`` lookup plugin has been refactored to use ``AWSLookupBase`` as its base class (https://github.com/ansible-collections/amazon.aws/pull/1225). +- aws_secret - the ``aws_secret`` lookup plugin has been renamed ``secretsmanager_secret``, ``aws_secret`` remains as an alias (https://github.com/ansible-collections/amazon.aws/pull/1225). +- aws_ssm - the ``aws_ssm`` lookup plugin has been refactored to use ``AWSLookupBase`` as its base class (https://github.com/ansible-collections/amazon.aws/pull/1225). +- aws_ssm - the ``aws_ssm`` lookup plugin has been renamed ``ssm_parameter``, ``aws_ssm`` remains as an alias (https://github.com/ansible-collections/amazon.aws/pull/1225). +- backup - Add logic for backup_selection* modules (https://github.com/ansible-collections/amazon.aws/pull/1530). +- bulk migration of ``%`` and ``.format()`` to fstrings (https://github.com/ansible-collections/amazon.aws/pull/1483). +- cloud module_utils - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- cloudtrail_info - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- cloudwatchlogs_log_group - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- docs_fragments - ``amazon.aws.boto3`` fragment now pulls the botocore version requirements from ``module_utils.botocore`` (https://github.com/ansible-collections/amazon.aws/pull/1248). +- docs_fragments - common parameters for modules and plugins have been synchronised and moved to ``amazon.aws.common.modules`` and ``amazon.aws.common.plugins`` (https://github.com/ansible-collections/amazon.aws/pull/1248). +- docs_fragments - region parameters for modules and plugins have been synchronised and moved to ``amazon.aws.region.modules`` and ``amazon.aws.region.plugins`` (https://github.com/ansible-collections/amazon.aws/pull/1248). +- ec2_ami - Extend the unit-test coverage of the module (https://github.com/ansible-collections/amazon.aws/pull/1159). +- ec2_ami - allow ``ImageAvailable`` waiter to retry when the image can't be found (https://github.com/ansible-collections/amazon.aws/pull/1321). +- ec2_ami_info - Add unit-tests coverage (https://github.com/ansible-collections/amazon.aws/pull/1252). +- ec2_eip - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- ec2_eni_info - Add unit-tests coverage (https://github.com/ansible-collections/amazon.aws/pull/1236). +- ec2_instance - avoid changing ``module.params`` (https://github.com/ansible-collections/amazon.aws/pull/1187). +- ec2_instance - updated to avoid manipulating ``module.params`` (https://github.com/ansible-collections/amazon.aws/pull/1337). +- ec2_security_group - added rule options to argument specifications to improve handling of inputs (https://github.com/ansible-collections/amazon.aws/pull/1214). +- ec2_security_group - refacter ``get_target_from_rule()`` (https://github.com/ansible-collections/amazon.aws/pull/1221). +- ec2_security_group - refactor rule expansion and add unit tests (https://github.com/ansible-collections/amazon.aws/pull/1261). +- ec2_snapshot - Reenable the integration tests (https://github.com/ansible-collections/amazon.aws/pull/1235). +- ec2_snapshot_info - Add unit-tests coverage (https://github.com/ansible-collections/amazon.aws/pull/1211). +- ec2_vpc_route_table - add support for Carrier Gateway entry (https://github.com/ansible-collections/amazon.aws/pull/926). +- ec2_vpc_subnet - retry fetching subnet details after creation if the first attempt fails (https://github.com/ansible-collections/amazon.aws/pull/1526). +- inventory aws ec2 - add parameter ``use_ssm_inventory`` allowing to query ssm inventory information for configured EC2 instances and populate hostvars (https://github.com/ansible-collections/amazon.aws/issues/704). +- inventory plugins - refactor cache handling (https://github.com/ansible-collections/amazon.aws/pull/1285). +- inventory plugins - refactor file verification handling (https://github.com/ansible-collections/amazon.aws/pull/1285). +- inventory_aws_ec2 integration tests - replace local module ``test_get_ssm_inventory`` by ``community.aws.ssm_inventory_info`` (https://github.com/ansible-collections/amazon.aws/pull/1416). +- kms_key_info - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- lambda - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- lambda - use common ``get_aws_account_info`` helper rather than reimplementing (https://github.com/ansible-collections/amazon.aws/pull/1181). +- lambda_alias - refactored to avoid passing around the complex ``module`` resource (https://github.com/ansible-collections/amazon.aws/pull/1336). +- lambda_alias - updated to avoid manipulating ``module.params`` (https://github.com/ansible-collections/amazon.aws/pull/1336). +- lambda_execute - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- lambda_info - updated to avoid manipulating ``module.params`` (https://github.com/ansible-collections/amazon.aws/pull/1336). +- lambda_layer_info - add support for parameter version_number to retrieve detailed information for a specific layer version (https://github.com/ansible-collections/amazon.aws/pull/1293). +- module_utils - move RetryingBotoClientWrapper into module_utils.retries for reuse with other plugin types (https://github.com/ansible-collections/amazon.aws/pull/1230). +- module_utils - move exceptions into dedicated python module (https://github.com/ansible-collections/amazon.aws/pull/1246). +- module_utils - refacter botocore version validation into module_utils.botocore for future reuse (https://github.com/ansible-collections/amazon.aws/pull/1227). +- module_utils.acm - Refactor ACMServiceManager class and add unit tests (https://github.com/ansible-collections/amazon.aws/pull/1273). +- module_utils.botocore - Add Ansible AWS User-Agent identification (https://github.com/ansible-collections/amazon.aws/pull/1306). +- module_utils.botocore - refactorization of ``get_aws_region``, ``get_aws_connection_info`` so that the code can be reused by non-module plugins (https://github.com/ansible-collections/amazon.aws/pull/1231). +- module_utils.policy - minor refacter of code to reduce complexity and improve test coverage (https://github.com/ansible-collections/amazon.aws/pull/1136). +- module_utils.s3 - Refactor get_s3_connection into a module_utils for S3 modules and expand module_utils.s3 unit tests (https://github.com/ansible-collections/amazon.aws/pull/1139). +- module_utils/botocore - added support to ``_boto3_conn`` for passing dictionaries of configuration (https://github.com/ansible-collections/amazon.aws/pull/1307). +- plugin_utils - Added ``AWSConnectionBase`` to support refactoring connection plugins (https://github.com/ansible-collections/amazon.aws/pull/1340). +- rds - AWS is phasing out aurora1. Integration tests use aurora2 (aurora-mysql) by default (https://github.com/ansible-collections/amazon.aws/pull/1233). +- rds_cluster - Split up the functional tests in smaller targets (https://github.com/ansible-collections/amazon.aws/pull/1175). +- rds_cluster_snapshot - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- rds_instance - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- rds_instance_info - Add unit-tests coverage (https://github.com/ansible-collections/amazon.aws/pull/1132). +- rds_instance_snapshot - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- rds_param_group - drop Python2 import fallbacks (https://github.com/ansible-collections/amazon.aws/pull/1513). +- route53_health_check - Drop deprecation warning (https://github.com/ansible-collections/community.aws/pull/1335). +- route53_health_check - minor fix for returning health check info while updating a Route53 health check (https://github.com/ansible-collections/amazon.aws/pull/1200). +- route53_health_check - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- route53_info - drop unused imports (https://github.com/ansible-collections/amazon.aws/pull/1462). +- s3_bucket - add support for S3 dualstack endpoint (https://github.com/ansible-collections/amazon.aws/pull/1305). +- s3_bucket - handle missing read permissions more gracefully when possible (https://github.com/ansible-collections/amazon.aws/pull/1406). +- s3_bucket - refactor S3 connection code (https://github.com/ansible-collections/amazon.aws/pull/1305). +- s3_object - refactor S3 connection code (https://github.com/ansible-collections/amazon.aws/pull/1305). +- s3_object - refactor main to reduce complexity (https://github.com/ansible-collections/amazon.aws/pull/1193). +- s3_object_info - minor linting fixes (https://github.com/ansible-collections/amazon.aws/pull/1181). +- s3_object_info - refactor S3 connection code (https://github.com/ansible-collections/amazon.aws/pull/1305). + +Breaking Changes / Porting Guide +-------------------------------- + +- The amazon.aws collection has dropped support for ``botocore<1.25.0`` and ``boto3<1.22.0``. Most modules will continue to work with older versions of the AWS SDK, however compatibility with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/1342). +- amazon.aws - compatibility code for Python < 3.6 has been removed (https://github.com/ansible-collections/amazon.aws/pull/1257). +- ec2_eip - the previously deprecated ``instance_id`` alias for the ``device_id`` parameter has been removed. Please use the ``device_id`` parameter name instead (https://github.com/ansible-collections/amazon.aws/issues/1176). +- ec2_instance - the default value for ``instance_type`` has been removed. At least one of ``instance_type`` or ``launch_template`` must be specified when launching new instances (https://github.com/ansible-collections/amazon.aws/pull/1315). +- ec2_vpc_dhcp_options - the ``new_options`` return value has been deprecated after being renamed to ``dhcp_config``. Please use the ``dhcp_config`` or ``dhcp_options`` return values (https://github.com/ansible-collections/amazon.aws/pull/1327). +- ec2_vpc_endpoint - the ``policy_file`` parameter has been removed. I(policy) with a file lookup can be used instead (https://github.com/ansible-collections/amazon.aws/issues/1178). +- ec2_vpc_net - the ``classic_link_enabled`` return value has been removed. Support for EC2 Classic networking was dropped by AWS (https://github.com/ansible-collections/amazon.aws/pull/1374). +- ec2_vpc_net_info - the ``classic_link_dns_status`` return value has been removed. Support for EC2 Classic networking was dropped by AWS (https://github.com/ansible-collections/amazon.aws/pull/1374). +- ec2_vpc_net_info - the ``classic_link_enabled`` return value has been removed. Support for EC2 Classic networking was dropped by AWS (https://github.com/ansible-collections/amazon.aws/pull/1374). +- module_utils.cloud - the previously deprecated ``CloudRetry.backoff`` has been removed. Please use ``CloudRetry.exponential_backoff`` or ``CloudRetry.jittered_backoff`` instead (https://github.com/ansible-collections/amazon.aws/issues/1110). + +Deprecated Features +------------------- + +- amazon.aws collection - due to the AWS SDKs Python support policies (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.8 by this collection is expected to be removed in a release after 2024-12-01 (https://github.com/ansible-collections/amazon.aws/pull/1342). +- amazon.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection has been deprecated and will be removed in release 7.0.0. (https://github.com/ansible-collections/amazon.aws/pull/1342). +- amazon.aws lookup plugins - the ``boto3_profile`` alias for the ``profile`` option has been deprecated, please use ``profile`` instead (https://github.com/ansible-collections/amazon.aws/pull/1225). +- docs_fragments - ``amazon.aws.aws_credentials`` docs fragment has been deprecated please use ``amazon.aws.common.plugins`` instead (https://github.com/ansible-collections/amazon.aws/pull/1248). +- docs_fragments - ``amazon.aws.aws_region`` docs fragment has been deprecated please use ``amazon.aws.region.plugins`` instead (https://github.com/ansible-collections/amazon.aws/pull/1248). +- docs_fragments - ``amazon.aws.aws`` docs fragment has been deprecated please use ``amazon.aws.common.modules`` instead (https://github.com/ansible-collections/amazon.aws/pull/1248). +- docs_fragments - ``amazon.aws.ec2`` docs fragment has been deprecated please use ``amazon.aws.region.modules`` instead (https://github.com/ansible-collections/amazon.aws/pull/1248). +- module_utils.policy - ``ansible_collections.amazon.aws.module_utils.policy.sort_json_policy_dict`` has been deprecated consider using ``ansible_collections.amazon.aws.module_utils.poilcies.compare_policies`` instead (https://github.com/ansible-collections/amazon.aws/pull/1136). +- s3_object - Support for passing ``dualstack`` and ``endpoint_url`` at the same time has been deprecated, the ``dualstack`` parameter is ignored when ``endpoint_url`` is passed. Support will be removed in a release after 2024-12-01 (https://github.com/ansible-collections/amazon.aws/pull/1305). +- s3_object - Support for passing values of ``overwrite`` other than ``always``, ``never``, ``different`` or last ``last`` has been deprecated. Boolean values should be replaced by the strings ``always`` or ``never`` Support will be removed in a release after 2024-12-01 (https://github.com/ansible-collections/amazon.aws/pull/1305). +- s3_object_info - Support for passing ``dualstack`` and ``endpoint_url`` at the same time has been deprecated, the ``dualstack`` parameter is ignored when ``endpoint_url`` is passed. Support will be removed in a release after 2024-12-01 (https://github.com/ansible-collections/amazon.aws/pull/1305). + +Removed Features (previously deprecated) +---------------------------------------- + +- ec2_vpc_endpoint_info - support for the ``query`` parameter was removed. The ``amazon.aws.ec2_vpc_endpoint_info`` module now only queries for endpoints. Services can be queried using the ``amazon.aws.ec2_vpc_endpoint_service_info`` module (https://github.com/ansible-collections/amazon.aws/pull/1308). +- s3_object - support for creating and deleting buckets using the ``s3_object`` module has been removed. S3 buckets can be created and deleted using the ``amazon.aws.s3_bucket`` module (https://github.com/ansible-collections/amazon.aws/issues/1112). + +Bugfixes +-------- + +- ec2_security_group - file included unreachable code. Fix now removes unreachable code by removing an inapproproate logic (https://github.com/ansible-collections/amazon.aws/pull/1348). +- ec2_vpc_dhcp_option - retry ``describe_dhcp_options`` after creation when ``InvalidDhcpOptionID.NotFound`` is raised (https://github.com/ansible-collections/amazon.aws/pull/1320). +- lambda_execute - Fix waiter error when function_arn is passed instead of name(https://github.com/ansible-collections/amazon.aws/issues/1268). +- module_utils - fixes ``TypeError: deciding_wrapper() got multiple values for argument 'aws_retry'`` when passing positional arguments to functions wrapped by AnsibleAWSModule.client (https://github.com/ansible-collections/amazon.aws/pull/1230). +- rds_param_group - added a check to fail the task while modifying/updating rds_param_group if trying to change DB parameter group family. (https://github.com/ansible-collections/amazon.aws/pull/1169). +- route53_health_check - Fix ``Name`` tag key removal idempotentcy issue when creating health_check with ``use_unique_names`` and ``tags`` set (https://github.com/ansible-collections/amazon.aws/pull/1253). +- s3_bucket - Handle setting of permissions while acl is disabled.(https://github.com/ansible-collections/amazon.aws/pull/1168). + +New Plugins +----------- + +Lookup +~~~~~~ + +- aws_collection_constants - expose various collection related constants + +New Modules +----------- + +- backup_plan - Manage AWS Backup Plans +- backup_plan_info - Describe AWS Backup Plans +- backup_restore_job_info - List information about backup restore jobs +- backup_selection - Create, delete and modify AWS Backup selection +- backup_selection_info - Describe AWS Backup Selections +- backup_tag - Manage tags on backup plan, backup vault, recovery point +- backup_tag_info - List tags on AWS Backup resources +- backup_vault - Manage AWS Backup Vaults +- backup_vault_info - Describe AWS Backup Vaults + +v5.5.3 +====== + +Release Summary +--------------- + +This release contains a few bugfixes for rds_cluster. + +Bugfixes +-------- + +- rds_cluster - Add ``AllocatedStorage``, ``DBClusterInstanceClass``, ``StorageType``, ``Iops``, and ``EngineMode`` to the list of parameters that can be passed when creating or modifying a Multi-AZ RDS cluster (https://github.com/ansible-collections/amazon.aws/pull/1657). +- rds_cluster - Allow to pass GlobalClusterIdentifier to rds cluster on creation (https://github.com/ansible-collections/amazon.aws/pull/1663). + +v5.5.2 +====== + +Bugfixes +-------- + +- cloudwatchevent_rule - Fixes changed status to report False when no change has been made. The module had incorrectly always reported a change. (https://github.com/ansible-collections/amazon.aws/pull/1589) +- ec2_vpc_nat_gateway - fixes to nat gateway so that when the user creates a private NAT gateway, an Elastic IP address should not be allocated. The module had inncorrectly always allocate elastic IP address when creating private nat gateway (https://github.com/ansible-collections/amazon.aws/pull/1632). +- lambda_execute - Fixes to the stack trace output, where it does not contain spaces between each character. The module had incorrectly always outputted extra spaces between each character. (https://github.com/ansible-collections/amazon.aws/pull/1615) + v5.5.1 ====== @@ -345,6 +896,44 @@ New Modules - cloudwatch_metric_alarm_info - Gather information about the alarms for the specified metric - s3_object_info - Gather information about objects in S3 +v4.5.0 +====== + +Release Summary +--------------- + +This release contains a minor bugfix for the ``ec2_vol`` module, some minor work on the ``ec2_key`` module, and various documentation fixes. This is the last planned release of the 4.x series. + + +Minor Changes +------------- + +- ec2_key - minor refactoring and improved unit-tests coverage (https://github.com/ansible-collections/amazon.aws/pull/1288). + +Bugfixes +-------- + +- ec2_vol - handle ec2_vol.tags when the associated instance already exists (https://github.com/ansible-collections/amazon.aws/pull/1071). + +v4.4.0 +====== + +Release Summary +--------------- + +The amazon.aws 4.4.0 release includes a number of security and minor bug fixes. + +Minor Changes +------------- + +- ec2_instance - refacter ``tower_callback`` code to handle parameter validation as part of the argument specification (https://github.com/ansible-collections/amazon.aws/pull/1199). +- ec2_instance - the ``tower_callback`` parameter has been renamed to ``aap_callback``, ``tower_callback`` remains as an alias. This change should have no observable effect for users outside the module documentation (https://github.com/ansible-collections/amazon.aws/pull/1199). + +Security Fixes +-------------- + +- ec2_instance - fixes leak of password into logs when using ``tower_callback.windows=True`` and ``tower_callback.set_password`` (https://github.com/ansible-collections/amazon.aws/pull/1199). + v4.3.0 ====== @@ -483,6 +1072,25 @@ Bugfixes - ec2_vpc_net - fix a bug where the module would get stuck if DNS options were updated in check mode (https://github.com/ansible/ansible/issues/62677). - elb_classic_lb - modify the return value of _format_listeners method to resolve a failure creating https listeners (https://github.com/ansible-collections/amazon.aws/pull/860). +v3.5.1 +====== + +Release Summary +--------------- + +3.5.1 is a security bugfix release. + +Minor Changes +------------- + +- ec2_instance - refacter ``tower_callback`` code to handle parameter validation as part of the argument specification (https://github.com/ansible-collections/amazon.aws/pull/1199). +- ec2_instance - the ``tower_callback`` parameter has been renamed to ``aap_callback``, ``tower_callback`` remains as an alias. This change should have no observable effect for users outside the module documentation (https://github.com/ansible-collections/amazon.aws/pull/1199). + +Security Fixes +-------------- + +- ec2_instance - fixes leak of password into logs when using ``tower_callback.windows=True`` and ``tower_callback.set_password`` (https://github.com/ansible-collections/amazon.aws/pull/1199). + v3.5.0 ====== @@ -520,6 +1128,11 @@ Bugfixes v3.3.1 ====== +Release Summary +--------------- + +Various minor documentation fixes. + v3.3.0 ====== @@ -647,6 +1260,22 @@ Deprecated Features - module_utils - support for the original AWS SDK ``boto`` has been deprecated in favour of the ``boto3``/``botocore`` SDK. All ``boto`` based modules have either been deprecated or migrated to ``botocore``, and the remaining support code in module_utils will be removed in release 4.0.0 of the amazon.aws collection. Any modules outside of the amazon.aws and community.aws collections based on the ``boto`` library will need to be migrated to the ``boto3``/``botocore`` libraries (https://github.com/ansible-collections/amazon.aws/pull/575). +v2.3.0 +====== + +Bugfixes +-------- + +- aws_account_attribute lookup plugin - fix linting errors in documentation data (https://github.com/ansible-collections/amazon.aws/pull/701). +- aws_ec2 inventory plugin - fix linting errors in documentation data (https://github.com/ansible-collections/amazon.aws/pull/701). +- aws_rds inventory plugin - fix linting errors in documentation data (https://github.com/ansible-collections/amazon.aws/pull/701). +- aws_resource_actions callback plugin - fix linting errors in documentation data (https://github.com/ansible-collections/amazon.aws/pull/701). +- aws_secret lookup plugin - fix linting errors in documentation data (https://github.com/ansible-collections/amazon.aws/pull/701). +- aws_service_ip_ranges lookup plugin - fix linting errors in documentation data (https://github.com/ansible-collections/amazon.aws/pull/701). +- aws_ssm lookup plugin - fix linting errors in documentation data (https://github.com/ansible-collections/amazon.aws/pull/701). +- ec2_instance - ec2_instance module broken in Python 3.8 - dict keys modified during iteration (https://github.com/ansible-collections/amazon.aws/issues/709). +- module.utils.s3 - Update validate_bucket_name minimum length to 3 (https://github.com/ansible-collections/amazon.aws/pull/802). + v2.2.0 ====== @@ -747,7 +1376,7 @@ Minor Changes - aws_s3 - add ``tags`` and ``purge_tags`` features for an S3 object (https://github.com/ansible-collections/amazon.aws/pull/335) - aws_s3 - new mode to copy existing on another bucket (https://github.com/ansible-collections/amazon.aws/pull/359). - aws_secret - added support for gracefully handling deleted secrets (https://github.com/ansible-collections/amazon.aws/pull/455). -- aws_ssm - add "on_missing" and "on_denied" option (https://github.com/ansible-collections/amazon.aws/pull/370). +- aws_ssm - add ``on_missing`` and ``on_denied`` option (https://github.com/ansible-collections/amazon.aws/pull/370). - cloudformation - Tests for compatibility with older versions of the AWS SDKs have been removed (https://github.com/ansible-collections/amazon.aws/pull/442). - cloudformation - Tests for compatibility with older versions of the AWS SDKs have been removed (https://github.com/ansible-collections/amazon.aws/pull/442). - ec2_ami - ensure tags are propagated to the snapshot(s) when creating an AMI (https://github.com/ansible-collections/amazon.aws/pull/437). @@ -818,6 +1447,20 @@ New Modules - ec2_spot_instance - request, stop, reboot or cancel spot instance - ec2_spot_instance_info - Gather information about ec2 spot instance requests +v1.5.1 +====== + +Minor Changes +------------- + +- ec2_instance - remove unnecessary raise when exiting with a failure (https://github.com/ansible-collections/amazon.aws/pull/460). + +Bugfixes +-------- + +- ec2_vol - Fixes ``changed`` status when ``modify_volume`` is used, but no new disk is being attached. The module incorrectly reported that no change had occurred even when disks had been modified (iops, throughput, type, etc.). (https://github.com/ansible-collections/amazon.aws/issues/482). +- ec2_vol - fix iops setting and enforce iops/throughput parameters usage (https://github.com/ansible-collections/amazon.aws/pull/334) + v1.5.0 ====== @@ -889,7 +1532,7 @@ Minor Changes - aws_caller_info - add AWSRetry decorator to automatically retry on common temporary failures (https://github.com/ansible-collections/amazon.aws/pull/208) - aws_s3 - Add support for uploading templated content (https://github.com/ansible-collections/amazon.aws/pull/20). -- aws_secret - add "on_missing" and "on_denied" option (https://github.com/ansible-collections/amazon.aws/pull/122). +- aws_secret - add ``on_missing`` and ``on_denied`` option (https://github.com/ansible-collections/amazon.aws/pull/122). - ec2_ami - Add retries for ratelimiting related errors (https://github.com/ansible-collections/amazon.aws/pull/195). - ec2_ami - fixed and streamlined ``max_attempts`` logic when waiting for AMI creation to finish (https://github.com/ansible-collections/amazon.aws/pull/194). - ec2_ami - increased default ``wait_timeout`` to 1200 seconds (https://github.com/ansible-collections/amazon.aws/pull/194). @@ -1005,7 +1648,7 @@ Bugfixes - aws_s3 - Delete objects and delete markers so versioned buckets can be removed. - aws_s3 - Try to wait for the bucket to exist before setting the access control list. - cloudformation_info - Fix a KeyError returning information about the stack(s). -- ec2_asg - Ensure "wait" is honored during replace operations +- ec2_asg - Ensure ``wait`` is honored during replace operations - ec2_launch_template - Update output to include latest_version and default_version, matching the documentation - ec2_transit_gateway - Use AWSRetry before ClientError is handled when describing transit gateways - ec2_transit_gateway - fixed issue where auto_attach set to yes was not being honored (https://github.com/ansible/ansible/issues/61907) diff --git a/ansible_collections/amazon/aws/docs/docsite/rst/aws_ec2_guide.rst b/ansible_collections/amazon/aws/docs/docsite/rst/aws_ec2_guide.rst index 3891aec2e..514d8ada4 100644 --- a/ansible_collections/amazon/aws/docs/docsite/rst/aws_ec2_guide.rst +++ b/ansible_collections/amazon/aws/docs/docsite/rst/aws_ec2_guide.rst @@ -481,6 +481,13 @@ Now the output of ``ansible-inventory -i demo.aws_ec2.yml --list``: ``strict_permissions: False`` will ignore 403 errors rather than failing. +``use_ssm_inventory`` +--------------------- + +``use_ssm_inventory: True`` enables fetching additional EC2 instance information from the AWS Systems Manager (SSM) inventory service into hostvars. By leveraging the SSM inventory data, the ``use_ssm_inventory`` option provides additional details and attributes about the EC2 instances in your inventory. +These details can include operating system information, installed software, network configurations, and custom inventory attributes defined in SSM. + + ``cache`` --------- diff --git a/ansible_collections/amazon/aws/docs/docsite/rst/collection_release.rst b/ansible_collections/amazon/aws/docs/docsite/rst/collection_release.rst new file mode 100644 index 000000000..8ffa2cbe2 --- /dev/null +++ b/ansible_collections/amazon/aws/docs/docsite/rst/collection_release.rst @@ -0,0 +1,383 @@ +:orphan: + +.. _ansible_collections.amazon.aws.docsite.collection_release: + +AWS collection release process +############################## + +The ``amazon.aws`` and ``community.aws`` collections follow `semantic versioning <https://semver.org/>`_ +with the `main branch <https://github.com/ansible-collections/amazon.aws/tree/main>`_ being the +pre-release or development branch, and separate ``stable`` branches used to backport patches for +release in minor and patch releases. Please make sure you're familiar with semantic versioning +prior to preparing a release. + +* Patch releases may **only** contain backwards compatible bug fixes. +* Minor releases must be backwards compatible, but may also include new functionality and + deprecation announcements. +* Major releases may also include breaking changes. + +Releases to `Ansible Galaxy <https://galaxy.ansible.com>`_ are automated through GitHub and Zuul +integrations. + +Major releases +************** + +.. note:: + The examples below will be based upon preparing the major release ``6.0.0``. At the end of the + process a new ``stable-6`` branch will have been created and the ``main`` branch will be ready for + use as the ``7.0.0dev0`` development branch. + +The major release process has two phases. + +#. Preparing the branches +#. Generating the release + +Preparing the branches involves creating a new ``stable`` branch, updating documentation links, and +bumping the version for the ``main`` branch. + +Generating the release involves updating the version information, creating the changelog and +tagging the release. This part of the process is identical to performing +`Minor and Patch releases<ansible_collections.amazon.aws.docsite.minor_releases>` +and will be covered in that section. + +Pre-flight checks +================= + +It's generally advisable to ask in the `Ansible + AWS Matrix chat room +<https://matrix.to/#/#aws:ansible.com>`_ prior to preparing a release to see if folks have any +patches that they'd like to get into a release. + +Deprecations +------------ + +Prior to proceeding with a major release check that no ``collection-deprecated-version`` or +``ansible-deprecated-date`` entries exist in the +`sanity test ignore files <https://github.com/ansible-collections/amazon.aws/tree/main/tests/sanity>`_. + +This generally involves changing a default or dropping support for something, however deprecations +are used as a warning for breaking changes. Once a major version has been released breaking changes +should wait for the next major release before being applied. + +In some cases it may be appropriate to either delay the change (update the deprecation version), +or abandon the deprecation. + +Python and AWS SDK dependencies +------------------------------- + +Starting with the 2.0.0 releases of ``amazon.aws`` and ``community.aws``, it is generally the +collection's policy to support the minor versions of ``botocore`` and ``boto3`` that were released +12 months prior to the most recent major collection release. SDK support for Python versions also +drives which versions of Python the collections support. + +SDK dependencies need to be updated in a number of places, primarily: + +* README.md +* constraints.txt files (for our tests) +* ``ansible_collections.amazon.aws.plugins.module_utils.botocore.MINIMUM_BOTOCORE_VERSION`` +* ``ansible_collections.amazon.aws.plugins.module_utils.botocore.MINIMUM_BOTO3_VERSION`` + +The pull request to update the SDK requirements can also include dropping explicit requirements for a +minimum ``boto3`` or ``botocore`` version in modules. However, dropping code that maintains +backwards compatible support for an older SDK version would be a breaking change and must not be +backported. + +For an example see `ansible-collections/amazon.aws#1342 <https://github.com/ansible-collections/amazon.aws/pull/1342>`_ + +Preparing the branches +====================== + +Ensure that your local copy of the ``main`` branch is up to date and contains all planned patches. + +Preparing a new stable branch +----------------------------- + +.. warning:: + Zuul will need updating here too. + + As part of the next release cycle please add an entry here about configuring the Zuul sanity jobs + for the new stable-6 branch. + +Create and push a new ``stable-<major-version>`` branch (for example ``stable-6`` for release +``6.0.0``): + +.. code-block:: bash + + git fetch origin + git checkout main + git reset --hard origin/main + git checkout -b stable-6 + git push --set-upstream origin stable-6 + +Create a pull request against the new branch updating any documentation links from ``main`` to the +new ``stable-<major-version>`` branch. + +For an example pull request see +`ansible-collections/amazon.aws#1107 <https://github.com/ansible-collections/amazon.aws/pull/1107>`_ + +Updating main +------------- + +Now that our new major release has been branched, we update the ``main`` branch so that it's +configured as the pre-release development version for the **next** release (for example +``7.0.0-dev0`` if you're preparing ``6.0.0``). + +Create a pull request against the ``main`` branch updating the +`galaxy.yml <https://github.com/ansible-collections/amazon.aws/blob/main/galaxy.yml>`_ version +information and the `plugins/module_utils/common.py +<https://github.com/ansible-collections/amazon.aws/blob/main/plugins/module_utils/common.py>`_ +version information to a ``dev0`` prerelease of the next major release. This may result in deprecation +errors from the sanity tests. Create issues and add entries to the relevant +`sanity test ignore files <https://github.com/ansible-collections/amazon.aws/tree/main/tests/sanity>`_. +(including a link to the issue) + +For an example pull request see +`ansible-collections/amazon.aws#1108 <https://github.com/ansible-collections/amazon.aws/pull/1108>`_ + + +Next steps +---------- + +Once these pull requests have been merged there should be a new ``stable`` branch for the release +series (for example ``stable-6`` for all ``6.x.y`` releases) and the ``main`` branch should have +been updated. After which you can continue the major release process by following the steps for +`Minor and Patch releases<ansible_collections.amazon.aws.docsite.minor_releases>`. + + +.. _ansible_collections.amazon.aws.docsite.minor_releases: + +Minor and Patch releases +************************ + +.. note:: + + The examples below will be based upon preparing the major release ``6.0.0`` using the ``stable-6`` + branch. While ``6.0.0`` is a major release, this part of the process is identical for major, + minor and patch releases. + +Ensure that the relevant stable branch (for example ``stable-6``) is up to date and includes all +planned patches. If you have local copies of both ``amazon.aws`` and ``community.aws`` it is +strongly recommended that you checkout the same branch for both collections. + +Outline of steps for generating a release: + +#. Create a local branch +#. Update version information +#. Generate the changelog +#. Generate (and merge) the PR +#. Tag the release +#. Announce the release + +Create a working branch for your release +======================================== + +Checkout the relevant stable branch, and create a local working branch for the release. + +.. code-block:: bash + + git fetch origin + git checkout stable-6 + git reset --hard origin/stable-6 + git checkout -b release/6.0.0/prepare + + +Update version information +========================== + +We need to update the version information in a couple of places: + +* galaxy.yml +* plugins/module_utils/common.py + +In your local clone of the repository, update ``galaxy.yml`` with the new release version +information. + +**galaxy.yml:** + +.. code-block:: yaml + + namespace: amazon + name: aws + version: 6.0.0 + ... + +**plugins/module_utils/common.py:** + +.. code-block:: python + + AMAZON_AWS_COLLECTION_VERSION = "6.0.0" + +.. note:: + + Separately committing each of the changes to your local branch as you go will save you time if + there are problems with changelog fragments. + + While the sanity tests can pick up invalid YAML and RST, they don't detect broken links + prior to the final changelog generation. + +Generate the Changelogs +======================= + +Install Antsibull +----------------- + +We use `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ to generate +our changelogs from the fragments, and `antsibull-docs +<https://github.com/ansible-community/antsibull-docs>`_ to generate the `rendered documentation. +<https://ansible-collections.github.io/amazon.aws/branch/main/collections/amazon/aws/index.html>`_ + +If you've not already installed these tools then you'll need to do so (this can be done in a virtual +environment if desired): + +.. code-block:: bash + + pip install ansible sphinx-ansible-theme antsibull-changelog antsibull-docs + +Add a release_summary changelog fragment +---------------------------------------- + +While not strictly necessary it's preferable to add a release summary that will be added to the +changelog. For example, the `release summary for 5.2.0 +<https://ansible-collections.github.io/amazon.aws/branch/stable-5/collections/amazon/aws/docsite/CHANGELOG.html#release-summary>`_ + +**changelogs/fragments/release-summary.yml:** + +.. code-block:: yaml + + release_summary: | + Add a short description highlighting some of the key changes in the release. + +Commit the release summary to your local branch. + +Generate the merged changelog +----------------------------- + +Next we need to generate the merged changelog. This will automatically delete the used fragments, +update ``CHANGELOG.rst``, ``changelogs/changelog.yaml``, and ``git add`` what it changes. + +.. code-block:: bash + + antsibull-changelog release + +Commit all of these changes to your local branch. + +Create your Pull Request +------------------------ + +Once everything's been committed locally you can prepare a pull request. The pull request should be +for the relevant ``stable`` branch and **not** the ``main`` branch. + +All tests for the PR should pass prior to merging. This pull request can be approved and merged as +usual. + +Because ``CHANGELOG.rst`` is actually generated from ``changelogs/changelog.yaml``, if you need to +fix issues with a changelog fragment, the easiest option is to revert the final changelog +generation, fix the original fragment, and re-generate the final changelog (This is why you should +commit small changes as you go). + +.. note:: + + Releases for amazon.aws should either be prepared by someone from the Ansible Cloud Content + team, or be approved by at least one person from the Ansible Cloud Content team. + +.. warning:: + + Prior to triggering the merge for the release pull request, please warn the `Ansible + AWS Matrix + chat room <https://matrix.to/#/#aws:ansible.com>`_ the final tagging (which releases the code to + `Ansible Galaxy <https://galaxy.ansible.com>`_) should be done using the pull request commit. + +Tag the release +=============== + +Pushing the release to `Ansible Galaxy <https://galaxy.ansible.com>`_ is performed by Zuul. When +a tag is pushed GitHub Zuul will automatically build the relevant artifacts and push them to Galaxy. + +.. code-block:: bash + + git fetch origin + git checkout stable-6 + git reset --hard origin/stable-6 + git tag 6.0.0 + git push origin 6.0.0 + + +Announce the release +==================== + +Bullhorn +-------- + +The Bullhorn is a newsletter for the Ansible developer community. If you have anything to share +about what you've been up to with Ansible lately, including new collection releases, simply hop +into `#social:ansible.com <https://matrix.to/#/#social:ansible.com>`_ (the Ansible Social room on +Matrix) and leave a message, tagging newsbot. Your update will then be included in the next +edition of the Bullhorn (pending editor approval). + +For more information (and some examples) see the `Ansible News Working Group wiki page +<https://github.com/ansible/community/wiki/News#the-bullhorn>`_ + +.. warning:: + As part of the next release cycle please add an example here. + +.. .. code-block:: none +.. +.. @newsbot [amazon.aws 6.0.0](https://github.com/ansible-collections/amazon.aws/tree/6.0.0) has been released. + This is a major release, and includes XXX WRITE ME XXX + [see changelog for more details](https://github.com/ansible-collections/amazon.aws/blob/6.0.0/CHANGELOG.rst) + +Update the chat room topic +-------------------------- + +Once the release is available from Ansible Galaxy, the topic should be updated in the +`Ansible + AWS Matrix chat room. <https://matrix.to/#/#aws:ansible.com>`_ This generally requires +assistance from a member of Ansible staff. + +Create a GitHub "Release" +------------------------- + +While the AWS collections are generally distributed via Ansible Galaxy, for visibility we also +create a GitHub release. Pushing a tag should automatically do this, however, should the automation +fail, releases can also be created manually. + +Copy the release notes from the rendered changelog file and generate a GitHub release based upon the +newly created tag. + +* `amazon.aws <https://github.com/ansible-collections/amazon.aws/releases>`_ +* `community.aws <https://github.com/ansible-collections/community.aws/releases>`_ + +.. note:: + For more information see: `Managing releases in a repository + <https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository>`_ + +Cleanup +******* + +We usually forward-port the changelog entries. If multiple releases are planned concurrently then +the changelog entries can be merged into the ``main`` branch in a single PR. + +.. code-block:: bash + + git fetch origin --tags + git checkout main + git reset --hard origin/main + git checkout -b release/6.0.0/changelog-to-main + git cherry-pick -n 6.0.0 + git checkout origin/main galaxy.yml + git commit -m "Add changelogs from release 6.0.0 to main" + +.. note:: + + To improve visibility of collection-wide deprecations, such as pending changes to module_utils, + or deprecated support for a version of Python, the corresponding changelog fragment can be kept in + the main branch. This will ensure that there is also a deprecation warning in the next major + release. + Keeping a fragment can be done by using git to checkout the original fragment prior to + commiting and pushing: + ``git checkout origin/main changelogs/fragments/<some fragment>.yml`` + +.. warning:: + + Any conflicts will need to be resolved prior to commiting. + +.. warning:: + + Be careful not to update galaxy.yml when you're forward-porting the changelog entries. diff --git a/ansible_collections/amazon/aws/docs/docsite/rst/dev_guidelines.rst b/ansible_collections/amazon/aws/docs/docsite/rst/dev_guidelines.rst index f105cc78a..7519a6c9f 100644 --- a/ansible_collections/amazon/aws/docs/docsite/rst/dev_guidelines.rst +++ b/ansible_collections/amazon/aws/docs/docsite/rst/dev_guidelines.rst @@ -187,16 +187,15 @@ use ``AnsibleAWSModule`` as a base, you must document the reason and request an Importing botocore and boto3 ---------------------------- -The ``ansible_collections.amazon.aws.plugins.module_utils.ec2`` module and -``ansible_collections.amazon.aws.plugins.module_utils.core`` modules both -automatically import boto3 and botocore. If boto3 is missing from the system then the variable -``HAS_BOTO3`` will be set to false. Normally, this means that modules don't need to import -boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule +The ``ansible_collections.amazon.aws.plugins.module_utils.botocore`` module +automatically imports boto3 and botocore. If boto3 is missing from the system then the variable +``HAS_BOTO3`` will be set to ``False``. Normally, this means that modules don't need to import +boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule as the module does that check: .. code-block:: python - from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule + from ansible_collections.amazon.aws.plugins.module_utils.modules import AnsibleAWSModule try: import botocore except ImportError: @@ -207,16 +206,16 @@ or: .. code-block:: python from ansible.module_utils.basic import AnsibleModule - from ansible_collections.amazon.aws.plugins.module_utils.ec2 import HAS_BOTO3 + from ansible.module_utils.basic import missing_required_lib + from ansible_collections.amazon.aws.plugins.module_utils.botocore import HAS_BOTO3 try: import botocore except ImportError: pass # handled by imported HAS_BOTO3 def main(): - if not HAS_BOTO3: - module.fail_json(msg='boto3 and botocore are required for this module') + module.fail_json(missing_required_lib('botocore and boto3')) Supporting Module Defaults -------------------------- @@ -230,7 +229,7 @@ authentication parameters. To do the same for your new module, add an entry for action_groups: aws: ... - aws_example_module + example_module Module behavior --------------- @@ -261,7 +260,7 @@ to connect to AWS as these handle the same range of connection options. These helpers also check for missing profiles or a region not set when it needs to be, so you don't have to. -An example of connecting to ec2 is shown below. Note that unlike boto there is no ``NoAuthHandlerFound`` +An example of connecting to EC2 is shown below. Note that unlike boto there is no ``NoAuthHandlerFound`` exception handling like in boto. Instead, an ``AuthFailure`` exception will be thrown when you use the connection. To ensure that authorization, parameter validation and permissions errors are all caught, you should catch ``ClientError`` and ``BotoCoreError`` exceptions with every boto3 connection call. @@ -271,7 +270,7 @@ See exception handling: module.client('ec2') -or for the higher level ec2 resource: +or for the higher level EC2 resource: .. code-block:: python @@ -297,10 +296,10 @@ Common Documentation Fragments for Connection Parameters There are four :ref:`common documentation fragments <module_docs_fragments>` that should be included into almost all AWS modules: -* ``aws`` - contains the common boto3 connection parameters -* ``ec2`` - contains the common region parameter required for many AWS modules * ``boto3`` - contains the minimum requirements for the collection -* ``tags`` - contains the common tagging parameters used by many AWS modules +* ``common.modules`` - contains the common boto3 connection parameters +* ``region.modules`` - contains the common region parameter required for many AWS APIs +* ``tags`` - contains the common tagging parameters These fragments should be used rather than re-documenting these properties to ensure consistency and that the more esoteric connection options are documented. For example: @@ -311,9 +310,31 @@ and that the more esoteric connection options are documented. For example: module: my_module # some lines omitted here extends_documentation_fragment: - - amazon.aws.aws - - amazon.aws.ec2 - amazon.aws.boto3 + - amazon.aws.common.modules + - amazon.aws.region.modules + ''' + +Other plugin types have a slightly different document fragment format, and should use +the following fragments: + +* ``boto3`` - contains the minimum requirements for the collection +* ``common.plugins`` - contains the common boto3 connection parameters +* ``region.plugins`` - contains the common region parameter required for many AWS APIs +* ``tags`` - contains the common tagging parameters + +These fragments should be used rather than re-documenting these properties to ensure consistency +and that the more esoteric connection options are documented. For example: + +.. code-block:: python + + DOCUMENTATION = ''' + module: my_plugin + # some lines omitted here + extends_documentation_fragment: + - amazon.aws.boto3 + - amazon.aws.common.plugins + - amazon.aws.region.plugins ''' .. _ansible_collections.amazon.aws.docsite.dev_exceptions: @@ -326,17 +347,17 @@ are a number of possibilities for handling it. * Catch the general ``ClientError`` or look for a specific error code with ``is_boto3_error_code``. -* Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way -* Retry using AWSRetry -* Use ``fail_json()`` to report the failure without using ``ansible_collections.amazon.aws.plugins.module_utils.core`` -* Do something custom in the case where you know how to handle the exception +* Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way. +* Retry using AWSRetry. +* Use ``fail_json()`` to report the failure without using ``AnsibleAWSModule``. +* Do something custom in the case where you know how to handle the exception. For more information on botocore exception handling see the `botocore error documentation <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_. Using is_boto3_error_code ------------------------- -To use ``ansible_collections.amazon.aws.plugins.module_utils.core.is_boto3_error_code`` to catch a single +To use ``ansible_collections.amazon.aws.plugins.module_utils.botocore.is_boto3_error_code`` to catch a single AWS error code, call it in place of ``ClientError`` in your except clauses. In this example, *only* the ``InvalidGroup.NotFound`` error code will be caught here, and any other error will be raised for handling elsewhere in the program. @@ -360,7 +381,7 @@ You should use the AnsibleAWSModule for all new modules, unless not possible. .. code-block:: python - from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule + from ansible_collections.amazon.aws.plugins.module_utils.modules import AnsibleAWSModule # Set up module parameters # module params code here @@ -369,7 +390,7 @@ You should use the AnsibleAWSModule for all new modules, unless not possible. # connection code here # Make a call to AWS - name = module.params.get['name'] + name = module.params.get('name') try: result = connection.describe_frooble(FroobleName=name) except (botocore.exceptions.BotoCoreError, botocore.exceptions.ClientError) as e: @@ -384,7 +405,7 @@ If you need to perform an action based on the error boto3 returned, use the erro .. code-block:: python # Make a call to AWS - name = module.params.get['name'] + name = module.params.get('name') try: result = connection.describe_frooble(FroobleName=name) except is_boto3_error_code('FroobleNotFound'): @@ -392,7 +413,7 @@ If you need to perform an action based on the error boto3 returned, use the erro except (botocore.exceptions.BotoCoreError, botocore.exceptions.ClientError) as e: # pylint: disable=duplicate-except module.fail_json_aws(e, msg="Couldn't obtain frooble %s" % name) -using fail_json() and avoiding ansible_collections.amazon.aws.plugins.module_utils.core +using fail_json() and avoiding AnsibleAWSModule --------------------------------------------------------------------------------------- Boto3 provides lots of useful information when an exception is thrown so pass this to the user @@ -400,7 +421,7 @@ along with the message. .. code-block:: python - from ansible.module_utils.ec2 import HAS_BOTO3 + from ansible_collections.amazon.aws.plugins.module_utils.botocore import HAS_BOTO3 try: import botocore except ImportError: @@ -410,7 +431,7 @@ along with the message. # connection code here # Make a call to AWS - name = module.params.get['name'] + name = module.params.get('name') try: result = connection.describe_frooble(FroobleName=name) except botocore.exceptions.ClientError as e: @@ -426,7 +447,7 @@ If you need to perform an action based on the error boto3 returned, use the erro .. code-block:: python # Make a call to AWS - name = module.params.get['name'] + name = module.params.get('name') try: result = connection.describe_frooble(FroobleName=name) except botocore.exceptions.ClientError as e: @@ -695,7 +716,7 @@ and returns True if they are different. .. code-block:: python - from ansible_collections.amazon.aws.plugins.module_utils.ec2 import compare_policies + from ansible_collections.amazon.aws.plugins.module_utils.iam import compare_policies import json @@ -1048,3 +1069,80 @@ Where one of these reasons apply you should open a pull request proposing the mi Unsupported integration tests will not be automatically run by CI. However, the necessary policies should be available so that the tests can be manually run by someone performing a PR review or writing a patch. + +Unit-tests for AWS plugins +========================== + +Why do we need unit-tests when we've got functional tests +--------------------------------------------------------- + +Unit-tests are much faster and more suitable to test corner cases. They also don't depend on a third party service +and thus, a failure is less likely to be a false positive. + + +How to keep my code simple? +--------------------------- + +Ideally, you should break up your code in tiny functions. Each function should have a limited number of parameters +and a low amount of cross dependencies with the rest of the code (low coupling): + +- Don't pass a large data structure to a function if it only uses one field. This clarifies the inputs of your + function (the contract) and also reduces the risk of an unexpected transformation of the data structure + from within the function. +- The boto client object is complex and can be source of unwanted side-effect. It's better to isolate the calls + in dedicated functions. These functions will have their own unit-tests. +- Don't pass the ``module`` object when you only need the read a couple of parameters from ``module.params``. + Pass the parameter directly to your function. By doing so, you're explicit about the function's inputs + (the contract) and you reduce potential side-effect. + +Unit-tests guidelines +--------------------- + +Ideally, all the ``module_utils`` should be covered by unit-tests. However we acknowledge that writing unit-tests may +be challenging and we also accept contribution with no unit-test. Generally speaking, unit-tests are recommended and likely to speed up the PR reviews. + +- Our tests are run with ``pytest`` and we use the features it provides such as Fixtures, Parametrization. +- The use of ``unittest.TestCase`` is discouraged for the sake of consistency and simplicity. +- Unit-tests should run fine without any network connection. +- It's not necessary to mock all the boto3/botocore calls (``get_paginator()``, ``paginate()``, etc). It's often better to just set-up a function that wraps these calls and mock the result. +- Simplicity prevails. Tests should be short and cover a limited set of features. + +Pytest is well documented and you will find some example in its `how-to guides <https://docs.pytest.org/en/latest/how-to/index.html>`_ + +How to run my unit-tests +------------------------ + +In our CI, the testing is done by ``ansible-test``. You can run the tests locally with the following command: + +.. code-block:: shell + + $ ansible-test units --docker + +We also provide a ``tox`` configuration which allow you to run one specific test faster. In this example, we focus on the tests for the ``s3_object`` module: + +.. code-block:: shell + + $ tox -e py3 -- tests/unit/plugins/modules/test_s3_object.py + + +Code formatting +=============== + +To improve the consistency of our code we use a number of formatters and linters. These tools can +be run locally by using tox: + +.. code-block:: shell + + $ tox -m format + +.. code-block:: shell + + $ tox -m lint + +More information about each of the tools we use can be found on their websites: + +- `black <https://black.readthedocs.io/en/stable/>`_ - opinionated code formatter. +- `isort <https://pycqa.github.io/isort/>`_ - groups and sorts imports. +- `flynt <https://github.com/ikamensh/flynt>`_ - encourages the use of f-strings over alternatives such as concatination, ``%``, ``str.format()``, and ``string.Template``. +- `flake8 <https://flake8.pycqa.org/en/latest/>`_ - encourages following the PEP8 recommendations. +- `pylint <https://pylint.readthedocs.io/en/latest/>`_ - a static code anaylsys tool. |