diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 14bf31a03b1..f867fc9e4e5 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -4,6 +4,104 @@ amazon.aws Release Notes .. contents:: Topics +v8.0.0 +====== + +Release Summary +--------------- + +This major release brings several new features, bug fixes, and deprecated features. It also includes the removal of some functionality for ``iam_role, iam_role_info`` and ``module_utils.policy`` that were previously deprecated. We have also removed support for ``ansible-core<2.15``. + +Minor Changes +------------- + +- autoscaling_group - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). +- cloudformation - apply automatic retries when paginating through stack events without a filter (https://github.com/ansible-collections/amazon.aws/pull/2049). +- cloudtrail - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). +- ec2_instance - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). +- ec2_vol - Ensure volume state is not one of ``deleted`` or ``deleting`` when trying to delete volume, to guaranty idempotency (https://github.com/ansible-collections/amazon.aws/pull/2052). +- ec2_vol - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). +- elb_classic_lb - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). +- kms_key - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). +- lambda_event - Add support for setting the ``maximum_batching_window_in_seconds`` option (https://github.com/ansible-collections/amazon.aws/pull/2025). +- module_uils/botocore - support sets and tuples of errors as well as lists (https://github.com/ansible-collections/amazon.aws/pull/1829). +- module_utils/elbv2 - Add support for adding listener with multiple certificates during ALB creation. Allows elb_application_elb module to handle mentioned use case. (https://github.com/ansible-collections/amazon.aws/pull/1950). +- module_utils/elbv2 - Add the possibility to update ``SslPolicy``, ``Certificates`` and ``AlpnPolicy`` for TLS listeners (https://github.com/ansible-collections/amazon.aws/issues/1198). +- rds_instance - Allow passing empty list to ``enable_cloudwatch_logs_exports`` in order to remove all existing exports (https://github.com/ansible-collections/amazon.aws/pull/1917). +- s3_bucket - refactor s3_bucket module code for improved readability and maintainability (https://github.com/ansible-collections/amazon.aws/pull/2057). +- s3_object - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + +Breaking Changes / Porting Guide +-------------------------------- + +- amazon.aws collection - Support for ansible-core < 2.15 has been dropped (https://github.com/ansible-collections/amazon.aws/pull/2093). +- iam_role - ``iam_role.assume_role_policy_document`` is no longer converted from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). +- iam_role_info - ``iam_role.assume_role_policy_document`` is no longer converted from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). +- kms_key - the ``policies`` return value has been renamed to ``key_policies`` the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). +- kms_key_info - the ``policies`` return value has been renamed to ``key_policies`` the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). +- lambda_event - | ``batch_size`` no longer defaults to 100. According to the boto3 API (https://boto3.amazonaws.com/v1/documentation/api/1.26.78/reference/services/lambda.html#Lambda.Client.create_event_source_mapping), ``batch_size`` defaults to 10 for sqs sources and to 100 for stream sources (https://github.com/ansible-collections/amazon.aws/pull/2025). + +Deprecated Features +------------------- + +- aws_ec2 inventory plugin - removal of the previously deprecated ``include_extra_api_calls`` option has been assigned to release 9.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2040). +- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). +- iam_policy - removal of the previously deprecated ``policies`` return key has been assigned to release 9.0.0. Use the ``policy_names`` return key instead (https://github.com/ansible-collections/amazon.aws/pull/2040). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- rds_param_group - the ``rds_param_group`` module has been renamed to ``rds_instance_param_group``. The usage of the module has not changed. The rds_param_group alias will be removed in version 10.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2058). + +Removed Features (previously deprecated) +---------------------------------------- + +- iam_role - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). +- iam_role_info - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). +- module_utils.policy - the previously deprecated ``sort_json_policy_dict()`` function has been removed, consider using ``compare_policies()`` instead (https://github.com/ansible-collections/amazon.aws/pull/2052). + +Bugfixes +-------- + +- elb_classic_lb - fixes bug where ``proxy_protocol`` not being set or being set to ``None`` may result in unexpected behaviour or errors (https://github.com/ansible-collections/amazon.aws/pull/2049). +- lambda_event - Fix when ``batch_size`` is greater than 10, by enabling support for setting ``maximum_batching_window_in_seconds`` (https://github.com/ansible-collections/amazon.aws/pull/2025). +- lambda_event - Retrieve function ARN using AWS API (get_function) instead of building it with AWS account information (https://github.com/ansible-collections/amazon.aws/issues/1859). + +v7.6.0 +====== + +Release Summary +--------------- + +This release brings several bugfixes, minor changes and some new rds modules (``rds_cluster_param_group``, ``rds_cluster_param_group_info`` and ``rds_engine_versions_info``). It also introduces a deprecation for the ``cloudformation`` module. + +Minor Changes +------------- + +- ec2_instance - add support for ``host`` option in placement.tenancy (https://github.com/ansible-collections/amazon.aws/pull/2026). +- ec2_vol - Ensure volume state is not one of ``deleted`` or ``deleting`` when trying to delete volume, to guaranty idempotency (https://github.com/ansible-collections/amazon.aws/pull/2052). + +Deprecated Features +------------------- + +- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + +Bugfixes +-------- + +- iam_managed_policy - fixes bug that causes ``ParamValidationError`` when attempting to delete a policy that's attached to a role or a user (https://github.com/ansible-collections/amazon.aws/issues/2067). +- iam_role_info - fixes bug in handling paths missing the ``/`` prefix and/or suffix (https://github.com/ansible-collections/amazon.aws/issues/2065). +- s3_object - fix idempotency issue when copying object uploaded using multipart upload (https://github.com/ansible-collections/amazon.aws/issues/2016). + +New Modules +----------- + +- rds_cluster_param_group - Manage RDS cluster parameter groups +- rds_cluster_param_group_info - Describes the properties of specific RDS cluster parameter group. +- rds_engine_versions_info - Describes the properties of specific versions of DB engines. + v7.5.0 ====== diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17be9b7d700..537f07cd44c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -123,7 +123,7 @@ be found on Libera.Chat IRC as detailed below. - [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) - Details on contributing to Ansible - [Contributing to Collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#contributing-to-collections) - How to check out collection git repositories correctly - [Contributing to Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html#contributing-maintained-collections) -- [Guidelines for Ansible Amazon AWS module development](https://docs.ansible.com/ansible/latest/dev_guide/platforms/aws_guidelines.html) +- [Guidelines for Ansible Amazon AWS module development](https://docs.ansible.com/ansible/latest/collections/amazon/aws/docsite/dev_guidelines.html) - [Getting Started With AWS Ansible Module Development and Community Contribution](https://www.ansible.com/blog/getting-started-with-aws-ansible-module-development) diff --git a/README.md b/README.md index 07b9b12051e..84f81e66ed7 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ AWS related modules and plugins supported by the Ansible community are in the [c ## Ansible version compatibility -Tested with the Ansible Core >= 2.14.0 versions, and the current development version of Ansible. Ansible Core versions prior to 2.14.0 are not supported. +Tested with the Ansible Core >= 2.15.0 versions, and the current development version of Ansible. Ansible Core versions prior to 2.15.0 are not supported. ## Python version compatibility diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml index 78379028ab8..546b1fe229f 100644 --- a/changelogs/changelog.yaml +++ b/changelogs/changelog.yaml @@ -2483,7 +2483,8 @@ releases: bugfixes: - cloudwatchlogs_log_group_info - Implement exponential backoff when making API calls to prevent throttling exceptions (https://github.com/ansible-collections/amazon.aws/issues/2011). - - plugin_utils.inventory - Ensure templated options in lookup plugins are converted (https://github.com/ansible-collections/amazon.aws/issues/1955). + - plugin_utils.inventory - Ensure templated options in lookup plugins are converted + (https://github.com/ansible-collections/amazon.aws/issues/1955). release_summary: This release includes bugfixes for the ``cloudwatchlogs_log_group_info`` module and the inventory plugins. fragments: @@ -2870,3 +2871,158 @@ releases: - 20240314-s3_object-copy-mode-with-metadata.yml - 20240321-iam-user-info.yml release_date: '2024-04-03' + 7.6.0: + changes: + bugfixes: + - iam_managed_policy - fixes bug that causes ``ParamValidationError`` when attempting + to delete a policy that's attached to a role or a user (https://github.com/ansible-collections/amazon.aws/issues/2067). + - iam_role_info - fixes bug in handling paths missing the ``/`` prefix and/or + suffix (https://github.com/ansible-collections/amazon.aws/issues/2065). + - s3_object - fix idempotency issue when copying object uploaded using multipart + upload (https://github.com/ansible-collections/amazon.aws/issues/2016). + deprecated_features: + - cloudformation - the ``template`` parameter has been deprecated and will be + removed in a release after 2026-05-01. The ``template_body`` parameter can + be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). + - module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` + will be removed in a release after 2025-05-01. The ``boto3`` parameter has + been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + - module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will + be removed in a release after 2025-05-01. The ``boto3`` parameter has been + ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + - module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` + will be removed in a release after 2025-05-01. The ``boto3`` parameter has + been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + minor_changes: + - ec2_instance - add support for ``host`` option in placement.tenancy (https://github.com/ansible-collections/amazon.aws/pull/2026). + - ec2_vol - Ensure volume state is not one of ``deleted`` or ``deleting`` when + trying to delete volume, to guaranty idempotency (https://github.com/ansible-collections/amazon.aws/pull/2052). + release_summary: This release brings several bugfixes, minor changes and some + new rds modules (``rds_cluster_param_group``, ``rds_cluster_param_group_info`` + and ``rds_engine_versions_info``). It also introduces a deprecation for the + ``cloudformation`` module. + fragments: + - 20240322-s3_object-fix-idempotency-copy-issue-with-multipart-uploaded-object.yml + - 20240403-ec2_securty_group-sanity.yml + - 20240411-ec2_vol.yml + - 2026-ec2_instance-add-support-for-placement-tenancy-host.yml + - 2065-iam_role_info.yml + - 2067-iam_managed_policy-delete.yml + - cloudformation-template.yml + - release_summary.yml + - sanity-boto3.yml + modules: + - description: Manage RDS cluster parameter groups + name: rds_cluster_param_group + namespace: '' + - description: Describes the properties of specific RDS cluster parameter group. + name: rds_cluster_param_group_info + namespace: '' + - description: Describes the properties of specific versions of DB engines. + name: rds_engine_versions_info + namespace: '' + release_date: '2024-05-07' + 8.0.0: + changes: + breaking_changes: + - amazon.aws collection - Support for ansible-core < 2.15 has been dropped (https://github.com/ansible-collections/amazon.aws/pull/2093). + - iam_role - ``iam_role.assume_role_policy_document`` is no longer converted + from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). + - iam_role_info - ``iam_role.assume_role_policy_document`` is no longer converted + from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). + - kms_key - the ``policies`` return value has been renamed to ``key_policies`` + the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). + - kms_key_info - the ``policies`` return value has been renamed to ``key_policies`` + the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). + - lambda_event - | ``batch_size`` no longer defaults to 100. According to the + boto3 API (https://boto3.amazonaws.com/v1/documentation/api/1.26.78/reference/services/lambda.html#Lambda.Client.create_event_source_mapping), + ``batch_size`` defaults to 10 for sqs sources and to 100 for stream sources + (https://github.com/ansible-collections/amazon.aws/pull/2025). + bugfixes: + - elb_classic_lb - fixes bug where ``proxy_protocol`` not being set or being + set to ``None`` may result in unexpected behaviour or errors (https://github.com/ansible-collections/amazon.aws/pull/2049). + - lambda_event - Fix when ``batch_size`` is greater than 10, by enabling support + for setting ``maximum_batching_window_in_seconds`` (https://github.com/ansible-collections/amazon.aws/pull/2025). + - lambda_event - Retrieve function ARN using AWS API (get_function) instead + of building it with AWS account information (https://github.com/ansible-collections/amazon.aws/issues/1859). + deprecated_features: + - aws_ec2 inventory plugin - removal of the previously deprecated ``include_extra_api_calls`` + option has been assigned to release 9.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2040). + - cloudformation - the ``template`` parameter has been deprecated and will be + removed in a release after 2026-05-01. The ``template_body`` parameter can + be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). + - iam_policy - removal of the previously deprecated ``policies`` return key + has been assigned to release 9.0.0. Use the ``policy_names`` return key instead + (https://github.com/ansible-collections/amazon.aws/pull/2040). + - module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` + will be removed in a release after 2025-05-01. The ``boto3`` parameter has + been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + - module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will + be removed in a release after 2025-05-01. The ``boto3`` parameter has been + ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + - module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` + will be removed in a release after 2025-05-01. The ``boto3`` parameter has + been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + - rds_param_group - the ``rds_param_group`` module has been renamed to ``rds_instance_param_group``. + The usage of the module has not changed. The rds_param_group alias will be + removed in version 10.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2058). + minor_changes: + - autoscaling_group - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + - cloudformation - apply automatic retries when paginating through stack events + without a filter (https://github.com/ansible-collections/amazon.aws/pull/2049). + - cloudtrail - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + - ec2_instance - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + - ec2_vol - Ensure volume state is not one of ``deleted`` or ``deleting`` when + trying to delete volume, to guaranty idempotency (https://github.com/ansible-collections/amazon.aws/pull/2052). + - ec2_vol - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + - elb_classic_lb - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + - kms_key - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + - lambda_event - Add support for setting the ``maximum_batching_window_in_seconds`` + option (https://github.com/ansible-collections/amazon.aws/pull/2025). + - module_uils/botocore - support sets and tuples of errors as well as lists + (https://github.com/ansible-collections/amazon.aws/pull/1829). + - module_utils/elbv2 - Add support for adding listener with multiple certificates + during ALB creation. Allows elb_application_elb module to handle mentioned + use case. (https://github.com/ansible-collections/amazon.aws/pull/1950). + - module_utils/elbv2 - Add the possibility to update ``SslPolicy``, ``Certificates`` + and ``AlpnPolicy`` for TLS listeners (https://github.com/ansible-collections/amazon.aws/issues/1198). + - rds_instance - Allow passing empty list to ``enable_cloudwatch_logs_exports`` + in order to remove all existing exports (https://github.com/ansible-collections/amazon.aws/pull/1917). + - s3_bucket - refactor s3_bucket module code for improved readability and maintainability + (https://github.com/ansible-collections/amazon.aws/pull/2057). + - s3_object - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). + release_summary: This major release brings several new features, bug fixes, + and deprecated features. It also includes the removal of some functionality + for ``iam_role, iam_role_info`` and ``module_utils.policy`` that were previously + deprecated. We have also removed support for ``ansible-core<2.15``. + removed_features: + - iam_role - the ``iam_role.assume_role_policy_document_raw`` return value has + been deprecated. ``iam_role.assume_role_policy_document`` now returns the + same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). + - iam_role_info - the ``iam_role.assume_role_policy_document_raw`` return value + has been deprecated. ``iam_role.assume_role_policy_document`` now returns + the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). + - module_utils.policy - the previously deprecated ``sort_json_policy_dict()`` + function has been removed, consider using ``compare_policies()`` instead (https://github.com/ansible-collections/amazon.aws/pull/2052). + fragments: + - 1829-is_boto3_error-tuple.yml + - 1950-elb_application_lb-multiple-listener-certificates-for-alb.yml + - 20231127-module_utils-elbv2-update.yaml + - 20231211-rds_instance_cloudwatch.yml + - 20240208-lambda_event-fix-validate-params.yml + - 20240227-zombies.yml + - 20240325-lambda_event-bugfix.yml + - 20240411-remove-deprecated-sort_json_policy_dict.yml + - 20240502-docs_cleanup.yml + - 20240516-rds_param_group.yml + - 20250513-update-docs.yml + - 2057-s3_bucket-refactor.yml + - 8.0.0-deprecation-removal.yml + - 8.0.0-dev0.yml + - 8.0.0-increase-ansible-core-version.yml + - cloudformation-template.yml + - release_summary.yml + - return_block_update_ec2_1.yml + - sanity-boto3.yml + - sanity-simple.yml + release_date: '2024-05-16' diff --git a/changelogs/fragments/1829-is_boto3_error-tuple.yml b/changelogs/fragments/1829-is_boto3_error-tuple.yml deleted file mode 100644 index 8174e85874a..00000000000 --- a/changelogs/fragments/1829-is_boto3_error-tuple.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: - - module_uils/botocore - support sets and tuples of errors as well as lists (https://github.com/ansible-collections/amazon.aws/pull/1829). diff --git a/changelogs/fragments/1950-elb_application_lb-multiple-listener-certificates-for-alb.yml b/changelogs/fragments/1950-elb_application_lb-multiple-listener-certificates-for-alb.yml deleted file mode 100644 index afad85e1445..00000000000 --- a/changelogs/fragments/1950-elb_application_lb-multiple-listener-certificates-for-alb.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: - - module_utils/elbv2 - Add support for adding listener with multiple certificates during ALB creation. Allows elb_application_elb module to handle mentioned use case. (https://github.com/ansible-collections/amazon.aws/pull/1950). diff --git a/changelogs/fragments/1979-do-not-ignore-ipv6-addresses.yaml b/changelogs/fragments/1979-do-not-ignore-ipv6-addresses.yaml new file mode 100644 index 00000000000..95ada6d654d --- /dev/null +++ b/changelogs/fragments/1979-do-not-ignore-ipv6-addresses.yaml @@ -0,0 +1,3 @@ +--- +bugfixes: + - ec2_instance - do not ignore IPv6 addresses when a single network interface is specified (https://github.com/ansible-collections/amazon.aws/pull/1979). diff --git a/changelogs/fragments/20231127-module_utils-elbv2-update.yaml b/changelogs/fragments/20231127-module_utils-elbv2-update.yaml deleted file mode 100644 index c851779a982..00000000000 --- a/changelogs/fragments/20231127-module_utils-elbv2-update.yaml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: - - module_utils/elbv2 - Add the possibility to update ``SslPolicy``, ``Certificates`` and ``AlpnPolicy`` for TLS listeners (https://github.com/ansible-collections/amazon.aws/issues/1198). diff --git a/changelogs/fragments/20231211-rds_instance_cloudwatch.yml b/changelogs/fragments/20231211-rds_instance_cloudwatch.yml deleted file mode 100644 index b661aa5d40e..00000000000 --- a/changelogs/fragments/20231211-rds_instance_cloudwatch.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: - - rds_instance - Allow passing empty list to ``enable_cloudwatch_logs_exports`` in order to remove all existing exports (https://github.com/ansible-collections/amazon.aws/pull/1917). diff --git a/changelogs/fragments/20240208-lambda_event-fix-validate-params.yml b/changelogs/fragments/20240208-lambda_event-fix-validate-params.yml deleted file mode 100644 index 4af29c11de7..00000000000 --- a/changelogs/fragments/20240208-lambda_event-fix-validate-params.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -bugfixes: - - lambda_event - Retrieve function ARN using AWS API (get_function) instead of building it with AWS account information (https://github.com/ansible-collections/amazon.aws/issues/1859). diff --git a/changelogs/fragments/20240227-zombies.yml b/changelogs/fragments/20240227-zombies.yml deleted file mode 100644 index ff58ad96c0d..00000000000 --- a/changelogs/fragments/20240227-zombies.yml +++ /dev/null @@ -1,8 +0,0 @@ -minor_changes: - - autoscaling_group - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). - - cloudtrail - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). - - ec2_instance - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). - - ec2_vol - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). - - elb_classic_lb - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). - - kms_key - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). - - s3_object - removed unused code (https://github.com/ansible-collections/amazon.aws/pull/1996). diff --git a/changelogs/fragments/20240322-s3_object-fix-idempotency-copy-issue-with-multipart-uploaded-object.yml b/changelogs/fragments/20240322-s3_object-fix-idempotency-copy-issue-with-multipart-uploaded-object.yml deleted file mode 100644 index 6d96a4d71e7..00000000000 --- a/changelogs/fragments/20240322-s3_object-fix-idempotency-copy-issue-with-multipart-uploaded-object.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -bugfixes: - - s3_object - fix idempotency issue when copying object uploaded using multipart upload (https://github.com/ansible-collections/amazon.aws/issues/2016). diff --git a/changelogs/fragments/20240403-ec2_securty_group-sanity.yml b/changelogs/fragments/20240403-ec2_securty_group-sanity.yml deleted file mode 100644 index 3d1134e4bdb..00000000000 --- a/changelogs/fragments/20240403-ec2_securty_group-sanity.yml +++ /dev/null @@ -1,2 +0,0 @@ -trivial: - - ec2_securty_group - Use ``yield from`` in order to fix sanity errors. diff --git a/changelogs/fragments/20240411-remove-deprecated-sort_json_policy_dict.yml b/changelogs/fragments/20240411-remove-deprecated-sort_json_policy_dict.yml deleted file mode 100644 index 07b093ea6bc..00000000000 --- a/changelogs/fragments/20240411-remove-deprecated-sort_json_policy_dict.yml +++ /dev/null @@ -1,5 +0,0 @@ ---- -removed_features: - - module_utils.policy - the previously deprecated ``sort_json_policy_dict()`` function has been removed, consider using ``compare_policies()`` instead (https://github.com/ansible-collections/amazon.aws/pull/2052). -minor_changes: - - ec2_vol - Ensure volume state is not one of ``deleted`` or ``deleting`` when trying to delete volume, to guaranty idempotency (https://github.com/ansible-collections/amazon.aws/pull/2052). diff --git a/changelogs/fragments/20240516-rds_param_group.yml b/changelogs/fragments/20240516-rds_param_group.yml deleted file mode 100644 index 97eaa0de639..00000000000 --- a/changelogs/fragments/20240516-rds_param_group.yml +++ /dev/null @@ -1,3 +0,0 @@ -deprecated_features: - - rds_param_group - the ``rds_param_group`` module has been renamed to ``rds_instance_param_group``. - The usage of the module has not changed. The rds_param_group alias will be removed in version 10.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2058). diff --git a/changelogs/fragments/20250513-main-9.0.0.yml b/changelogs/fragments/20250513-main-9.0.0.yml new file mode 100644 index 00000000000..7d31e9997a9 --- /dev/null +++ b/changelogs/fragments/20250513-main-9.0.0.yml @@ -0,0 +1,2 @@ +trivial: + - galaxy.yml - bump ``release`` for main branch to ``9.0.0-dev0``. diff --git a/changelogs/fragments/2026-ec2_instance-add-support-for-placement-tenancy-host.yml b/changelogs/fragments/2026-ec2_instance-add-support-for-placement-tenancy-host.yml deleted file mode 100644 index 83090e96d42..00000000000 --- a/changelogs/fragments/2026-ec2_instance-add-support-for-placement-tenancy-host.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: - - ec2_instance - add support for ``host`` option in placement.tenancy (https://github.com/ansible-collections/amazon.aws/pull/2026). diff --git a/changelogs/fragments/2057-s3_bucket-refactor.yml b/changelogs/fragments/2057-s3_bucket-refactor.yml deleted file mode 100644 index 68fccc6a6b4..00000000000 --- a/changelogs/fragments/2057-s3_bucket-refactor.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -minor_changes: - - s3_bucket - refactor s3_bucket module code for improved readability and maintainability (https://github.com/ansible-collections/amazon.aws/pull/2057). \ No newline at end of file diff --git a/changelogs/fragments/2065-iam_role_info.yml b/changelogs/fragments/2065-iam_role_info.yml deleted file mode 100644 index e65c2fbd40c..00000000000 --- a/changelogs/fragments/2065-iam_role_info.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -bugfixes: - - iam_role_info - fixes bug in handling paths missing the ``/`` prefix and/or suffix (https://github.com/ansible-collections/amazon.aws/issues/2065). diff --git a/changelogs/fragments/2067-iam_managed_policy-delete.yml b/changelogs/fragments/2067-iam_managed_policy-delete.yml deleted file mode 100644 index 1bef1980d91..00000000000 --- a/changelogs/fragments/2067-iam_managed_policy-delete.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -bugfixes: - - iam_managed_policy - fixes bug that causes ``ParamValidationError`` when attempting to delete a policy that's attached to a role or a user (https://github.com/ansible-collections/amazon.aws/issues/2067). diff --git a/changelogs/fragments/2083-backup_plan_info-bugfix-get-info-for-all-plans.yml b/changelogs/fragments/2083-backup_plan_info-bugfix-get-info-for-all-plans.yml new file mode 100644 index 00000000000..96bedc378bc --- /dev/null +++ b/changelogs/fragments/2083-backup_plan_info-bugfix-get-info-for-all-plans.yml @@ -0,0 +1,3 @@ +--- +bugfixes: + - backup_plan_info - Bugfix to enable getting info of all backup plans (https://github.com/ansible-collections/amazon.aws/pull/2083). diff --git a/changelogs/fragments/2105-backup_vault-remove-unnecessary-return-values.yml b/changelogs/fragments/2105-backup_vault-remove-unnecessary-return-values.yml new file mode 100644 index 00000000000..705986018f1 --- /dev/null +++ b/changelogs/fragments/2105-backup_vault-remove-unnecessary-return-values.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - backup_vault - Update code to remove unnecessary return values returned as None (https://github.com/ansible-collections/amazon.aws/pull/2105). diff --git a/changelogs/fragments/2107-s3_download.yml b/changelogs/fragments/2107-s3_download.yml new file mode 100644 index 00000000000..b4604192745 --- /dev/null +++ b/changelogs/fragments/2107-s3_download.yml @@ -0,0 +1,2 @@ +bugfixes: + - s3_object - fixed issue which was causing ``MemoryError`` exceptions when downloading large files (https://github.com/ansible-collections/amazon.aws/issues/2107). diff --git a/changelogs/fragments/8.0.0-deprecation-removal.yml b/changelogs/fragments/8.0.0-deprecation-removal.yml deleted file mode 100644 index ef0af9325d5..00000000000 --- a/changelogs/fragments/8.0.0-deprecation-removal.yml +++ /dev/null @@ -1,13 +0,0 @@ -deprecated_features: -- aws_ec2 inventory plugin - removal of the previously deprecated ``include_extra_api_calls`` option has been assigned to release 9.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2040). -- iam_policy - removal of the previously deprecated ``policies`` return key has been assigned to release 9.0.0. Use the ``policy_names`` return key instead (https://github.com/ansible-collections/amazon.aws/pull/2040). - -removed_features: -- iam_role - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). -- iam_role_info - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). - -breaking_changes: -- iam_role - ``iam_role.assume_role_policy_document`` is no longer converted from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). -- iam_role_info - ``iam_role.assume_role_policy_document`` is no longer converted from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). -- kms_key - the ``policies`` return value has been renamed to ``key_policies`` the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). -- kms_key_info - the ``policies`` return value has been renamed to ``key_policies`` the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). diff --git a/changelogs/fragments/8.0.0-dev0.yml b/changelogs/fragments/8.0.0-dev0.yml deleted file mode 100644 index 587a5db3b0b..00000000000 --- a/changelogs/fragments/8.0.0-dev0.yml +++ /dev/null @@ -1,3 +0,0 @@ ---- -trivial: - - bump galaxy.yml to release 8.0.0-dev0 diff --git a/changelogs/fragments/8.0.0-increase-ansible-core-version.yml b/changelogs/fragments/8.0.0-increase-ansible-core-version.yml deleted file mode 100644 index fe368852c94..00000000000 --- a/changelogs/fragments/8.0.0-increase-ansible-core-version.yml +++ /dev/null @@ -1,2 +0,0 @@ -breaking_changes: - - amazon.aws collection - Support for ansible-core < 2.14 has been dropped (https://github.com/ansible-collections/amazon.aws/pull/2041). diff --git a/changelogs/fragments/add_evaluate_low_sample_count_percentile.yml b/changelogs/fragments/add_evaluate_low_sample_count_percentile.yml new file mode 100644 index 00000000000..4a1ddff5dd3 --- /dev/null +++ b/changelogs/fragments/add_evaluate_low_sample_count_percentile.yml @@ -0,0 +1,5 @@ +--- +minor_changes: + - cloudwatch_metric_alarm - add support for `evaluate_low_sample_count_percentile` parameter. +trivial: + - cloudwatch_metric_alarm - add return block to the module doc. diff --git a/changelogs/fragments/cloudformation-template.yml b/changelogs/fragments/cloudformation-template.yml deleted file mode 100644 index 29ddadc8e3f..00000000000 --- a/changelogs/fragments/cloudformation-template.yml +++ /dev/null @@ -1,2 +0,0 @@ -deprecated_features: - - cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). diff --git a/changelogs/fragments/documentation_update.yml b/changelogs/fragments/documentation_update.yml new file mode 100644 index 00000000000..e4160a5dea7 --- /dev/null +++ b/changelogs/fragments/documentation_update.yml @@ -0,0 +1,2 @@ +trivial: + - "Part #1 - Ensures the modules documentation follows the correct formats (see also https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation)." diff --git a/changelogs/fragments/documentation_update_2.yml b/changelogs/fragments/documentation_update_2.yml new file mode 100644 index 00000000000..87c0daf84ce --- /dev/null +++ b/changelogs/fragments/documentation_update_2.yml @@ -0,0 +1,2 @@ +trivial: + - "Part #2 - Ensures the modules documentation follows the correct formats (see also https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation)." diff --git a/changelogs/fragments/documentation_update_3.yml b/changelogs/fragments/documentation_update_3.yml new file mode 100644 index 00000000000..67e6daac534 --- /dev/null +++ b/changelogs/fragments/documentation_update_3.yml @@ -0,0 +1,2 @@ +trivial: + - "Part #3 - Ensures the modules documentation follows the correct formats (see also https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation)." diff --git a/changelogs/fragments/fix_args_spec_supoptions.yml b/changelogs/fragments/fix_args_spec_supoptions.yml new file mode 100644 index 00000000000..403ef18fbd4 --- /dev/null +++ b/changelogs/fragments/fix_args_spec_supoptions.yml @@ -0,0 +1,4 @@ +--- +trivial: + - backup_plan - Modify the argspec to use options for a dict parameter. + - backup_plan - add example for advanced_backup_settings usage. diff --git a/changelogs/fragments/sanity-boto3.yml b/changelogs/fragments/sanity-boto3.yml deleted file mode 100644 index 10d870e8490..00000000000 --- a/changelogs/fragments/sanity-boto3.yml +++ /dev/null @@ -1,7 +0,0 @@ -deprecated_features: - - module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. - The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). - - module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. - The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). - - module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. - The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). diff --git a/changelogs/fragments/sanity-simple.yml b/changelogs/fragments/sanity-simple.yml deleted file mode 100644 index 27c1e682075..00000000000 --- a/changelogs/fragments/sanity-simple.yml +++ /dev/null @@ -1,5 +0,0 @@ -bugfixes: - - elb_classic_lb - fixes bug where ``proxy_protocol`` not being set or being set to ``None`` may result in unexpected behaviour or errors (https://github.com/ansible-collections/amazon.aws/pull/2049). - -minor_changes: - - cloudformation - apply automatic retries when paginating through stack events without a filter (https://github.com/ansible-collections/amazon.aws/pull/2049). diff --git a/changelogs/fragments/update_return_block_cloud_modules.yml b/changelogs/fragments/update_return_block_cloud_modules.yml new file mode 100644 index 00000000000..3bd6806bf0d --- /dev/null +++ b/changelogs/fragments/update_return_block_cloud_modules.yml @@ -0,0 +1,3 @@ +--- +trivial: + - Update return block in the module documentation for cloudtrail, cloudtrail_info, cloudwatchevent_rule, cloudwatchlogs_log_group modules. diff --git a/changelogs/fragments/update_return_block_ec2_2.yml b/changelogs/fragments/update_return_block_ec2_2.yml new file mode 100644 index 00000000000..8de1a9b07d7 --- /dev/null +++ b/changelogs/fragments/update_return_block_ec2_2.yml @@ -0,0 +1,3 @@ +--- +trivial: + - Update return block in the module documentation for ec2_snapshot ec2_snapshot_info ec2_spot_instance ec2_vol ec2_vpc_endpoint ec2_vpc_endpoint_info ec2_vpc_endpoint_service_info ec2_vpc_nat_gateway ec2_vpc_nat_gateway_info ec2_vpc_route_table ec2_vpc_subnet ec2_vpc_subnet_info diff --git a/galaxy.yml b/galaxy.yml index 9625532fa10..d54d125d81f 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -1,7 +1,7 @@ --- namespace: amazon name: aws -version: 8.0.0-dev0 +version: 9.0.0-dev0 readme: README.md authors: - Ansible (https://github.com/ansible) diff --git a/meta/runtime.yml b/meta/runtime.yml index 1d2a1cd0151..94614615f1e 100644 --- a/meta/runtime.yml +++ b/meta/runtime.yml @@ -1,5 +1,5 @@ --- -requires_ansible: ">=2.14.0" +requires_ansible: ">=2.15.0" action_groups: aws: - autoscaling_group diff --git a/plugins/module_utils/common.py b/plugins/module_utils/common.py index a915204b8c3..23aa93fc5ee 100644 --- a/plugins/module_utils/common.py +++ b/plugins/module_utils/common.py @@ -4,7 +4,7 @@ # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) AMAZON_AWS_COLLECTION_NAME = "amazon.aws" -AMAZON_AWS_COLLECTION_VERSION = "8.0.0-dev0" +AMAZON_AWS_COLLECTION_VERSION = "9.0.0-dev0" _collection_info_context = { diff --git a/plugins/modules/autoscaling_group.py b/plugins/modules/autoscaling_group.py index 520bf932076..378c84405dd 100644 --- a/plugins/modules/autoscaling_group.py +++ b/plugins/modules/autoscaling_group.py @@ -12,7 +12,7 @@ description: - Can create or delete AWS AutoScaling Groups. - Can be used with the M(community.aws.autoscaling_launch_config) module to manage Launch Configurations. - - Prior to release 5.0.0 this module was called C(community.aws.ec2_asg). + - Prior to release 5.0.0 this module was called M(community.aws.ec2_asg). The usage did not change. - This module was originally added to C(community.aws) in release 1.0.0. author: @@ -42,13 +42,13 @@ availability_zones: description: - List of availability zone names in which to create the group. - - Defaults to all the availability zones in the region if I(vpc_zone_identifier) is not set. + - Defaults to all the availability zones in the region if O(vpc_zone_identifier) is not set. type: list elements: str launch_config_name: description: - - Name of the Launch configuration to use for the group. See the community.aws.autoscaling_launch_config) module for managing these. - - If unspecified then the current group value will be used. One of I(launch_config_name) or I(launch_template) must be provided. + - Name of the Launch configuration to use for the group. See the M(community.aws.autoscaling_launch_config) module for managing these. + - If unspecified then the current group value will be used. One of O(launch_config_name) or O(launch_template) must be provided. type: str launch_template: description: @@ -61,11 +61,11 @@ type: str launch_template_name: description: - - The name of the launch template. Only one of I(launch_template_name) or I(launch_template_id) is required. + - The name of the launch template. Only one of O(launch_template.launch_template_name) or O(launch_template.launch_template_id) is required. type: str launch_template_id: description: - - The id of the launch template. Only one of I(launch_template_name) or I(launch_template_id) is required. + - The id of the launch template. Only one of O(launch_template.launch_template_name) or O(launch_template.launch_template_id) is required. type: str type: dict min_size: @@ -79,19 +79,19 @@ max_instance_lifetime: description: - The maximum amount of time, in seconds, that an instance can be in service. - - Maximum instance lifetime must be equal to 0, between 604800 and 31536000 seconds (inclusive), or not specified. - - Value of 0 removes lifetime restriction. + - Maximum instance lifetime must be equal to V(0), between V(604800) and V(31536000) seconds (inclusive), or not specified. + - Value of V(0) removes lifetime restriction. type: int mixed_instances_policy: description: - A mixed instance policy to use for the ASG. - - Only used when the ASG is configured to use a Launch Template (I(launch_template)). + - Only used when the ASG is configured to use a Launch Template (O(launch_template)). - 'See also U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-autoscaling-autoscalinggroup-mixedinstancespolicy.html)' required: false suboptions: instance_types: description: - - A list of instance_types. + - A list of instance types. type: list elements: str required: false @@ -120,17 +120,19 @@ The minimum amount of the Auto Scaling group's capacity that must be fulfilled by On-Demand Instances. This base portion is provisioned first as your group scales. - >- - Default if not set is 0. If you leave it set to 0, On-Demand Instances are launched as a - percentage of the Auto Scaling group's desired capacity, per the OnDemandPercentageAboveBaseCapacity setting. + Default if not set is V(0). If you leave it set to V(0), On-Demand Instances are launched as a + percentage of the Auto Scaling group's desired capacity, per the + O(mixed_instances_policy.instances_distribution.on_demand_percentage_above_base_capacity) setting. type: int required: false version_added: 1.5.0 version_added_collection: community.aws on_demand_percentage_above_base_capacity: description: - - Controls the percentages of On-Demand Instances and Spot Instances for your additional capacity beyond OnDemandBaseCapacity. - - Default if not set is 100. If you leave it set to 100, the percentages are 100% for On-Demand Instances and 0% for Spot Instances. - - 'Valid range: 0 to 100' + - Controls the percentages of On-Demand Instances and Spot Instances for your additional capacity beyond + O(mixed_instances_policy.instances_distribution.on_demand_base_capacity). + - Default if not set is V(100). If you leave it set to V(100), the percentages are 100% for On-Demand Instances and 0% for Spot Instances. + - 'Valid range: V(0) to V(100).' type: int required: false version_added: 1.5.0 @@ -146,9 +148,9 @@ description: - >- The number of Spot Instance pools across which to allocate your Spot Instances. The Spot pools are determined from - the different instance types in the Overrides array of LaunchTemplate. Default if not set is 2. + the different instance types in the Overrides array of LaunchTemplate. Default if not set is V(2). - Used only when the Spot allocation strategy is lowest-price. - - 'Valid Range: Minimum value of 1. Maximum value of 20.' + - 'Valid Range: Minimum value of V(1). Maximum value of V(20).' type: int required: false version_added: 1.5.0 @@ -174,20 +176,20 @@ replace_all_instances: description: - In a rolling fashion, replace all instances that used the old launch configuration with one from the new launch configuration. - It increases the ASG size by I(replace_batch_size), waits for the new instances to be up and running. + It increases the ASG size by O(replace_batch_size), waits for the new instances to be up and running. After that, it terminates a batch of old instances, waits for the replacements, and repeats, until all old instances are replaced. Once that's done the ASG size is reduced back to the expected size. default: false type: bool replace_batch_size: description: - - Number of instances you'd like to replace at a time. Used with I(replace_all_instances). + - Number of instances you'd like to replace at a time. Used with O(replace_all_instances). required: false default: 1 type: int replace_instances: description: - - List of I(instance_ids) belonging to the named AutoScalingGroup that you would like to terminate and be replaced with instances + - List of instance ids belonging to the named AutoScalingGroup that you would like to terminate and be replaced with instances matching the current launch configuration. type: list elements: str @@ -195,7 +197,7 @@ detach_instances: description: - Removes one or more instances from the specified AutoScalingGroup. - - If I(decrement_desired_capacity) flag is not set, new instance(s) are launched to replace the detached instance(s). + - If O(decrement_desired_capacity) flag is not set, new instance(s) are launched to replace the detached instance(s). - If a Classic Load Balancer is attached to the AutoScalingGroup, the instances are also deregistered from the load balancer. - If there are target groups attached to the AutoScalingGroup, the instances are also deregistered from the target groups. type: list @@ -212,13 +214,13 @@ version_added_collection: community.aws lc_check: description: - - Check to make sure instances that are being replaced with I(replace_instances) do not already have the current I(launch_config). + - Check to make sure instances that are being replaced with O(replace_instances) do not already have the current launch config. default: true type: bool lt_check: description: - - Check to make sure instances that are being replaced with I(replace_instances) do not already have the current - I(launch_template or I(launch_template) I(version). + - Check to make sure instances that are being replaced with O(replace_instances) do not already have the current + O(launch_template) or O(launch_template) O(launch_template.version). default: true type: bool vpc_zone_identifier: @@ -229,15 +231,15 @@ tags: description: - A list of tags to add to the Auto Scale Group. - - Optional key is I(propagate_at_launch), which defaults to true. - - When I(propagate_at_launch) is true the tags will be propagated to the Instances created. + - Optional key is V(propagate_at_launch), which defaults to V(true). + - When V(propagate_at_launch) is V(true) the tags will be propagated to the Instances created. type: list elements: dict default: [] purge_tags: description: - - If C(true), existing tags will be purged from the resource to match exactly what is defined by I(tags) parameter. - - If the I(tags) parameter is not set then tags will not be modified. + - If V(true), existing tags will be purged from the resource to match exactly what is defined by O(tags) parameter. + - If the O(tags) parameter is not set then tags will not be modified. default: false type: bool version_added: 3.2.0 @@ -275,9 +277,9 @@ termination_policies: description: - An ordered list of criteria used for selecting instances to be removed from the Auto Scaling group when reducing capacity. - - Using I(termination_policies=Default) when modifying an existing AutoScalingGroup will result in the existing policy being retained - instead of changed to C(Default). - - 'Valid values include: C(Default), C(OldestInstance), C(NewestInstance), C(OldestLaunchConfiguration), C(ClosestToNextInstanceHour)' + - Using O(termination_policies=Default) when modifying an existing AutoScalingGroup will result in the existing policy being retained + instead of changed to V(Default). + - 'Valid values include: V(Default), V(OldestInstance), V(NewestInstance), V(OldestLaunchConfiguration), V(ClosestToNextInstanceHour)' - 'Full documentation of valid values can be found in the AWS documentation:' - 'U(https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-instance-termination.html#custom-termination-policy)' default: Default @@ -302,7 +304,7 @@ description: - A list of scaling processes to suspend. - 'Valid values include:' - - C(Launch), C(Terminate), C(HealthCheck), C(ReplaceUnhealthy), C(AZRebalance), C(AlarmNotification), C(ScheduledActions), C(AddToLoadBalancer) + - V(Launch), V(Terminate), V(HealthCheck), V(ReplaceUnhealthy), V(AZRebalance), V(AlarmNotification), V(ScheduledActions), V(AddToLoadBalancer) - 'Full documentation of valid values can be found in the AWS documentation:' - 'U(https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-suspend-resume-processes.html)' default: [] @@ -315,12 +317,12 @@ default: false metrics_granularity: description: - - When I(metrics_collection=true) this will determine the granularity of metrics collected by CloudWatch. + - When O(metrics_collection=true) this will determine the granularity of metrics collected by CloudWatch. default: "1Minute" type: str metrics_list: description: - - List of autoscaling metrics to collect when I(metrics_collection=true). + - List of autoscaling metrics to collect when O(metrics_collection=true). default: - 'GroupMinSize' - 'GroupMaxSize' diff --git a/plugins/modules/autoscaling_group_info.py b/plugins/modules/autoscaling_group_info.py index 8a39e200b39..59884bfc639 100644 --- a/plugins/modules/autoscaling_group_info.py +++ b/plugins/modules/autoscaling_group_info.py @@ -11,7 +11,7 @@ short_description: Gather information about EC2 Auto Scaling Groups (ASGs) in AWS description: - Gather information about EC2 Auto Scaling Groups (ASGs) in AWS. - - Prior to release 5.0.0 this module was called C(community.aws.ec2_asg_info). + - Prior to release 5.0.0 this module was called M(community.aws.ec2_asg_info). The usage did not change. - This module was originally added to C(community.aws) in release 1.0.0. author: diff --git a/plugins/modules/aws_az_info.py b/plugins/modules/aws_az_info.py index a373f41bc85..0c5ac8694f4 100644 --- a/plugins/modules/aws_az_info.py +++ b/plugins/modules/aws_az_info.py @@ -107,7 +107,7 @@ group_name: description: - The name of the associated group. - - For availability zones, this will be the same as I(region_name). + - For availability zones, this will be the same as RV(availability_zones.region_name). type: str returned: on success sample: 'us-east-1' diff --git a/plugins/modules/backup_plan.py b/plugins/modules/backup_plan.py index 4fab240c762..1dd672933bc 100644 --- a/plugins/modules/backup_plan.py +++ b/plugins/modules/backup_plan.py @@ -11,7 +11,7 @@ version_added: 6.0.0 short_description: Manage AWS Backup Plans description: - - Creates, updates, or deletes AWS Backup Plans + - Creates, updates, or deletes AWS Backup Plans. - For more information see the AWS documentation for Backup plans U(https://docs.aws.amazon.com/aws-backup/latest/devguide/about-backup-plans.html). author: - Kristof Imre Szabo (@krisek) @@ -33,7 +33,7 @@ rules: description: - An array of BackupRule objects, each of which specifies a scheduled task that is used to back up a selection of resources. - - Required when I(state=present). + - Required when O(state=present). type: list elements: dict suboptions: @@ -55,14 +55,14 @@ - A value in minutes after a backup is scheduled before a job will be canceled if it doesn't start successfully. If this value is included, it must be at least 60 minutes to avoid errors. - - AWS default if not supplied is 480. + - AWS default if not supplied is V(480). type: int default: 480 completion_window_minutes: description: - A value in minutes after a backup job is successfully started before it must be completed or it will be canceled by Backup. - - AWS default if not supplied is 10080 + - AWS default if not supplied is V(10080). type: int default: 10080 lifecycle: @@ -82,8 +82,8 @@ type: int delete_after_days: description: Specifies the number of days after creation that a recovery - point is deleted. Must be greater than 90 days plus - move_to_cold_storage_after_days. + point is deleted. Must be greater than V(90) days plus + O(rules.lifecycle.move_to_cold_storage_after_days). type: int recovery_point_tags: description: To help organize your resources, you can assign your own metadata to the resources that you create. @@ -114,15 +114,15 @@ type: int delete_after_days: description: Specifies the number of days after creation that a - recovery point is deleted. Must be greater than 90 days plus - move_to_cold_storage_after_days. + recovery point is deleted. Must be greater than V(90) days plus + O(rules.copy_actions.lifecycle.move_to_cold_storage_after_days). type: int enable_continuous_backup: description: - Specifies whether Backup creates continuous backups. True causes Backup to create continuous backups capable of point-in-time restore (PITR). False (or not specified) causes Backup to create snapshot backups. - - AWS default if not supplied is false. + - AWS default if not supplied is V(false). type: bool default: false schedule_expression_timezone: @@ -153,7 +153,11 @@ - Specifies the backup option for a selected resource. - This option is only available for Windows VSS backup jobs. type: dict - choices: [{'WindowsVSS': 'enabled'}, {'WindowsVSS': 'disabled'}] + suboptions: + WindowsVSS: + description: Enable or disable WindowsVSS backup option. + type: str + choices: ['enabled', 'disabled'] creator_request_id: description: Identifies the request and allows failed requests to be retried without the risk of running the operation twice. If the request includes a @@ -180,6 +184,10 @@ backup_plan_name: elastic rules: - rule_name: daily + advanced_backup_settings: + - resource_type: "EC2" + backup_options: + WindowsVSS: enabled target_backup_vault_name: "{{ backup_vault_name }}" schedule_expression: 'cron(0 5 ? * * *)' start_window_minutes: 60 @@ -387,7 +395,7 @@ resource_type=dict(type="str", choices=["EC2"]), backup_options=dict( type="dict", - choices=[{"WindowsVSS": "enabled"}, {"WindowsVSS": "disabled"}], + options=dict(WindowsVSS=dict(type="str", choices=["enabled", "disabled"])), ), ), ), diff --git a/plugins/modules/backup_plan_info.py b/plugins/modules/backup_plan_info.py index 096857d5b1f..1761d2af68a 100644 --- a/plugins/modules/backup_plan_info.py +++ b/plugins/modules/backup_plan_info.py @@ -20,7 +20,6 @@ backup_plan_names: type: list elements: str - required: true description: - Specifies a list of plan names. extends_documentation_fragment: @@ -31,10 +30,11 @@ EXAMPLES = r""" # Note: These examples do not set authentication details, see the AWS Guide for details. -# Gather information about all backup plans -- amazon.aws.backup_plan_info -# Gather information about a particular backup plan -- amazon.aws.backup_plan_info: +- name: Gather information about all backup plans + amazon.aws.backup_plan_info: + +- name: Gather information about a particular backup plan + amazon.aws.backup_plan_info: backup plan_names: - elastic """ @@ -70,7 +70,7 @@ description: Tags of the backup plan type: str version_id: - description: Version id of the backup plan + description: Version id of the backup plan. type: str backup_plan: returned: always @@ -83,15 +83,15 @@ type: str sample: elastic advanced_backup_settings: - description: Advanced backup settings of the backup plan + description: Advanced backup settings of the backup plan. type: list elements: dict contains: resource_type: - description: Resource type of the advanced setting + description: Resource type of the advanced setting. type: str backup_options: - description: Options of the advanced setting + description: Options of the advanced setting. type: dict rules: description: @@ -110,10 +110,21 @@ from ansible_collections.amazon.aws.plugins.module_utils.retries import AWSRetry +def get_all_backup_plans_info(client): + paginator = client.get_paginator("list_backup_plans") + return paginator.paginate().build_full_result() + + def get_backup_plan_detail(client, module): backup_plan_list = [] backup_plan_names = module.params.get("backup_plan_names") + if backup_plan_names is None: + backup_plan_names = [] + backup_plan_list_info = get_all_backup_plans_info(client)["BackupPlansList"] + for backup_plan in backup_plan_list_info: + backup_plan_names.append(backup_plan["BackupPlanName"]) + for name in backup_plan_names: backup_plan_list.extend(get_plan_details(module, client, name)) @@ -122,7 +133,7 @@ def get_backup_plan_detail(client, module): def main(): argument_spec = dict( - backup_plan_names=dict(type="list", elements="str", required=True), + backup_plan_names=dict(type="list", elements="str"), ) module = AnsibleAWSModule(argument_spec=argument_spec, supports_check_mode=True) diff --git a/plugins/modules/backup_selection.py b/plugins/modules/backup_selection.py index ff78d0b68cf..60434289e87 100644 --- a/plugins/modules/backup_selection.py +++ b/plugins/modules/backup_selection.py @@ -43,14 +43,14 @@ description: - A list of conditions that you define to assign resources to your backup plans using tags. - Condition operators are case sensitive. - - When you specify more than one condition in I(list_of_tags), you assign all resources that match AT LEAST ONE condition (using OR logic). + - When you specify more than one condition in O(list_of_tags), you assign all resources that match AT LEAST ONE condition (using OR logic). type: list elements: dict suboptions: condition_type: description: - An operation applied to a key-value pair used to assign resources to your backup plan. - - Condition only supports C(STRINGEQUALS). + - Condition only supports V(STRINGEQUALS). type: str condition_key: description: @@ -71,7 +71,7 @@ description: - A list of conditions (expressed as a dict) that you define to assign resources to your backup plans using tags. - When you specify more than one condition in I(conditions), you only assign the resources that match ALL conditions (using AND logic). - - I(conditions) supports C(string_equals), C(string_like), C(string_not_equals), and C(string_not_like). I(list_of_tags) only supports C(string_equals). + - O(conditions) supports V(string_equals), V(string_like), V(string_not_equals), and V(string_not_like). O(list_of_tags) only supports V(string_equals). type: dict suboptions: string_equals: @@ -84,7 +84,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_equals.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. @@ -100,7 +100,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_like.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. @@ -115,7 +115,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_not_equals.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. @@ -130,7 +130,7 @@ condition_key: description: - The key in a key-value pair. - - I(condition_key) in the I(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' + - O(conditions.string_not_like.condition_key) in the O(conditions) option must use the AWS resource tag prefix, e.g. 'aws:ResourceTag/key-name' type: str condition_value: description: The value in a key-value pair. diff --git a/plugins/modules/backup_tag.py b/plugins/modules/backup_tag.py index c06d5666ee1..2fb23cffc75 100644 --- a/plugins/modules/backup_tag.py +++ b/plugins/modules/backup_tag.py @@ -29,14 +29,14 @@ tags: description: - A dictionary of tags to add or remove from the resource. - - If the value provided for a tag key is null and I(state=absent), the tag will be removed regardless of its current value. + - If the value provided for a tag key is null and O(state=absent), the tag will be removed regardless of its current value. type: dict required: true aliases: ['resource_tags'] purge_tags: description: - Whether unspecified tags should be removed from the resource. - - Note that when combined with I(state=absent), specified tag keys are not purged regardless of its current value. + - Note that when combined with O(state=absent), specified tag keys are not purged regardless of its current value. type: bool default: false diff --git a/plugins/modules/backup_tag_info.py b/plugins/modules/backup_tag_info.py index 91bd375edb4..a0cbe64feb7 100644 --- a/plugins/modules/backup_tag_info.py +++ b/plugins/modules/backup_tag_info.py @@ -37,7 +37,7 @@ RETURN = r""" tags: - description: A dict containing the tags on the resource + description: A dict containing the tags on the resource. returned: always type: dict """ diff --git a/plugins/modules/backup_vault.py b/plugins/modules/backup_vault.py index 7fd2cb93900..ab408df3c4a 100644 --- a/plugins/modules/backup_vault.py +++ b/plugins/modules/backup_vault.py @@ -187,19 +187,6 @@ def get_vault_facts(module, client, vault_name): resource = resp.get("BackupVaultArn") resp["tags"] = get_backup_resource_tags(module, client, resource) - # Check for non-existent values and populate with None - optional_vals = set( - [ - "S3KeyPrefix", - "SnsTopicName", - "SnsTopicARN", - "CloudWatchLogsLogGroupArn", - "CloudWatchLogsRoleArn", - "KmsKeyId", - ] - ) - for v in optional_vals - set(resp.keys()): - resp[v] = None return resp else: diff --git a/plugins/modules/cloudformation.py b/plugins/modules/cloudformation.py index 49392fde098..c24b3d55bf6 100644 --- a/plugins/modules/cloudformation.py +++ b/plugins/modules/cloudformation.py @@ -24,7 +24,7 @@ type: bool on_create_failure: description: - - Action to take upon failure of stack creation. Incompatible with the I(disable_rollback) option. + - Action to take upon failure of stack creation. Incompatible with the O(disable_rollback) option. choices: - DO_NOTHING - ROLLBACK @@ -32,7 +32,7 @@ type: str create_timeout: description: - - The amount of time (in minutes) that can pass before the stack status becomes CREATE_FAILED + - The amount of time (in minutes) that can pass before the stack status becomes V(CREATE_FAILED). type: int template_parameters: description: @@ -42,9 +42,9 @@ type: dict state: description: - - If I(state=present), stack will be created. - - If I(state=present) and if stack exists and template has changed, it will be updated. - - If I(state=absent), stack will be removed. + - If O(state=present), stack will be created. + - If O(state=present) and if stack exists and template has changed, it will be updated. + - If O(state=absent), stack will be removed. default: present choices: [ present, absent ] type: str @@ -52,13 +52,13 @@ description: - The local path of the CloudFormation template. - This must be the full path to the file, relative to the working directory. If using roles this may look - like C(roles/cloudformation/files/cloudformation-example.json). - - If I(state=present) and the stack does not exist yet, either I(template), I(template_body) or I(template_url) + like V(roles/cloudformation/files/cloudformation-example.json). + - If O(state=present) and the stack does not exist yet, either O(template), O(template_body) or O(template_url) must be specified (but only one of them). - - If I(state=present), the stack does exist, and neither I(template), - I(template_body) nor I(template_url) are specified, the previous template will be reused. - - The I(template) parameter has been deprecated and will be remove in a release after - 2026-05-01. It is recommended to use I(template_body) with the lookup plugin. + - If O(state=present), the stack does exist, and neither O(template), + O(template_body) nor O(template_url) are specified, the previous template will be reused. + - The O(template) parameter has been deprecated and will be remove in a release after + 2026-05-01. It is recommended to use O(template_body) with the P(ansible.builtin.template#lookup) lookup plugin. type: path notification_arns: description: @@ -77,7 +77,7 @@ version_added: 1.5.0 stack_policy_on_update_body: description: - - the body of the cloudformation stack policy only applied during this update. + - The body of the cloudformation stack policy only applied during this update. type: json version_added: 1.5.0 tags: @@ -89,23 +89,23 @@ description: - Location of file containing the template body. The URL must point to a template (max size 307,200 bytes) located in an S3 bucket in the same region as the stack. - - If I(state=present) and the stack does not exist yet, either I(template), I(template_body) or I(template_url) + - If O(state=present) and the stack does not exist yet, either O(template), O(template_body) or O(template_url) must be specified (but only one of them). - - If I(state=present), the stack does exist, and neither I(template), I(template_body) nor I(template_url) are specified, + - If O(state=present), the stack does exist, and neither O(template), O(template_body) nor O(template_url) are specified, the previous template will be reused. type: str create_changeset: description: - - "If stack already exists create a changeset instead of directly applying changes. See the AWS Change Sets docs - U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html)." - - "WARNING: if the stack does not exist, it will be created without changeset. If I(state=absent), the stack will be - deleted immediately with no changeset." + - If stack already exists create a changeset instead of directly applying changes. See the AWS Change Sets docs + U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html). + - B(WARNING:) if the stack does not exist, it will be created without changeset. If O(state=absent), the stack will be + deleted immediately with no changeset. type: bool default: false changeset_name: description: - Name given to the changeset when creating a changeset. - - Only used when I(create_changeset=true). + - Only used when O(create_changeset=true). - By default a name prefixed with Ansible-STACKNAME is generated based on input parameters. See the AWS Change Sets docs for more information U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html) @@ -122,9 +122,9 @@ template_body: description: - Template body. Use this to pass in the actual body of the CloudFormation template. - - If I(state=present) and the stack does not exist yet, either I(template), I(template_body) or I(template_url) + - If O(state=present) and the stack does not exist yet, either O(template), O(template_body) or O(template_url) must be specified (but only one of them). - - If I(state=present), the stack does exist, and neither I(template), I(template_body) nor I(template_url) + - If O(state=present), the stack does exist, and neither O(template), O(template_body) nor O(template_url) are specified, the previous template will be reused. type: str events_limit: @@ -154,7 +154,7 @@ capabilities: description: - Specify capabilities that stack template contains. - - Valid values are C(CAPABILITY_IAM), C(CAPABILITY_NAMED_IAM) and C(CAPABILITY_AUTO_EXPAND). + - Valid values are V(CAPABILITY_IAM), V(CAPABILITY_NAMED_IAM) and V(CAPABILITY_AUTO_EXPAND). type: list elements: str default: [ CAPABILITY_IAM, CAPABILITY_NAMED_IAM ] @@ -301,7 +301,7 @@ sample: ["updating stack"] change_set_id: description: The ID of the stack change set if one was created - returned: I(state=present) and I(create_changeset=true) + returned: O(state=present) and O(create_changeset=true) type: str sample: "arn:aws:cloudformation:us-east-1:123456789012:changeSet/Ansible-StackName-f4496805bd1b2be824d1e315c6884247ede41eb0" stack_resources: diff --git a/plugins/modules/cloudformation_info.py b/plugins/modules/cloudformation_info.py index 697b39f0071..afc02e4ab40 100644 --- a/plugins/modules/cloudformation_info.py +++ b/plugins/modules/cloudformation_info.py @@ -104,7 +104,7 @@ cloudformation: description: - Dictionary of dictionaries containing info of stack(s). - - Keys are I(stack_name)s. + - Keys are stack_name(s). returned: always type: dict contains: @@ -249,24 +249,24 @@ } stack_events: description: All stack events for the stack. - returned: only if all_facts or stack_events is true and the stack exists + returned: only if O(all_facts) or O(stack_events) is V(true) and the stack exists type: list stack_policy: description: Describes the stack policy for the stack. - returned: only if all_facts or stack_policy is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict stack_template: description: Describes the stack template for the stack. - returned: only if all_facts or stack_template is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict stack_resource_list: description: Describes stack resources for the stack. - returned: only if all_facts or stack_resources is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: list stack_resources: description: Dictionary of stack resources keyed by the value of each resource 'LogicalResourceId' parameter and corresponding value of each resource 'PhysicalResourceId' parameter. - returned: only if all_facts or stack_resources is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict sample: { "AutoScalingGroup": "dev-someapp-AutoscalingGroup-1SKEXXBCAN0S7", @@ -275,11 +275,11 @@ } stack_change_sets: description: A list of stack change sets. Each item in the list represents the details of a specific changeset. - returned: only if all_facts or stack_change_sets is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: list stack_tags: description: Dictionary of key value pairs of tags. - returned: only if all_facts or stack_resources is true and the stack exists + returned: only if O(all_facts) or O(stack_policy) is V(true) and the stack exists type: dict sample: { 'TagOne': 'ValueOne', diff --git a/plugins/modules/cloudtrail.py b/plugins/modules/cloudtrail.py index 6d9017f6739..45c97cc8abd 100644 --- a/plugins/modules/cloudtrail.py +++ b/plugins/modules/cloudtrail.py @@ -20,9 +20,9 @@ state: description: - Add or remove CloudTrail configuration. - - 'The following states have been preserved for backwards compatibility: I(state=enabled) and I(state=disabled).' - - I(state=enabled) is equivalet to I(state=present). - - I(state=disabled) is equivalet to I(state=absent). + - 'The following states have been preserved for backwards compatibility: O(state=enabled) and O(state=disabled).' + - O(state=enabled) is equivalet to O(state=present). + - O(state=disabled) is equivalet to O(state=absent). type: str choices: ['present', 'absent', 'enabled', 'disabled'] default: present @@ -42,7 +42,7 @@ - An existing S3 bucket where CloudTrail will deliver log files. - This bucket should exist and have the proper policy. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/aggregating_logs_regions_bucket_policy.html). - - Required when I(state=present). + - Required when O(state=present). type: str s3_key_prefix: description: @@ -73,23 +73,23 @@ description: - Specifies a full ARN for an IAM role that assigns the proper permissions for CloudTrail to create and write to the log group. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/send-cloudtrail-events-to-cloudwatch-logs.html). - - Required when C(cloudwatch_logs_log_group_arn). + - Required when O(cloudwatch_logs_log_group_arn). type: str cloudwatch_logs_log_group_arn: description: - A full ARN specifying a valid CloudWatch log group to which CloudTrail logs will be delivered. The log group should already exist. - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/send-cloudtrail-events-to-cloudwatch-logs.html). - - Required when C(cloudwatch_logs_role_arn). + - Required when O(cloudwatch_logs_role_arn). type: str kms_key_id: description: - Specifies the KMS key ID to use to encrypt the logs delivered by CloudTrail. This also has the effect of enabling log file encryption. - The value can be an alias name prefixed by "alias/", a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier. - - Encryption can be disabled by setting I(kms_key_id=""). + - Encryption can be disabled by setting O(kms_key_id=""). - See U(https://docs.aws.amazon.com/awscloudtrail/latest/userguide/encrypting-cloudtrail-log-files-with-aws-kms.html). type: str notes: - - The I(purge_tags) option was added in release 4.0.0 + - The O(purge_tags) option was added in release 4.0.0. extends_documentation_fragment: - amazon.aws.common.modules @@ -151,53 +151,59 @@ RETURN = r""" exists: - description: whether the resource exists + description: whether the resource exists. returned: always type: bool sample: true trail: - description: CloudTrail resource details + description: CloudTrail resource details. returned: always type: complex sample: hash/dictionary of values contains: trail_arn: - description: Full ARN of the CloudTrail resource + description: Full ARN of the CloudTrail resource. returned: success type: str sample: arn:aws:cloudtrail:us-east-1:123456789012:trail/default name: - description: Name of the CloudTrail resource + description: Name of the CloudTrail resource. returned: success type: str sample: default is_logging: - description: Whether logging is turned on or paused for the Trail + description: Whether logging is turned on or paused for the Trail. returned: success type: bool sample: True s3_bucket_name: - description: S3 bucket name where log files are delivered + description: S3 bucket name where log files are delivered. returned: success type: str sample: myBucket s3_key_prefix: - description: Key prefix in bucket where log files are delivered (if any) + description: Key prefix in bucket where log files are delivered (if any). returned: success when present type: str sample: myKeyPrefix log_file_validation_enabled: - description: Whether log file validation is enabled on the trail + description: Whether log file validation is enabled on the trail. returned: success type: bool sample: true include_global_service_events: - description: Whether global services (IAM, STS) are logged with this trail + description: Whether global services (IAM, STS) are logged with this trail. returned: success type: bool sample: true is_multi_region_trail: - description: Whether the trail applies to all regions or just one + description: Whether the trail applies to all regions or just one. + returned: success + type: bool + sample: true + is_organization_trail: + description: + - Specifies whether the trail is created for all accounts in an organization in Organizations, or only for the current Amazon Web Services account. returned: success type: bool sample: true @@ -206,6 +212,11 @@ returned: success type: bool sample: False + has_insight_selectors: + description: Whether any insight selectors are used for this trail. + returned: success + type: bool + sample: False home_region: description: The home region where the trail was originally created and must be edited. returned: success diff --git a/plugins/modules/cloudtrail_info.py b/plugins/modules/cloudtrail_info.py index d1e51baf886..2cae49b6e5c 100644 --- a/plugins/modules/cloudtrail_info.py +++ b/plugins/modules/cloudtrail_info.py @@ -8,7 +8,7 @@ --- module: cloudtrail_info version_added: 5.0.0 -short_description: Gather information about trails in AWS Cloud Trail. +short_description: Gather information about trails in AWS Cloud Trail description: - Gather information about trails in AWS CloudTrail. author: "Gomathi Selvi Srinivasan (@GomathiselviS)" @@ -116,9 +116,21 @@ latest_delivery_error: description: Displays any Amazon S3 error that CloudTrail encountered when attempting to deliver log files to the designated bucket. type: str + latest_notification_attempt_time: + description: Specifies the date and time that CloudTrail last attempt to deliver a notification. + type: str + latest_notification_attempt_succeeded: + description: Specifies the date and time that CloudTrail last successful attempt to deliver a notification. + type: str latest_notification_error: description: Displays any Amazon SNS error that CloudTrail encountered when attempting to send a notification. type: str + latest_delivery_attempt_succeeded: + description: Specifies the date and time that CloudTrail last successful attempt to deliver log files to an account's Amazon S3 bucket. + type: str + latest_delivery_attempt_time: + description: Specifies the date and time that CloudTrail last attempt to deliver log files to an account's Amazon S3 bucket. + type: str latest_delivery_time: description: Specifies the date and time that CloudTrail last delivered log files to an account's Amazon S3 bucket. type: str diff --git a/plugins/modules/cloudwatch_metric_alarm.py b/plugins/modules/cloudwatch_metric_alarm.py index e3a1749135b..ff82a9b770a 100644 --- a/plugins/modules/cloudwatch_metric_alarm.py +++ b/plugins/modules/cloudwatch_metric_alarm.py @@ -6,12 +6,12 @@ DOCUMENTATION = r""" module: cloudwatch_metric_alarm -short_description: "Create/update or delete AWS CloudWatch 'metric alarms'" +short_description: Create/update or delete AWS CloudWatch 'metric alarms' version_added: 5.0.0 description: - Can create or delete AWS CloudWatch metric alarms. - Metrics you wish to alarm on must already exist. - - Prior to release 5.0.0 this module was called C(community.aws.ec2_metric_alarm). + - Prior to release 5.0.0 this module was called M(community.aws.ec2_metric_alarm). The usage did not change. - This module was originally added to C(community.aws) in release 1.0.0. author: @@ -30,7 +30,7 @@ type: str metric_name: description: - - Name of the monitored metric (e.g. C(CPUUtilization)). + - Name of the monitored metric (e.g. V(CPUUtilization)). - Metric must already exist. required: false type: str @@ -69,7 +69,7 @@ type: str required: True dimensions: - description: a name/value pair that is part of the identity of a metric. + description: A name/value pair that is part of the identity of a metric. type: list elements: dict required: false @@ -118,13 +118,13 @@ required: false namespace: description: - - Name of the appropriate namespace (C(AWS/EC2), C(System/Linux), etc.), which determines the category it will appear under in CloudWatch. + - Name of the appropriate namespace (V(AWS/EC2), V(System/Linux), etc.), which determines the category it will appear under in CloudWatch. required: false type: str statistic: description: - Operation applied to the metric. - - Works in conjunction with I(period) and I(evaluation_periods) to determine the comparison value. + - Works in conjunction with O(period) and O(evaluation_periods) to determine the comparison value. required: false choices: ['SampleCount','Average','Sum','Minimum','Maximum'] type: str @@ -153,6 +153,14 @@ - The time (in seconds) between metric evaluations. required: false type: int + evaluate_low_sample_count_percentile: + description: + - Used only for alarms based on percentiles. + - If you specify V(ignore), the alarm state does not change during periods with too few data points to be statistically significant. + - If you specify V(evaluate) or omit this parameter, alarm is evaluated and possibly changes state no matter how many data points are available. + type: str + choices: ['ignore', 'evaluate'] + version_added: 9.0.0 evaluation_periods: description: - The number of times in which the metric is evaluated before final calculation. @@ -205,21 +213,21 @@ type: dict alarm_actions: description: - - A list of the names action(s) taken when the alarm is in the C(alarm) status, denoted as Amazon Resource Name(s). + - A list of the names action(s) taken when the alarm is in the V(alarm) status, denoted as Amazon Resource Name(s). required: false type: list elements: str default: [] insufficient_data_actions: description: - - A list of the names of action(s) to take when the alarm is in the C(insufficient_data) status. + - A list of the names of action(s) to take when the alarm is in the V(insufficient_data) status. required: false type: list elements: str default: [] ok_actions: description: - - A list of the names of action(s) to take when the alarm is in the C(ok) status, denoted as Amazon Resource Name(s). + - A list of the names of action(s) to take when the alarm is in the V(ok) status, denoted as Amazon Resource Name(s). required: false type: list elements: str @@ -241,8 +249,6 @@ - amazon.aws.boto3 """ -RETURN = r""" # """ - EXAMPLES = r""" - name: create alarm amazon.aws.cloudwatch_metric_alarm: @@ -255,6 +261,7 @@ comparison: "LessThanOrEqualToThreshold" threshold: 5.0 period: 300 + evaluate_low_sample_count_percentile: "ignore" evaluation_periods: 3 unit: "Percent" description: "This will alarm when a instance's CPU usage average is lower than 5% for 15 minutes" @@ -299,6 +306,126 @@ alarm_actions: ["arn:aws:automate:us-west-1:ec2:recover"] """ +RETURN = r""" +actions_enabled: + description: Indicates whether actions should be executed during any changes to the alarm state. + returned: always + type: bool +name: + description: Unique name for the alarm. + returned: always + type: str +alarm_arn: + description: The Amazon Resource Name (ARN) of the alarm. + returned: always + type: str +description: + description: The description of the alarm. + returned: always + type: str +last_updated: + description: The time stamp of the last update to the alarm configuration. + returned: always + type: str +ok_actions: + description: The actions to execute when this alarm transitions to an OK state from any other state. + returned: always + type: list + elements: str +alarm_actions: + description: The actions to execute when this alarm transitions to an ALARM state from any other state. + returned: always + type: list + elements: str +insufficient_data_actions: + description: The actions to execute when this alarm transitions to an INSUFFICIENT_DATA state from any other state. + returned: always + type: list + elements: str +state_value: + description: The state value for the alarm. + returned: always + type: str +state_reason: + description: An explanation for the alarm state, in text format. + returned: always + type: str +metric: + description: Name of the monitored metric (e.g. C(CPUUtilization)). + returned: always + type: str +metric_name: + description: Name of the monitored metric (e.g. C(CPUUtilization)). + returned: always + type: str +namespace: + description: + - Name of the appropriate namespace (C(AWS/EC2), C(System/Linux), etc.). + - Determines the category it will appear under in CloudWatch. + returned: always + type: str +statistic: + description: The statistic for the metric associated with the alarm, other than percentile. + returned: always + type: str +extended_statistic: + description: The percentile statistic for the metric associated with the alarm. + returned: always + type: str +dimensions: + description: The dimensions for the metric. + returned: always + type: list + elements: dict + contains: + name: + description: The name of the dimension. + returned: always + type: str + value: + description: The value of the dimension. + returned: always + type: str +period: + description: + - The length, in seconds, used each time the metric specified in MetricName is evaluated. + - Valid values are 10, 30, and any multiple of 60. + returned: always + type: int +unit: + description: Unit used when storing the metric + returned: always + type: str +evaluation_periods: + description: The number of periods over which data is compared to the specified threshold. + returned: always + type: int +threshold: + description: The value to compare with the specified statistic. + returned: always + type: float +comparison: + description: The arithmetic operation to use when comparing the specified statistic and threshold. + returned: always + type: str +treat_missing_data: + description: Sets how alarm is to handle missing data points. + returned: always + type: str +evaluate_low_sample_count_percentile: + description: + - Used only for alarms based on percentiles. + - If I(ignore), the alarm state does not change during periods with too few data points to be statistically significant. + - If I(evaluate) or this parameter is not used, the alarm is always evaluated and possibly changes state. + returned: always + type: str +metrics: + description: An array of MetricDataQuery structures, used in an alarm based on a metric math expression. + returned: always + type: list + elements: dict +""" + try: from botocore.exceptions import ClientError except ImportError: @@ -381,6 +508,8 @@ def create_metric_alarm(connection, module, params): comparison=result.get("ComparisonOperator"), description=result.get("AlarmDescription"), dimensions=result.get("Dimensions"), + extended_statistic=result.get("ExtendedStatistic"), + evaluate_low_sample_count_percentile=result.get("EvaluateLowSampleCountPercentile"), evaluation_periods=result.get("EvaluationPeriods"), insufficient_data_actions=result.get("InsufficientDataActions"), last_updated=result.get("AlarmConfigurationUpdatedTimestamp"), @@ -462,6 +591,7 @@ def main(): "None", ], ), + evaluate_low_sample_count_percentile=dict(type="str", choices=["ignore", "evaluate"]), evaluation_periods=dict(type="int"), extended_statistic=dict(type="str"), description=dict(type="str"), @@ -503,6 +633,7 @@ def main(): params["ComparisonOperator"] = module.params.get("comparison") params["Threshold"] = module.params.get("threshold") params["Period"] = module.params.get("period") + params["EvaluateLowSampleCountPercentile"] = module.params.get("evaluate_low_sample_count_percentile") params["EvaluationPeriods"] = module.params.get("evaluation_periods") if module.params.get("unit"): params["Unit"] = module.params.get("unit") diff --git a/plugins/modules/cloudwatch_metric_alarm_info.py b/plugins/modules/cloudwatch_metric_alarm_info.py index 1e5287dcd10..8284a363643 100644 --- a/plugins/modules/cloudwatch_metric_alarm_info.py +++ b/plugins/modules/cloudwatch_metric_alarm_info.py @@ -23,13 +23,13 @@ alarm_name_prefix: description: - An alarm name prefix to retrieve information about alarms that have names that start with this prefix. - - Can not be used with I(alarm_names). + - Can not be used with O(alarm_names). required: false type: str alarm_type: description: - Specify this to return metric alarms or composite alarms. - - Module is defaulted to return metric alarms but can return composite alarms if I(alarm_type=CompositeAlarm). + - Module is defaulted to return metric alarms but can return composite alarms if O(alarm_type=CompositeAlarm). required: false type: str default: MetricAlarm @@ -147,7 +147,7 @@ type: str namespace: description: - - Name of the appropriate namespace (C(AWS/EC2), C(System/Linux), etc.). + - Name of the appropriate namespace (V(AWS/EC2), V(System/Linux), etc.). - Determines the category it will appear under in CloudWatch. returned: always type: str diff --git a/plugins/modules/cloudwatchevent_rule.py b/plugins/modules/cloudwatchevent_rule.py index e8565546dfe..800edb1e2b3 100644 --- a/plugins/modules/cloudwatchevent_rule.py +++ b/plugins/modules/cloudwatchevent_rule.py @@ -20,10 +20,11 @@ author: - "Jim Dalton (@jsdalton) " notes: - - A rule must contain at least an I(event_pattern) or I(schedule_expression). A - rule can have both an I(event_pattern) and a I(schedule_expression), in which + - A rule must contain at least an O(event_pattern) or O(schedule_expression). A + rule can have both an O(event_pattern) and a O(schedule_expression), in which case the rule will trigger on matching events as well as on a schedule. - - When specifying targets, I(input), I(input_path), I(input_paths_map) and I(input_template) + - When specifying targets, O(targets.input), O(targets.input_path), + O(targets.input_transformer.input_paths_map) and O(targets.input_transformer.input_template) are mutually-exclusive and optional parameters. options: name: @@ -83,14 +84,14 @@ type: json description: - A JSON object that will override the event data passed to the target. - - If neither I(input) nor I(input_path) nor I(input_transformer) + - If neither O(targets.input) nor O(targets.input_path) nor O(targets.input_transformer) is specified, then the entire event is passed to the target in JSON form. input_path: type: str description: - - A JSONPath string (e.g. C($.detail)) that specifies the part of the event data to be + - A JSONPath string (e.g. V($.detail)) that specifies the part of the event data to be passed to the target. - - If neither I(input) nor I(input_path) nor I(input_transformer) + - If neither O(targets.input) nor O(targets.input_path) nor O(targets.input_transformer) is specified, then the entire event is passed to the target in JSON form. input_transformer: type: dict @@ -120,7 +121,7 @@ required: true task_count: type: int - description: The number of tasks to create based on I(task_definition). + description: The number of tasks to create based on task definition. required: false """ @@ -167,17 +168,52 @@ description: CloudWatch Event rule data. returned: success type: dict - sample: - arn: 'arn:aws:events:us-east-1:123456789012:rule/MyCronTask' - description: 'Run my scheduled task' - name: 'MyCronTask' - schedule_expression: 'cron(0 20 * * ? *)' - state: 'ENABLED' + contains: + name: + description: + - The name of the rule you are creating, updating or deleting. + returned: success + type: str + sample: "MyCronTask" + schedule_expression: + description: + - A cron or rate expression that defines the schedule the rule will trigger on. + returned: success + type: str + sample: 'cron(0 20 * * ? *)' + state: + description: + - Whether the rule is present (and enabled), disabled, or absent. + returned: success + type: str + sample: "enabled" + description: + description: + - A description of the rule. + returned: success + type: str + sample: "Run my scheduled task" + arn: + description: The ARN associated with the rule. + type: str + returned: success + sample: 'arn:aws:events:us-east-1:123456789012:rule/MyCronTask' targets: description: CloudWatch Event target(s) assigned to the rule. returned: success type: list - sample: "[{ 'arn': 'arn:aws:lambda:us-east-1:123456789012:function:MyFunction', 'id': 'MyTargetId' }]" + elements: dict + contains: + id: + description: The unique target assignment ID. + type: str + returned: success + sample: 'MyTargetId' + arn: + description: The ARN associated with the target. + type: str + returned: success + sample: 'arn:aws:lambda:us-east-1:123456789012:function:MyFunction' """ import json diff --git a/plugins/modules/cloudwatchlogs_log_group.py b/plugins/modules/cloudwatchlogs_log_group.py index f499c478f4b..f47fa95ff69 100644 --- a/plugins/modules/cloudwatchlogs_log_group.py +++ b/plugins/modules/cloudwatchlogs_log_group.py @@ -14,7 +14,7 @@ - This module was originally added to C(community.aws) in release 1.0.0. notes: - For details of the parameters and returns see U(http://boto3.readthedocs.io/en/latest/reference/services/logs.html). - - Support for I(purge_tags) was added in release 4.0.0. + - Support for O(purge_tags) was added in release 4.0.0. author: - Willian Ricardo (@willricardo) options: @@ -39,20 +39,20 @@ description: - The number of days to retain the log events in the specified log group. - "Valid values are: [1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653]" - - Mutually exclusive with I(purge_retention_policy). + - Mutually exclusive with O(purge_retention_policy). required: false type: int purge_retention_policy: description: - - "Whether to purge the retention policy or not." - - "Mutually exclusive with I(retention) and I(overwrite)." + - Whether to purge the retention policy or not. + - Mutually exclusive with O(retention) and O(overwrite). default: false required: false type: bool overwrite: description: - Whether an existing log group should be overwritten on create. - - Mutually exclusive with I(purge_retention_policy). + - Mutually exclusive with O(purge_retention_policy). default: false required: false type: bool @@ -90,8 +90,40 @@ """ RETURN = r""" +log_group_name: + description: The name of the log group. + returned: always + type: str +creation_time: + description: The creation time of the log group. + returned: always + type: int +retention_in_days: + description: The number of days to retain the log events in the specified log group. + returned: always + type: int +metric_filter_count: + description: The number of metric filters. + returned: always + type: int +arn: + description: The Amazon Resource Name (ARN) of the log group. + returned: always + type: str +stored_bytes: + description: The number of bytes stored. + returned: always + type: str +kms_key_id: + description: The Amazon Resource Name (ARN) of the CMK to use when encrypting log data. + returned: always + type: str +tags: + description: A dictionary representing the tags on the log group. + returned: always + type: dict log_groups: - description: Return the list of complex objects representing log groups + description: Return the list of complex objects representing log groups. returned: success type: complex version_added: 4.0.0 diff --git a/plugins/modules/cloudwatchlogs_log_group_info.py b/plugins/modules/cloudwatchlogs_log_group_info.py index 453d268d52b..f2770519e7a 100644 --- a/plugins/modules/cloudwatchlogs_log_group_info.py +++ b/plugins/modules/cloudwatchlogs_log_group_info.py @@ -33,7 +33,7 @@ RETURN = r""" log_groups: - description: Return the list of complex objects representing log groups + description: Return the list of complex objects representing log groups. returned: success type: complex contains: diff --git a/plugins/modules/cloudwatchlogs_log_group_metric_filter.py b/plugins/modules/cloudwatchlogs_log_group_metric_filter.py index b8bf0884b6a..8eddb671bed 100644 --- a/plugins/modules/cloudwatchlogs_log_group_metric_filter.py +++ b/plugins/modules/cloudwatchlogs_log_group_metric_filter.py @@ -34,11 +34,11 @@ type: str filter_pattern: description: - - A filter pattern for extracting metric data out of ingested log events. Required when I(state=present). + - A filter pattern for extracting metric data out of ingested log events. Required when O(state=present). type: str metric_transformation: description: - - A collection of information that defines how metric data gets emitted. Required when I(state=present). + - A collection of information that defines how metric data gets emitted. Required when O(state=present). type: dict suboptions: metric_name: @@ -84,7 +84,7 @@ RETURN = r""" metric_filters: - description: Return the origin response value + description: Return the origin response value. returned: success type: list sample: [ diff --git a/plugins/modules/ec2_ami.py b/plugins/modules/ec2_ami.py index 00ead5ce5cc..699f22680c3 100644 --- a/plugins/modules/ec2_ami.py +++ b/plugins/modules/ec2_ami.py @@ -61,7 +61,7 @@ default: '' no_reboot: description: - - Flag indicating that the bundling process should not attempt to shutdown the instance before bundling. If this flag is True, the + - Flag indicating that the bundling process should not attempt to shutdown the instance before bundling. If this flag is V(true), the responsibility of maintaining file system integrity is left to the owner of the instance. default: false type: bool @@ -78,7 +78,7 @@ device_name: type: str description: - - The device name. For example C(/dev/sda). + - The device name. For example V(/dev/sda). required: true virtual_name: type: str @@ -91,7 +91,7 @@ - Suppresses the specified device included in the block device mapping of the AMI. volume_type: type: str - description: The volume type. Defaults to C(gp2) when not set. + description: The volume type. Defaults to V(gp2) when not set. delete_on_termination: type: bool description: Whether the device should be automatically deleted when the Instance is terminated. @@ -100,7 +100,7 @@ description: The ID of the Snapshot. iops: type: int - description: When using an C(io1) I(volume_type) this sets the number of IOPS provisioned for the volume. + description: When using O(device_mapping.volume_type=io1), this sets the number of IOPS provisioned for the volume. encrypted: type: bool description: Whether the volume should be encrypted. @@ -172,18 +172,16 @@ version_added: 5.5.0 tpm_support: description: - - Set to v2.0 to enable Trusted Platform Module (TPM) support. - - If the image is configured for NitroTPM support, the value is v2.0 . - - Requires I(boot_mode) to be set to 'uefi'. + - Set to V(v2.0) to enable Trusted Platform Module (TPM) support. + - If the image is configured for NitroTPM support, the value is V(v2.0). + - Requires O(boot_mode) to be set to V(uefi). - Requires an instance type that is compatible with Nitro. - - Requires minimum botocore version 1.26.0. - See the AWS documentation for more detail U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html). type: str version_added: 5.5.0 uefi_data: description: - Base64 representation of the non-volatile UEFI variable store. - - Requires minimum botocore version 1.26.0. - See the AWS documentation for more detail U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/uefi-secure-boot.html). type: str version_added: 5.5.0 @@ -339,6 +337,11 @@ returned: when AMI is created or already exists type: str sample: "nat-server" +enhanced_networking: + description: Specifies whether enhanced networking with ENA is enabled. + returned: when AMI is created or already exists + type: bool + sample: true hypervisor: description: Type of hypervisor. returned: when AMI is created or already exists @@ -349,11 +352,26 @@ returned: when AMI is created or already exists type: str sample: "ami-1234abcd" +image_owner_alias: + description: The owner alias ( amazon | aws-marketplace). + returned: when AMI is created or already exists + type: str + sample: "amazon" +image_type: + description: Type of image. + returned: when AMI is created or already exists + type: str + sample: "machine" is_public: description: Whether image is public. returned: when AMI is created or already exists type: bool sample: false +kernel_id: + description: The kernel associated with the image, if any. Only applicable for machine images. + returned: when AMI is created or already exists + type: str + sample: "aki-88aa75e1" launch_permission: description: Permissions allowing other accounts to access the AMI. returned: when AMI is created or already exists @@ -379,6 +397,16 @@ description: Platform of image. returned: when AMI is created or already exists type: str + sample: "Windows" +product_codes: + description: Any product codes associated with the AMI. + returned: when AMI is created or already exists + type: list + sample: [] +ramdisk_id: + description: The RAM disk associated with the image, if any. Only applicable for machine images. + returned: when AMI is created or already exists + type: str sample: null root_device_name: description: Root device name of image. @@ -390,11 +418,24 @@ returned: when AMI is created or already exists type: str sample: "ebs" +sriov_net_support: + description: Specifies whether enhanced networking with the Intel 82599 Virtual Function interface is enabled. + returned: when AMI is created or already exists + type: str + sample: "simple" state: description: State of image. returned: when AMI is created or already exists type: str sample: "available" +state_reason: + description: The reason for the state change. + returned: when AMI is created or already exists + type: dict + sample: { + 'Code': 'string', + 'Message': 'string' + } tags: description: A dictionary of tags assigned to image. returned: when AMI is created or already exists diff --git a/plugins/modules/ec2_ami_info.py b/plugins/modules/ec2_ami_info.py index 2929a0292df..fb6a7cc2d93 100644 --- a/plugins/modules/ec2_ami_info.py +++ b/plugins/modules/ec2_ami_info.py @@ -8,9 +8,9 @@ --- module: ec2_ami_info version_added: 1.0.0 -short_description: Gather information about ec2 AMIs +short_description: Gather information about EC2 AMIs description: - - Gather information about ec2 AMIs + - Gather information about EC2 AMIs. author: - Prasad Katti (@prasadkatti) options: @@ -112,7 +112,6 @@ sample: '2017-10-16T19:22:13.000Z' description: description: The description of the AMI. - returned: always type: str sample: '' ena_support: @@ -142,7 +141,7 @@ sample: machine launch_permissions: description: A List of AWS accounts may launch the AMI. - returned: When image is owned by calling account and I(describe_image_attributes=true). + returned: When image is owned by calling account and O(describe_image_attributes=true). type: list elements: dict contains: @@ -163,6 +162,11 @@ returned: always type: str sample: '123456789012' + platform_details: + description: Platform of image. + returned: always + type: str + sample: "Windows" public: description: Whether the image has public launch permissions. returned: always @@ -180,7 +184,6 @@ sample: ebs sriov_net_support: description: Whether enhanced networking is enabled. - returned: always type: str sample: simple state: @@ -192,6 +195,11 @@ description: Any tags assigned to the image. returned: always type: dict + usage_operation: + description: The operation of the Amazon EC2 instance and the billing code that is associated with the AMI. + returned: always + type: str + sample: "RunInstances" virtualization_type: description: The type of virtualization of the AMI. returned: always diff --git a/plugins/modules/ec2_eip.py b/plugins/modules/ec2_eip.py index 38bf32c87a3..52080ff3685 100644 --- a/plugins/modules/ec2_eip.py +++ b/plugins/modules/ec2_eip.py @@ -18,28 +18,28 @@ description: - The id of the device for the EIP. - Can be an EC2 Instance id or Elastic Network Interface (ENI) id. - - When specifying an ENI id, I(in_vpc) must be C(true) + - When specifying an ENI id, O(in_vpc) must be V(true). - The C(instance_id) alias was removed in release 6.0.0. required: false type: str public_ip: description: - The IP address of a previously allocated EIP. - - When I(state=present) and device is specified, the EIP is associated with the device. - - When I(state=absent) and device is specified, the EIP is disassociated from the device. + - When O(state=present) and device is specified, the EIP is associated with the device. + - When O(state=absent) and device is specified, the EIP is disassociated from the device. aliases: [ ip ] type: str state: description: - - When C(state=present), allocate an EIP or associate an existing EIP with a device. - - When C(state=absent), disassociate the EIP from the device and optionally release it. + - When O(state=present), allocate an EIP or associate an existing EIP with a device. + - When O(state=absent), disassociate the EIP from the device and optionally release it. choices: ['present', 'absent'] default: present type: str in_vpc: description: - Allocate an EIP inside a VPC or not. - - Required if specifying an ENI with I(device_id). + - Required if specifying an ENI with O(device_id). default: false type: bool reuse_existing_ip_allowed: @@ -64,17 +64,17 @@ type: bool tag_name: description: - - When I(reuse_existing_ip_allowed=true), supplement with this option to only reuse - an Elastic IP if it is tagged with I(tag_name). + - When O(reuse_existing_ip_allowed=true), supplement with this option to only reuse + an Elastic IP if it is tagged with O(tag_name). type: str tag_value: description: - - Supplements I(tag_name) but also checks that the value of the tag provided in I(tag_name) matches I(tag_value). + - Supplements O(tag_name) but also checks that the value of the tag provided in O(tag_name) matches O(tag_value). type: str public_ipv4_pool: description: - Allocates the new Elastic IP from the provided public IPv4 pool (BYOIP) - only applies to newly allocated Elastic IPs, isn't validated when I(reuse_existing_ip_allowed=true). + only applies to newly allocated Elastic IPs, isn't validated when O(reuse_existing_ip_allowed=true). type: str extends_documentation_fragment: - amazon.aws.common.modules @@ -92,7 +92,7 @@ - This module returns multiple changed statuses on disassociation or release. It returns an overall status based on any changes occurring. It also returns individual changed statuses for disassociation and release. - - Support for I(tags) and I(purge_tags) was added in release 2.1.0. + - Support for O(tags) and O(purge_tags) was added in release 2.1.0. """ EXAMPLES = r""" @@ -205,12 +205,12 @@ RETURN = r""" allocation_id: - description: allocation_id of the elastic ip + description: Allocation id of the elastic ip. returned: on success type: str sample: eipalloc-51aa3a6c public_ip: - description: an elastic ip address + description: An elastic ip address. returned: on success type: str sample: 52.88.159.209 diff --git a/plugins/modules/ec2_eip_info.py b/plugins/modules/ec2_eip_info.py index c00dc515c84..18d03160e3e 100644 --- a/plugins/modules/ec2_eip_info.py +++ b/plugins/modules/ec2_eip_info.py @@ -18,7 +18,7 @@ filters: description: - A dict of filters to apply. Each dict item consists of a filter key and filter - value. See U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-addresses.html#options) + value. See U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-addresses.html#options) for possible filters. Filter names and values are case sensitive. required: false default: {} @@ -79,19 +79,58 @@ description: Properties of all Elastic IP addresses matching the provided filters. Each element is a dict with all the information related to an EIP. returned: on success type: list - sample: [{ - "allocation_id": "eipalloc-64de1b01", - "association_id": "eipassoc-0fe9ce90d6e983e97", - "domain": "vpc", - "instance_id": "i-01020cfeb25b0c84f", - "network_interface_id": "eni-02fdeadfd4beef9323b", - "network_interface_owner_id": "0123456789", - "private_ip_address": "10.0.0.1", - "public_ip": "54.81.104.1", - "tags": { + elements: dict + contains: + "allocation_id": + description: The ID representing the allocation of the address. + returned: always + type: str + sample: "eipalloc-64de1b01" + "association_id": + description: The ID representing the association of the address with an instance. + type: str + sample: "eipassoc-0fe9ce90d6e983e97" + "domain": + description: The network (vpc). + type: str + returned: always + sample: "vpc" + "instance_id": + description: The ID of the instance that the address is associated with (if any). + returned: if any instance is associated + type: str + sample: "i-01020cfeb25b0c84f" + "network_border_group": + description: The name of the unique set of Availability Zones, Local Zones, or Wavelength Zones from which Amazon Web Services advertises IP addresses. + returned: if any instance is associated + type: str + sample: "us-east-1" + "network_interface_id": + description: The ID of the network interface. + returned: if any instance is associated + type: str + sample: "eni-02fdeadfd4beef9323b" + "network_interface_owner_id": + description: The ID of the network interface. + returned: if any instance is associated + type: str + sample: "0123456789" + "private_ip_address": + description: The private IP address associated with the Elastic IP address. + returned: always + type: str + sample: "10.0.0.1" + "public_ip": + description: The Elastic IP address. + returned: if any instance is associated + type: str + sample: "54.81.104.1" + "tags": + description: Any tags assigned to the Elastic IP address. + type: dict + sample: { "Name": "test-vm-54.81.104.1" } - }] """ try: diff --git a/plugins/modules/ec2_eni.py b/plugins/modules/ec2_eni.py index 604ca924a70..0715dabe0c5 100644 --- a/plugins/modules/ec2_eni.py +++ b/plugins/modules/ec2_eni.py @@ -11,8 +11,8 @@ short_description: Create and optionally attach an Elastic Network Interface (ENI) to an instance description: - Create and optionally attach an Elastic Network Interface (ENI) to an instance. - - If I(eni_id) or I(private_ip) is provided, the existing ENI (if any) will be modified. - - The I(attached) parameter controls the attachment status of the network interface. + - If O(eni_id) or O(private_ip_address) is provided, the existing ENI (if any) will be modified. + - The O(attached) parameter controls the attachment status of the network interface. author: - "Rob White (@wimnat)" - "Mike Healey (@healem)" @@ -20,7 +20,7 @@ eni_id: description: - The ID of the ENI (to modify). - - If I(eni_id=None) and I(state=present), a new ENI will be created. + - If O(eni_id=None) and O(state=present), a new ENI will be created. type: str instance_id: description: @@ -41,7 +41,7 @@ security_groups: description: - List of security groups associated with the interface. - - Ignored when I(state=absent). + - Ignored when O(state=absent). type: list elements: str default: [] @@ -63,8 +63,8 @@ type: bool force_detach: description: - - Force detachment of the interface. This applies either when explicitly detaching the interface by setting I(instance_id=None) - or when deleting an interface with I(state=absent). + - Force detachment of the interface. This applies either when explicitly detaching the interface by setting O(instance_id=None) + or when deleting an interface with O(state=absent). default: false type: bool delete_on_termination: @@ -82,20 +82,20 @@ secondary_private_ip_addresses: description: - A list of IP addresses to assign as secondary IP addresses to the network interface. - - This option is mutually exclusive of I(secondary_private_ip_address_count). + - This option is mutually exclusive of O(secondary_private_ip_address_count). required: false type: list elements: str purge_secondary_private_ip_addresses: description: - - To be used with I(secondary_private_ip_addresses) to determine whether or not to remove any secondary IP addresses other than those specified. - - Set I(secondary_private_ip_addresses=[]) to purge all secondary addresses. + - To be used with O(secondary_private_ip_addresses) to determine whether or not to remove any secondary IP addresses other than those specified. + - Set O(secondary_private_ip_addresses=[]) to purge all secondary addresses. default: false type: bool secondary_private_ip_address_count: description: - The number of secondary IP addresses to assign to the network interface. - - This option is mutually exclusive of I(secondary_private_ip_addresses). + - This option is mutually exclusive of O(secondary_private_ip_addresses). required: false type: int allow_reassignment: @@ -107,10 +107,10 @@ type: bool name: description: - - Name for the ENI. This will create a tag with the key C(Name) and the value assigned here. - - This can be used in conjunction with I(subnet_id) as another means of identifiying a network interface. - - AWS does not enforce unique C(Name) tags, so duplicate names are possible if you configure it that way. - If that is the case, you will need to provide other identifying information such as I(private_ip_address) or I(eni_id). + - Name for the ENI. This will create a tag with the key V(Name) and the value assigned here. + - This can be used in conjunction with O(subnet_id) as another means of identifiying a network interface. + - AWS does not enforce unique V(Name) tags, so duplicate names are possible if you configure it that way. + If that is the case, you will need to provide other identifying information such as O(private_ip_address) or O(eni_id). required: false type: str extends_documentation_fragment: @@ -119,9 +119,9 @@ - amazon.aws.tags - amazon.aws.boto3 notes: - - This module identifies and ENI based on either the I(eni_id), a combination of I(private_ip_address) and I(subnet_id), - or a combination of I(instance_id) and I(device_id). Any of these options will let you specify a particular ENI. - - Support for I(tags) and I(purge_tags) was added in release 1.3.0. + - This module identifies and ENI based on either the O(eni_id), a combination of O(private_ip_address) and O(subnet_id), + or a combination of O(instance_id) and O(device_index). Any of these options will let you specify a particular ENI. + - Support for O(tags) and O(purge_tags) was added in release 1.3.0. """ EXAMPLES = r""" @@ -213,62 +213,72 @@ RETURN = r""" interface: - description: Network interface attributes + description: Network interface attributes. returned: when state != absent type: complex contains: + attachment: + description: The network interface attachment. + type: dict + sample: { + "attach_time": "2024-04-25T20:57:20+00:00", + "attachment_id": "eni-attach-0ddce58b341a1846f", + "delete_on_termination": true, + "device_index": 0, + "instance_id": "i-032cb1cceb29250d2", + "status": "attached" + } description: - description: interface description + description: Interface description. type: str sample: Firewall network interface groups: - description: list of security groups - type: list - elements: dict - sample: [ { "sg-f8a8a9da": "default" } ] + description: Dict of security groups. + type: dict + sample: { "sg-f8a8a9da": "default" } id: - description: network interface id + description: Network interface id. type: str sample: "eni-1d889198" mac_address: - description: interface's physical address + description: Interface's physical address. type: str sample: "00:00:5E:00:53:23" name: - description: The name of the ENI + description: The name of the ENI. type: str sample: "my-eni-20" owner_id: - description: aws account id + description: AWS account id. type: str sample: 812381371 private_ip_address: - description: primary ip address of this interface + description: Primary ip address of this interface. type: str sample: 10.20.30.40 private_ip_addresses: - description: list of all private ip addresses associated to this interface + description: List of all private ip addresses associated to this interface. type: list elements: dict sample: [ { "primary_address": true, "private_ip_address": "10.20.30.40" } ] source_dest_check: - description: value of source/dest check flag + description: Value of source/dest check flag. type: bool sample: True status: - description: network interface status + description: Network interface status. type: str sample: "pending" subnet_id: - description: which vpc subnet the interface is bound + description: Which vpc subnet the interface is bound. type: str sample: subnet-b0a0393c tags: - description: The dictionary of tags associated with the ENI + description: The dictionary of tags associated with the ENI. type: dict sample: { "Name": "my-eni", "group": "Finance" } vpc_id: - description: which vpc this network interface is bound + description: Which vpc this network interface is bound. type: str sample: vpc-9a9a9da """ diff --git a/plugins/modules/ec2_eni_info.py b/plugins/modules/ec2_eni_info.py index 5ef36b2581d..c12f1eb057f 100644 --- a/plugins/modules/ec2_eni_info.py +++ b/plugins/modules/ec2_eni_info.py @@ -17,14 +17,14 @@ eni_id: description: - The ID of the ENI. - - This option is mutually exclusive of I(filters). + - This option is mutually exclusive of O(filters). type: str version_added: 1.3.0 filters: description: - A dict of filters to apply. Each dict item consists of a filter key and a filter value. See U(https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeNetworkInterfaces.html) for possible filters. - - This option is mutually exclusive of I(eni_id). + - This option is mutually exclusive of O(eni_id). type: dict default: {} extends_documentation_fragment: @@ -73,6 +73,7 @@ device_index: 1, instance_id: "i-15b8d3cadbafa1234", instance_owner_id: "123456789012", + "network_card_index": 0, status: "attached" } availability_zone: @@ -96,7 +97,7 @@ } ] id: - description: The id of the ENI (alias for network_interface_id). + description: The id of the ENI (alias for RV(network_interfaces.network_interface_id)). returned: always type: str sample: "eni-392fsdf" @@ -147,7 +148,6 @@ sample: [] requester_id: description: The ID of the entity that launched the ENI. - returned: always type: str sample: "AIDA12345EXAMPLE54321" requester_managed: diff --git a/plugins/modules/ec2_import_image.py b/plugins/modules/ec2_import_image.py index c167d5ce8c0..7ace4c7aa6b 100644 --- a/plugins/modules/ec2_import_image.py +++ b/plugins/modules/ec2_import_image.py @@ -16,8 +16,8 @@ options: state: description: - - Use I(state=present) to import single or multi-volume disk images or EBS snapshots into an Amazon Machine Image (AMI). - - Use I(state=absent) to cancel an in-process import virtual machine task. + - Use O(state=present) to import single or multi-volume disk images or EBS snapshots into an Amazon Machine Image (AMI). + - Use O(state=absent) to cancel an in-process import virtual machine task. default: "present" choices: ["present", "absent"] type: str @@ -101,7 +101,7 @@ encrypted: description: - Specifies whether the destination AMI of the imported image should be encrypted. - - The default KMS key for EBS is used unless you specify a non-default KMS key using I(kms_key_id). + - The default KMS key for EBS is used unless you specify a non-default KMS key using O(kms_key_id). type: bool hypervisor: description: @@ -113,7 +113,7 @@ - An identifier for the symmetric KMS key to use when creating the encrypted AMI. This parameter is only required if you want to use a non-default KMS key; if this parameter is not specified, the default KMS key for EBS is used. - If a I(kms_key_id) is specified, the I(encrypted) flag must also be set. + If a O(kms_key_id) is specified, the O(encrypted) flag must also be set. type: str license_type: description: diff --git a/plugins/modules/ec2_instance.py b/plugins/modules/ec2_instance.py index 79b333f33b1..b853dc544d5 100644 --- a/plugins/modules/ec2_instance.py +++ b/plugins/modules/ec2_instance.py @@ -20,27 +20,27 @@ instance_ids: description: - If you specify one or more instance IDs, only instances that have the specified IDs are returned. - - Mutually exclusive with I(exact_count). + - Mutually exclusive with O(exact_count). type: list elements: str default: [] state: description: - Goal state for the instances. - - "I(state=present): ensures instances exist, but does not guarantee any state (e.g. running). Newly-launched instances will be run by EC2." - - "I(state=running): I(state=present) + ensures the instances are running" - - "I(state=started): I(state=running) + waits for EC2 status checks to report OK if I(wait=true)" - - "I(state=stopped): ensures an existing instance is stopped." - - "I(state=rebooted): convenience alias for I(state=stopped) immediately followed by I(state=running)" - - "I(state=restarted): convenience alias for I(state=stopped) immediately followed by I(state=started)" - - "I(state=terminated): ensures an existing instance is terminated." - - "I(state=absent): alias for I(state=terminated)" + - "O(state=present): ensures instances exist, but does not guarantee any state (e.g. running). Newly-launched instances will be run by EC2." + - "O(state=running): O(state=present) + ensures the instances are running." + - "O(state=started): O(state=running) + waits for EC2 status checks to report OK if O(wait=true)." + - "O(state=stopped): ensures an existing instance is stopped." + - "O(state=rebooted): convenience alias for O(state=stopped) immediately followed by O(state=running)." + - "O(state=restarted): convenience alias for O(state=stopped) immediately followed by O(state=started)." + - "O(state=terminated): ensures an existing instance is terminated." + - "O(state=absent): alias for O(state=terminated)." choices: [present, terminated, running, started, stopped, restarted, rebooted, absent] default: present type: str wait: description: - - Whether or not to wait for the desired I(state) (use (wait_timeout) to customize this). + - Whether or not to wait for the desired O(state) (use O(wait_timeout) to customize this). default: true type: bool wait_timeout: @@ -53,22 +53,22 @@ - Instance type to use for the instance, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html). - Only required when instance is not already present. - - At least one of I(instance_type) or I(launch_template) must be specificed when launching an + - At least one of O(instance_type) or O(launch_template) must be specificed when launching an instance. type: str count: description: - Number of instances to launch. - Setting this value will result in always launching new instances. - - Mutually exclusive with I(exact_count). + - Mutually exclusive with O(exact_count). type: int version_added: 2.2.0 exact_count: description: - - An integer value which indicates how many instances that match the I(filters) parameter should be running. + - An integer value which indicates how many instances that match the O(filters) parameter should be running. - Instances are either created or terminated based on this value. - If termination takes place, least recently created instances will be terminated based on Launch Time. - - Mutually exclusive with I(count), I(instance_ids). + - Mutually exclusive with O(count), O(instance_ids). type: int version_added: 2.2.0 user_data: @@ -79,45 +79,45 @@ description: - Preconfigured user-data to enable an instance to perform an Ansible Automation Platform callback (Linux only). - - For Windows instances, to enable remote access via Ansible set I(windows) to C(true), and + - For Windows instances, to enable remote access via Ansible set O(aap_callback.windows) to V(true), and optionally set an admin password. - - If using I(windows) and I(set_password), callback ton Ansible Automation Platform will not + - If using O(aap_callback.windows) and O(aap_callback.set_password), callback ton Ansible Automation Platform will not be performed but the instance will be ready to receive winrm connections from Ansible. - - Mutually exclusive with I(user_data). + - Mutually exclusive with O(user_data). type: dict aliases: ['tower_callback'] suboptions: windows: description: - - Set I(windows=True) to use powershell instead of bash for the callback script. + - Set O(aap_callback.windows=True) to use powershell instead of bash for the callback script. type: bool default: False set_password: description: - - Optional admin password to use if I(windows=True). + - Optional admin password to use if O(aap_callback.windows=True). type: str tower_address: description: - IP address or DNS name of Tower server. Must be accessible via this address from the VPC that this instance will be launched in. - - Required if I(windows=False). + - Required if O(aap_callback.windows=False). type: str job_template_id: description: - Either the integer ID of the Tower Job Template, or the name. Using a name for the job template is not supported by Ansible Tower prior to version 3.2. - - Required if I(windows=False). + - Required if O(aap_callback.windows=False). type: str host_config_key: description: - Host configuration secret key generated by the Tower job template. - - Required if I(windows=False). + - Required if O(aap_callback.windows=False). type: str image: description: - An image to use for the instance. The M(amazon.aws.ec2_ami_info) module may be used to retrieve images. - One of I(image) or I(image_id) are required when instance is not already present. + One of O(image) or O(image_id) are required when instance is not already present. type: dict suboptions: id: @@ -133,20 +133,20 @@ - a string AKI to override the AMI kernel. image_id: description: - - I(ami) ID to use for the instance. One of I(image) or I(image_id) are required when instance is not already present. - - This is an alias for I(image.id). + - I(ami) ID to use for the instance. One of O(image) or O(image_id) are required when instance is not already present. + - This is an alias for O(image.id). type: str security_groups: description: - A list of security group IDs or names (strings). - - Mutually exclusive with I(security_group). + - Mutually exclusive with O(security_group). type: list elements: str default: [] security_group: description: - A security group ID or name. - - Mutually exclusive with I(security_groups). + - Mutually exclusive with O(security_groups). type: str name: description: @@ -167,7 +167,7 @@ suboptions: interfaces: description: - - A list of ENI IDs (strings) or a list of objects containing the key I(id). + - A list of ENI IDs (strings) or a list of objects containing the key id. type: list elements: str assign_public_ip: @@ -217,15 +217,15 @@ volumes: description: - A list of block device mappings, by default this will always use the AMI root device so the volumes option is primarily for adding more storage. - - A mapping contains the (optional) keys C(device_name), C(virtual_name), C(ebs.volume_type), C(ebs.volume_size), C(ebs.kms_key_id), - C(ebs.snapshot_id), C(ebs.iops), and C(ebs.delete_on_termination). + - A mapping contains the (optional) keys V(device_name), V(virtual_name), V(ebs.volume_type), V(ebs.volume_size), V(ebs.kms_key_id), + V(ebs.snapshot_id), V(ebs.iops), and V(ebs.delete_on_termination). - For more information about each parameter, see U(https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html). type: list elements: dict launch_template: description: - The EC2 launch template to base instance configuration on. - - At least one of I(instance_type) or I(launch_template) must be specificed when launching an + - At least one of O(instance_type) or O(launch_template) must be specificed when launching an instance. type: dict suboptions: @@ -247,7 +247,7 @@ type: str availability_zone: description: - - Specify an availability zone to use the default subnet it. Useful if not specifying the I(vpc_subnet_id) parameter. + - Specify an availability zone to use the default subnet it. Useful if not specifying the O(vpc_subnet_id) parameter. - If no subnet, ENI, or availability zone is provided, the default subnet in the default VPC will be used in the first AZ (alphabetically sorted). type: str instance_initiated_shutdown_behavior: @@ -257,8 +257,8 @@ type: str tenancy: description: - - What type of tenancy to allow an instance to use. Default is shared tenancy. Dedicated tenancy will incur additional charges. - - This field is deprecated and will be removed in a release after 2025-12-01, use I(placement) instead. + - What type of tenancy to allow an instance to use. Default is V(shared) tenancy. Dedicated tenancy will incur additional charges. + - This field is deprecated and will be removed in a release after 2025-12-01, use O(placement) instead. choices: ['dedicated', 'default'] type: str termination_protection: @@ -277,13 +277,13 @@ cpu_credit_specification: description: - For T series instances, choose whether to allow increased charges to buy CPU credits if the default pool is depleted. - - Choose C(unlimited) to enable buying additional CPU credits. + - Choose V(unlimited) to enable buying additional CPU credits. choices: ['unlimited', 'standard'] type: str cpu_options: description: - Reduce the number of vCPU exposed to the instance. - - Those parameters can only be set at instance launch. The two suboptions threads_per_core and core_count are mandatory. + - Those parameters can only be set at instance launch. The two suboptions O(cpu_options.threads_per_core) and O(cpu_options.core_count) are mandatory. - See U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) for combinations available. type: dict suboptions: @@ -326,7 +326,7 @@ placement_group: description: - The placement group that needs to be assigned to the instance. - - This field is deprecated and will be removed in a release after 2025-12-01, use I(placement) instead. + - This field is deprecated and will be removed in a release after 2025-12-01, use O(placement) instead. type: str placement: description: @@ -361,7 +361,7 @@ tenancy: description: - Type of tenancy to allow an instance to use. Default is shared tenancy. Dedicated tenancy will incur additional charges. - - Support for I(tenancy=host) was added in amazon.aws 7.6.0. + - Support for O(tenancy=host) was added in amazon.aws 7.6.0. type: str required: false choices: ['dedicated', 'default', 'host'] @@ -384,7 +384,7 @@ description: - Modify the metadata options for the instance. - See U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) for more information. - - The two suboptions I(http_endpoint) and I(http_tokens) are supported. + - The two suboptions O(metadata_options.http_endpoint) and O(metadata_options.http_tokens) are supported. type: dict version_added: 2.0.0 suboptions: @@ -414,14 +414,14 @@ version_added: 4.0.0 type: str description: - - Whether the instance metadata endpoint is available via IPv6 (C(enabled)) or not (C(disabled)). + - Whether the instance metadata endpoint is available via IPv6 (V(enabled)) or not (V(disabled)). choices: [enabled, disabled] default: 'disabled' instance_metadata_tags: version_added: 4.0.0 type: str description: - - Whether the instance tags are availble (C(enabled)) via metadata endpoint or not (C(disabled)). + - Whether the instance tags are availble (V(enabled)) via metadata endpoint or not (V(disabled)). choices: [enabled, disabled] default: 'disabled' @@ -606,26 +606,26 @@ RETURN = r""" instance_ids: - description: a list of ec2 instance IDs matching the provided specification and filters + description: A list of EC2 instance IDs matching the provided specification and filters. returned: always type: list sample: ["i-0123456789abcdef0", "i-0123456789abcdef1"] version_added: 5.3.0 changed_ids: - description: a list of the set of ec2 instance IDs changed by the module action + description: A list of the set of EC2 instance IDs changed by the module action. returned: when instances that must be present are launched type: list sample: ["i-0123456789abcdef0"] version_added: 5.3.0 terminated_ids: - description: a list of the set of ec2 instance IDs terminated by the module action + description: A list of the set of EC2 instance IDs terminated by the module action. returned: when instances that must be absent are terminated type: list sample: ["i-0123456789abcdef1"] version_added: 5.3.0 instances: - description: a list of ec2 instances - returned: when wait == true or when matching instances already exist + description: A list of EC2 instances. + returned: when O(wait=true) or when matching instances already exist type: complex contains: ami_launch_index: @@ -634,7 +634,7 @@ type: int sample: 0 architecture: - description: The architecture of the image + description: The architecture of the image. returned: always type: str sample: x86_64 @@ -669,20 +669,71 @@ type: str sample: attached volume_id: - description: The ID of the EBS volume + description: The ID of the EBS volume. returned: always type: str sample: vol-12345678 + capacity_reservation_specification: + description: Information about the Capacity Reservation targeting option. + type: complex + contains: + capacity_reservation_preference: + description: Describes the Capacity Reservation preferences. + type: str + sample: open client_token: description: The idempotency token you provided when you launched the instance, if applicable. returned: always type: str sample: mytoken + cpu_options: + description: The CPU options for the instance. + type: complex + contains: + core_count: + description: The number of CPU cores for the instance. + type: int + sample: 1 + threads_per_core: + description: The number of threads per CPU core. + type: int + sample: 2 + amd_sev_snp: + description: Indicates whether the instance is enabled for AMD SEV-SNP. + type: str + sample: enabled + current_instance_boot_mode: + description: The boot mode that is used to boot the instance at launch or start. + type: str + sample: legacy-bios ebs_optimized: description: Indicates whether the instance is optimized for EBS I/O. returned: always type: bool sample: false + ena_support: + description: Specifies whether enhanced networking with ENA is enabled. + returned: always + type: bool + sample: true + enclave_options: + description: Indicates whether the instance is enabled for Amazon Web Services Nitro Enclaves. + type: dict + contains: + enabled: + description: If this parameter is set to true, the instance is enabled for Amazon Web Services Nitro Enclaves. + returned: always + type: bool + sample: false + hibernation_options: + description: Indicates whether the instance is enabled for hibernation. + type: dict + contains: + configured: + description: If true, your instance is enabled for hibernation; otherwise, it is not enabled for hibernation. + returned: always + type: bool + sample: false hypervisor: description: The hypervisor type of the instance. returned: always @@ -699,7 +750,7 @@ type: str sample: "arn:aws:iam::123456789012:instance-profile/myprofile" id: - description: The ID of the instance profile + description: The ID of the instance profile. returned: always type: str sample: JFJ397FDG400FG9FD1N @@ -739,6 +790,35 @@ returned: always type: str sample: arn:aws:license-manager:us-east-1:123456789012:license-configuration:lic-0123456789 + metadata_options: + description: The metadata options for the instance. + returned: always + type: complex + contains: + http_endpoint: + description: Indicates whether the HTTP metadata endpoint on your instances is enabled or disabled. + type: str + sample: enabled + http_protocol_ipv6: + description: Indicates whether the IPv6 endpoint for the instance metadata service is enabled or disabled. + type: str + sample: disabled + http_put_response_hop_limit: + description: The maximum number of hops that the metadata token can travel. + type: int + sample: 1 + http_tokens: + description: Indicates whether IMDSv2 is required. + type: str + sample: optional + instance_metadata_tags: + description: Indicates whether access to instance tags from the instance metadata is enabled or disabled. + type: str + sample: disabled + state: + description: The state of the metadata option changes. + type: str + sample: applied monitoring: description: The monitoring for the instance. returned: always @@ -752,7 +832,8 @@ network_interfaces: description: One or more network interfaces for the instance. returned: always - type: complex + type: list + elements: dict contains: association: description: The association information for an Elastic IPv4 associated with the network interface. @@ -799,6 +880,11 @@ returned: always type: int sample: 0 + network_card_index: + description: The index of the network card. + returned: always + type: int + sample: 0 status: description: The attachment state. returned: always @@ -825,6 +911,11 @@ returned: always type: str sample: mygroup + interface_type: + description: The type of network interface. + returned: always + type: str + sample: interface ipv6_addresses: description: One or more IPv6 addresses associated with the network interface. returned: always @@ -851,6 +942,11 @@ returned: always type: str sample: 01234567890 + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always @@ -864,7 +960,6 @@ contains: association: description: The association information for an Elastic IP address (IPv4) associated with the network interface. - returned: always type: complex contains: ip_owner_id: @@ -887,6 +982,11 @@ returned: always type: bool sample: true + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The private IPv4 address of the network interface. returned: always @@ -928,7 +1028,6 @@ type: str group_id: description: The ID of the placement group the instance is in (for cluster compute instances). - returned: always type: str sample: "pg-01234566" group_name: @@ -938,16 +1037,13 @@ sample: "my-placement-group" host_id: description: The ID of the Dedicated Host on which the instance resides. - returned: always type: str host_resource_group_arn: description: The ARN of the host resource group in which the instance is in. - returned: always type: str sample: "arn:aws:resource-groups:us-east-1:123456789012:group/MyResourceGroup" partition_number: description: The number of the partition the instance is in. - returned: always type: int sample: 1 tenancy: @@ -961,11 +1057,32 @@ type: str version_added: 7.1.0 sample: + platform_details: + description: The platform details value for the instance. + returned: always + type: str + sample: Linux/UNIX private_dns_name: description: The private DNS name. returned: always type: str sample: ip-10-0-0-1.ap-southeast-2.compute.internal + private_dns_name_options: + description: The options for the instance hostname. + type: dict + contains: + enable_resource_name_dns_a_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS A records. + type: bool + sample: false + enable_resource_name_dns_aaaa_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records. + type: bool + sample: false + hostname_type: + description: The type of hostname to assign to an instance. + type: str + sample: ip-name private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always @@ -1023,7 +1140,7 @@ returned: always type: str sample: my-security-group - network.source_dest_check: + source_dest_check: description: Indicates whether source/destination checking is enabled. returned: always type: bool @@ -1222,6 +1339,9 @@ def build_network_spec(params): sub = get_default_subnet(default_vpc, availability_zone=module.params.get("availability_zone")) spec["SubnetId"] = sub["SubnetId"] + if network.get("ipv6_addresses"): + spec["Ipv6Addresses"] = [{"Ipv6Address": a} for a in network.get("ipv6_addresses", [])] + if network.get("private_ip_address"): spec["PrivateIpAddress"] = network["private_ip_address"] diff --git a/plugins/modules/ec2_instance_info.py b/plugins/modules/ec2_instance_info.py index 1caea9365c4..0af3d05ed35 100644 --- a/plugins/modules/ec2_instance_info.py +++ b/plugins/modules/ec2_instance_info.py @@ -10,7 +10,7 @@ version_added: 1.0.0 short_description: Gather information about ec2 instances in AWS description: - - Gather information about ec2 instances in AWS + - Gather information about EC2 instances in AWS. author: - Michael Schuett (@michaeljs1990) - Rob White (@wimnat) @@ -32,7 +32,7 @@ type: dict minimum_uptime: description: - - Minimum running uptime in minutes of instances. For example if I(uptime) is C(60) return all instances that have run more than 60 minutes. + - Minimum running uptime in minutes of instances. For example if O(uptime) is V(60) return all instances that have run more than 60 minutes. required: false aliases: ['uptime'] type: int @@ -161,6 +161,14 @@ returned: always type: str sample: vol-12345678 + capacity_reservation_specification: + description: Information about the Capacity Reservation targeting option. + type: complex + contains: + capacity_reservation_preference: + description: Describes the Capacity Reservation preferences. + type: str + sample: open cpu_options: description: The CPU options set for the instance. returned: always @@ -181,11 +189,38 @@ returned: always type: str sample: mytoken + current_instance_boot_mode: + description: The boot mode that is used to boot the instance at launch or start. + type: str + sample: legacy-bios ebs_optimized: description: Indicates whether the instance is optimized for EBS I/O. returned: always type: bool sample: false + ena_support: + description: Specifies whether enhanced networking with ENA is enabled. + returned: always + type: bool + sample: true + enclave_options: + description: Indicates whether the instance is enabled for Amazon Web Services Nitro Enclaves. + type: dict + contains: + enabled: + description: If this parameter is set to true, the instance is enabled for Amazon Web Services Nitro Enclaves. + returned: always + type: bool + sample: false + hibernation_options: + description: Indicates whether the instance is enabled for hibernation. + type: dict + contains: + configured: + description: If true, your instance is enabled for hibernation; otherwise, it is not enabled for hibernation. + returned: always + type: bool + sample: false hypervisor: description: The hypervisor type of the instance. returned: always @@ -193,7 +228,6 @@ sample: xen iam_instance_profile: description: The IAM instance profile associated with the instance, if applicable. - returned: always type: complex contains: arn: @@ -231,6 +265,44 @@ returned: always type: str sample: "2017-03-23T22:51:24+00:00" + maintenance_options: + description: Provides information on the recovery and maintenance options of your instance. + returned: always + type: dict + contains: + auto_recovery: + description: Provides information on the current automatic recovery behavior of your instance. + type: str + sample: default + metadata_options: + description: The metadata options for the instance. + returned: always + type: complex + contains: + http_endpoint: + description: Indicates whether the HTTP metadata endpoint on your instances is enabled or disabled. + type: str + sample: enabled + http_protocol_ipv6: + description: Indicates whether the IPv6 endpoint for the instance metadata service is enabled or disabled. + type: str + sample: disabled + http_put_response_hop_limit: + description: The maximum number of hops that the metadata token can travel. + type: int + sample: 1 + http_tokens: + description: Indicates whether IMDSv2 is required. + type: str + sample: optional + instance_metadata_tags: + description: Indicates whether access to instance tags from the instance metadata is enabled or disabled. + type: str + sample: disabled + state: + description: The state of the metadata option changes. + type: str + sample: applied monitoring: description: The monitoring for the instance. returned: always @@ -291,6 +363,11 @@ returned: always type: int sample: 0 + network_card_index: + description: The index of the network card. + returned: always + type: int + sample: 0 status: description: The attachment state. returned: always @@ -317,6 +394,11 @@ returned: always type: str sample: mygroup + interface_type: + description: The type of network interface. + returned: always + type: str + sample: interface ipv6_addresses: description: One or more IPv6 addresses associated with the network interface. returned: always @@ -343,6 +425,11 @@ returned: always type: str sample: 01234567890 + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always @@ -356,7 +443,6 @@ contains: association: description: The association information for an Elastic IP address (IPv4) associated with the network interface. - returned: always type: complex contains: ip_owner_id: @@ -379,6 +465,11 @@ returned: always type: bool sample: true + private_dns_name: + description: The private DNS hostname name assigned to the instance. + type: str + returned: always + sample: ip-10-1-0-156.ec2.internal private_ip_address: description: The private IPv4 address of the network interface. returned: always @@ -424,11 +515,32 @@ returned: always type: str sample: default + platform_details: + description: The platform details value for the instance. + returned: always + type: str + sample: Linux/UNIX private_dns_name: description: The private DNS name. returned: always type: str sample: ip-10-0-0-1.ap-southeast-2.compute.internal + private_dns_name_options: + description: The options for the instance hostname. + type: dict + contains: + enable_resource_name_dns_a_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS A records. + type: bool + sample: false + enable_resource_name_dns_aaaa_record: + description: Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records. + type: bool + sample: false + hostname_type: + description: The type of hostname to assign to an instance. + type: str + sample: ip-name private_ip_address: description: The IPv4 address of the network interface within the subnet. returned: always @@ -533,7 +645,7 @@ sample: vpc-0011223344 attributes: description: The details of the instance attribute specified on input. - returned: when include_attribute is specified + returned: when O(include_attributes) is specified type: dict sample: { diff --git a/plugins/modules/ec2_key.py b/plugins/modules/ec2_key.py index ea4d7f7e4f2..f2e98e069b4 100644 --- a/plugins/modules/ec2_key.py +++ b/plugins/modules/ec2_key.py @@ -41,7 +41,7 @@ - Note that ED25519 keys are not supported for Windows instances, EC2 Instance Connect, and EC2 Serial Console. - By default Amazon will create an RSA key. - - Mutually exclusive with parameter I(key_material). + - Mutually exclusive with parameter O(key_material). type: str choices: - rsa @@ -50,15 +50,15 @@ file_name: description: - Name of the file where the generated private key will be saved. - - When provided, the I(key.private_key) attribute will be removed from the return value. + - When provided, the RV(key.private_key) attribute will be removed from the return value. - The file is written out on the 'host' side rather than the 'controller' side. - - Ignored when I(state=absent) or I(key_material) is provided. + - Ignored when O(state=absent) or O(key_material) is provided. type: path version_added: 6.4.0 notes: - - Support for I(tags) and I(purge_tags) was added in release 2.1.0. + - Support for O(tags) and O(purge_tags) was added in release 2.1.0. - For security reasons, this module should be used with B(no_log=true) and (register) functionalities - when creating new key pair without providing I(key_material). + when creating new key pair without providing O(key_material). extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -112,49 +112,49 @@ RETURN = r""" changed: - description: whether a keypair was created/deleted + description: Whether a keypair was created/deleted. returned: always type: bool sample: true msg: - description: short message describing the action taken + description: Short message describing the action taken. returned: always type: str sample: key pair created key: - description: details of the keypair (this is set to null when state is absent) + description: Details of the keypair (this is set to null when state is absent). returned: always type: complex contains: fingerprint: - description: fingerprint of the key - returned: when state is present + description: Fingerprint of the key. + returned: when O(state=present) type: str sample: 'b0:22:49:61:d9:44:9d:0c:7e:ac:8a:32:93:21:6c:e8:fb:59:62:43' name: - description: name of the keypair - returned: when state is present + description: Name of the keypair. + returned: when O(state=present) type: str sample: my_keypair id: - description: id of the keypair - returned: when state is present + description: Id of the keypair. + returned: when O(state=present) type: str sample: key-123456789abc tags: - description: a dictionary representing the tags attached to the key pair - returned: when state is present + description: A dictionary representing the tags attached to the key pair. + returned: when O(state=present) type: dict sample: '{"my_key": "my value"}' private_key: - description: private key of a newly created keypair - returned: when a new keypair is created by AWS (I(key_material) is not provided) and I(file_name) is not provided. + description: Private key of a newly created keypair. + returned: when a new keypair is created by AWS (O(key_material) is not provided) and O(file_name) is not provided. type: str sample: '-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKC... -----END RSA PRIVATE KEY-----' type: - description: type of a newly created keypair + description: Type of a newly created keypair. returned: when a new keypair is created by AWS type: str sample: rsa diff --git a/plugins/modules/ec2_security_group.py b/plugins/modules/ec2_security_group.py index ab910c6061e..c339370fa83 100644 --- a/plugins/modules/ec2_security_group.py +++ b/plugins/modules/ec2_security_group.py @@ -18,20 +18,20 @@ name: description: - Name of the security group. - - One of and only one of I(name) or I(group_id) is required. - - Required if I(state=present). + - One of and only one of O(name) or O(group_id) is required. + - Required if O(state=present). required: false type: str group_id: description: - Id of group to delete (works only with absent). - - One of and only one of I(name) or I(group_id) is required. + - One of and only one of O(name) or O(group_id) is required. required: false type: str description: description: - Description of the security group. - - Required when I(state) is C(present). + - Required when O(state) is V(present). required: false type: str vpc_id: @@ -42,7 +42,7 @@ rules: description: - List of firewall inbound rules to enforce in this group (see example). If none are supplied, - no inbound rules will be enabled. Rules list may include its own name in I(group_name). + no inbound rules will be enabled. Rules list may include its own name in O(rules.group_name). This allows idempotent loopback additions (e.g. allow group to access itself). required: false type: list @@ -53,18 +53,18 @@ elements: raw description: - The IPv4 CIDR range traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) + - You can specify only one of O(rules.cidr_ip), O(rules.cidr_ipv6), O(rules.ip_prefix), O(rules.group_id) and I(group_name). - - Support for passing nested lists of strings to I(cidr_ip) has been deprecated and will + - Support for passing nested lists of strings to O(rules.cidr_ip) has been deprecated and will be removed in a release after 2024-12-01. cidr_ipv6: type: list elements: raw description: - The IPv6 CIDR range traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). - - Support for passing nested lists of strings to I(cidr_ipv6) has been deprecated and will + - You can specify only one of O(rules.cidr_ip), O(rules.cidr_ipv6), O(rules.ip_prefix), O(rules.group_id) + and I(rules.group_name). + - Support for passing nested lists of strings to O(rules.cidr_ipv6) has been deprecated and will be removed in a release after 2024-12-01. ip_prefix: type: list @@ -72,74 +72,74 @@ description: - The IP Prefix U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html) that traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(rules.cidr_ip), O(rules.cidr_ipv6), O(rules.ip_prefix), O(rules.group_id) + and O(rules.group_name). group_id: type: list elements: str description: - The ID of the Security Group that traffic is coming from. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(rules.cidr_ip), O(rules.cidr_ipv6), O(rules.ip_prefix), O(rules.group_id) + and O(rules.group_name). group_name: type: list elements: str description: - Name of the Security Group that traffic is coming from. - If the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. - - I(group_name) can accept values of type str and list. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + created with O(rules.group_desc) as the description. + - O(rules.group_name) can accept values of type str and list. + - You can specify only one of O(rules.cidr_ip), O(rules.cidr_ipv6), O(rules.ip_prefix), O(rules.group_id) + and O(rules.group_name). group_desc: type: str description: - - If the I(group_name) is set and the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. + - If the O(rules.group_name) is set and the Security Group doesn't exist a new Security Group will be + created with O(rules.group_desc) as the description. proto: type: str description: - - The IP protocol name (C(tcp), C(udp), C(icmp), C(icmpv6)) or + - The IP protocol name (V(tcp), V(udp), V(icmp), V(icmpv6)) or number (U(https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers)). - default: 'tcp' + default: tcp from_port: type: int description: - The start of the range of ports that traffic is going to. - - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - A value can be between V(0) to V(65535). + - When O(rules.proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(rules.icmp_code), O(rules.icmp_type) and O(rules.ports). to_port: type: int description: - The end of the range of ports that traffic is going to. - - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - A value can be between V(0) to V(65535). + - When O(rules.proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(rules.icmp_code), O(rules.icmp_type) and O(rules.ports). ports: type: list elements: str description: - A list of ports that traffic is going to. - - Elements of the list can be a single port (for example C(8080)), or a range of ports - specified as C(-), (for example C(1011-1023)). - - Mutually exclusive with I(icmp_code), I(icmp_type), I(from_port) and I(to_port). + - Elements of the list can be a single port (for example V(8080)), or a range of ports + specified as V(-), (for example V(1011-1023)). + - Mutually exclusive with O(rules.icmp_code), O(rules.icmp_type), O(rules.from_port) and O(rules.to_port). icmp_type: version_added: 3.3.0 type: int description: - The ICMP type of the packet. - - A value of C(-1) indicates all ICMP types. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of V(-1) indicates all ICMP types. + - Requires O(rules.proto=icmp) or O(rules.proto=icmpv6). + - Mutually exclusive withot O(rules.ports), O(rules.from_port) and O(rules.to_port). icmp_code: version_added: 3.3.0 type: int description: - The ICMP code of the packet. - - A value of C(-1) indicates all ICMP codes. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of V(-1) indicates all ICMP codes. + - Requires O(rules.proto=icmp) or O(rules.proto=icmpv6). + - Mutually exclusive with O(rules.ports), O(rules.from_port) and O(rules.to_port). rule_desc: type: str description: A description for the rule. @@ -158,18 +158,18 @@ elements: raw description: - The IPv4 CIDR range traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). - - Support for passing nested lists of strings to I(cidr_ip) has been deprecated and will + - You can specify only one of O(rules_egress.cidr_ip), O(rules_egress.cidr_ipv6), O(rules_egress.ip_prefix), O(rules_egress.group_id) + and I(rules_egress.group_name). + - Support for passing nested lists of strings to O(rules_egress.cidr_ip) has been deprecated and will be removed in a release after 2024-12-01. cidr_ipv6: type: list elements: raw description: - The IPv6 CIDR range traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). - - Support for passing nested lists of strings to I(cidr_ipv6) has been deprecated and will + - You can specify only one of O(rules_egress.cidr_ip), O(rules_egress.cidr_ipv6), O(rules_egress.ip_prefix), O(rules_egress.group_id) + and O(rules_egress.group_name). + - Support for passing nested lists of strings to O(rules_egress.cidr_ipv6) has been deprecated and will be removed in a release after 2024-12-01. ip_prefix: type: list @@ -177,73 +177,73 @@ description: - The IP Prefix U(https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-prefix-lists.html) that traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(rules_egress.cidr_ip), O(rules_egress.cidr_ipv6), O(rules_egress.ip_prefix), O(rules_egress.group_id) + and O(rules_egress.group_name). group_id: type: list elements: str description: - The ID of the Security Group that traffic is going to. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + - You can specify only one of O(rules_egress.cidr_ip), O(rules_egress.cidr_ipv6), O(rules_egress.ip_prefix), O(rules_egress.group_id) + and O(rules_egress.group_name). group_name: type: list elements: str description: - Name of the Security Group that traffic is going to. - If the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. - - You can specify only one of I(cidr_ip), I(cidr_ipv6), I(ip_prefix), I(group_id) - and I(group_name). + created with O(rules_egress.group_desc) as the description. + - You can specify only one of O(rules_egress.cidr_ip), O(rules_egress.cidr_ipv6), O(rules_egress.ip_prefix), O(rules_egress.group_id) + and O(rules_egress.group_name). group_desc: type: str description: - - If the I(group_name) is set and the Security Group doesn't exist a new Security Group will be - created with I(group_desc) as the description. + - If the O(rules_egress.group_name) is set and the Security Group doesn't exist a new Security Group will be + created with O(rules_egress.group_desc) as the description. proto: type: str description: - - The IP protocol name (C(tcp), C(udp), C(icmp), C(icmpv6)) or + - The IP protocol name (V(tcp), V(udp), V(icmp), V(icmpv6)) or number (U(https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers)). default: 'tcp' from_port: type: int description: - The start of the range of ports that traffic is going to. - - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - A value can be between V(0) to V(65535). + - When O(rules_egress.proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(rules_egress.icmp_code), O(rules_egress.icmp_type) and O(rules_egress.ports). to_port: type: int description: - The end of the range of ports that traffic is going to. - A value can be between C(0) to C(65535). - - When I(proto=icmp) a value of C(-1) indicates all ports. - - Mutually exclusive with I(icmp_code), I(icmp_type) and I(ports). + - When O(rules_egress.proto=icmp) a value of V(-1) indicates all ports. + - Mutually exclusive with O(rules_egress.icmp_code), O(rules_egress.icmp_type) and O(rules_egress.ports). ports: type: list elements: str description: - A list of ports that traffic is going to. - - Elements of the list can be a single port (for example C(8080)), or a range of ports - specified as C(-), (for example C(1011-1023)). - - Mutually exclusive with I(icmp_code), I(icmp_type), I(from_port) and I(to_port). + - Elements of the list can be a single port (for example V(8080)), or a range of ports + specified as V(-), (for example V(1011-1023)). + - Mutually exclusive with O(rules_egress.icmp_code), O(rules_egress.icmp_type), O(rules_egress.from_port) and O(rules_egress.to_port). icmp_type: version_added: 3.3.0 type: int description: - The ICMP type of the packet. - - A value of C(-1) indicates all ICMP types. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of CV(-1) indicates all ICMP types. + - Requires O(rules_egress.proto=icmp) or O(rules_egress.proto=icmpv6). + - Mutually exclusive with O(rules_egress.ports), O(rules_egress.from_port) and O(rules_egress.to_port). icmp_code: version_added: 3.3.0 type: int description: - The ICMP code of the packet. - - A value of C(-1) indicates all ICMP codes. - - Requires I(proto=icmp) or I(proto=icmpv6). - - Mutually exclusive with I(ports), I(from_port) and I(to_port). + - A value of V(-1) indicates all ICMP codes. + - Requires O(rules_egress.proto=icmp) or O(rules_egress.proto=icmpv6). + - Mutually exclusive with O(rules_egress.ports), O(rules_egress.from_port) and O(rules_egress.to_port). rule_desc: type: str description: A description for the rule. @@ -280,7 +280,7 @@ - If a rule declares a group_name and that group doesn't exist, it will be automatically created. In that case, group_desc should be provided as well. The module will refuse to create a depended-on group without a description. - - Prior to release 5.0.0 this module was called C(amazon.aws.ec2_group_info). The usage did not + - Prior to release 5.0.0 this module was called M(amazon.aws.ec2_group_info). The usage did not change. """ @@ -413,62 +413,154 @@ """ RETURN = r""" -group_name: - description: Security group name +description: + description: Description of security group. sample: My Security Group type: str returned: on create/update group_id: - description: Security group id + description: Security group id. sample: sg-abcd1234 type: str returned: on create/update -description: - description: Description of security group +group_name: + description: Security group name. sample: My Security Group type: str returned: on create/update +ip_permissions: + description: The inbound rules associated with the security group. + returned: always + type: list + elements: dict + contains: + from_port: + description: If the protocol is TCP or UDP, this is the start of the port range. + type: int + sample: 80 + ip_protocol: + description: The IP protocol name or number. + returned: always + type: str + ip_ranges: + description: The IPv4 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ip: + description: The IPv4 CIDR range. + returned: always + type: str + ipv6_ranges: + description: The IPv6 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ipv6: + description: The IPv6 CIDR range. + returned: always + type: str + prefix_list_ids: + description: The prefix list IDs. + returned: always + type: list + elements: dict + contains: + prefix_list_id: + description: The ID of the prefix. + returned: always + type: str + to_group: + description: If the protocol is TCP or UDP, this is the end of the port range. + type: int + sample: 80 + user_id_group_pairs: + description: The security group and AWS account ID pairs. + returned: always + type: list + elements: dict + contains: + group_id: + description: The security group ID of the pair. + returned: always + type: str + user_id: + description: The user ID of the pair. + returned: always + type: str +ip_permissions_egress: + description: The outbound rules associated with the security group. + returned: always + type: list + elements: dict + contains: + ip_protocol: + description: The IP protocol name or number. + returned: always + type: str + ip_ranges: + description: The IPv4 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ip: + description: The IPv4 CIDR range. + returned: always + type: str + ipv6_ranges: + description: The IPv6 ranges. + returned: always + type: list + elements: dict + contains: + cidr_ipv6: + description: The IPv6 CIDR range. + returned: always + type: str + prefix_list_ids: + description: The prefix list IDs. + returned: always + type: list + elements: dict + contains: + prefix_list_id: + description: The ID of the prefix. + returned: always + type: str + user_id_group_pairs: + description: The security group and AWS account ID pairs. + returned: always + type: list + elements: dict + contains: + group_id: + description: The security group ID of the pair. + returned: always + type: str + user_id: + description: The user ID of the pair. + returned: always + type: str +owner_id: + description: AWS Account ID of the security group. + sample: 123456789012 + type: int + returned: on create/update tags: - description: Tags associated with the security group + description: Tags associated with the security group. sample: Name: My Security Group Purpose: protecting stuff type: dict returned: on create/update vpc_id: - description: ID of VPC to which the security group belongs + description: ID of VPC to which the security group belongs. sample: vpc-abcd1234 type: str returned: on create/update -ip_permissions: - description: Inbound rules associated with the security group. - sample: - - from_port: 8182 - ip_protocol: tcp - ip_ranges: - - cidr_ip: "198.51.100.1/32" - ipv6_ranges: [] - prefix_list_ids: [] - to_port: 8182 - user_id_group_pairs: [] - type: list - returned: on create/update -ip_permissions_egress: - description: Outbound rules associated with the security group. - sample: - - ip_protocol: -1 - ip_ranges: - - cidr_ip: "0.0.0.0/0" - ipv6_ranges: [] - prefix_list_ids: [] - user_id_group_pairs: [] - type: list - returned: on create/update -owner_id: - description: AWS Account ID of the security group - sample: 123456789012 - type: int - returned: on create/update """ import itertools diff --git a/plugins/modules/ec2_security_group_info.py b/plugins/modules/ec2_security_group_info.py index 8b7a04ba14c..14a130ccc3a 100644 --- a/plugins/modules/ec2_security_group_info.py +++ b/plugins/modules/ec2_security_group_info.py @@ -26,7 +26,7 @@ notes: - By default, the module will return all security groups in a region. To limit results use the appropriate filters. - - Prior to release 5.0.0 this module was called C(amazon.aws.ec2_group_info). The usage did not + - Prior to release 5.0.0 this module was called M(amazon.aws.ec2_group_info). The usage did not change. extends_documentation_fragment: @@ -107,6 +107,10 @@ type: list elements: dict contains: + from_port: + description: If the protocol is TCP or UDP, this is the start of the port range. + type: int + sample: 80 ip_protocol: description: The IP protocol name or number. returned: always @@ -141,6 +145,10 @@ description: The ID of the prefix. returned: always type: str + to_group: + description: If the protocol is TCP or UDP, this is the end of the port range. + type: int + sample: 80 user_id_group_pairs: description: The security group and AWS account ID pairs. returned: always diff --git a/plugins/modules/ec2_snapshot.py b/plugins/modules/ec2_snapshot.py index 1ca33b039b1..60b3ce8d5f0 100644 --- a/plugins/modules/ec2_snapshot.py +++ b/plugins/modules/ec2_snapshot.py @@ -35,7 +35,7 @@ snapshot_tags: description: - A dictionary of tags to add to the snapshot. - - If the volume has a C(Name) tag this will be automatically added to the + - If the volume has a V(Name) tag this will be automatically added to the snapshot. type: dict required: false @@ -66,28 +66,28 @@ type: str last_snapshot_min_age: description: - - If the volume's most recent snapshot has started less than I(last_snapshot_min_age) minutes ago, a new snapshot will not be created. + - If the volume's most recent snapshot has started less than O(last_snapshot_min_age) minutes ago, a new snapshot will not be created. required: false default: 0 type: int modify_create_vol_permission: description: - - If set to C(true), ec2 snapshot's createVolumePermissions can be modified. + - If set to V(true), ec2 snapshot's createVolumePermissions can be modified. required: false type: bool version_added: 6.1.0 purge_create_vol_permission: description: - Whether unspecified group names or user IDs should be removed from the snapshot createVolumePermission. - - Must set I(modify_create_vol_permission) to C(True) for when I(purge_create_vol_permission) is set to C(True). + - Must set O(modify_create_vol_permission) to V(True) for when O(purge_create_vol_permission) is set to V(True). required: False type: bool default: False version_added: 6.1.0 group_names: description: - - The group to be added or removed. The possible value is C(all). - - Mutually exclusive with I(user_ids). + - The group to be added or removed. The possible value is V(all). + - Mutually exclusive with O(user_ids). required: false type: list elements: str @@ -96,9 +96,9 @@ user_ids: description: - The account user IDs to be added or removed. - - If createVolumePermission on snapshot is currently set to Public i.e. I(group_names=all), - providing I(user_ids) will not make createVolumePermission Private unless I(create_volume_permission) is set to C(true). - - Mutually exclusive with I(group_names). + - If createVolumePermission on snapshot is currently set to Public i.e. O(group_names=all), + providing O(user_ids) will not make createVolumePermission Private unless O(modify_create_vol_permission) is set to V(true). + - Mutually exclusive with O(group_names). required: false type: list elements: str @@ -185,6 +185,62 @@ type: str returned: always sample: snap-01234567 +snapshots: + description: List of snapshots. + returned: always + type: list + elements: dict + contains: + description: + description: Description specified by the CreateSnapshotRequest that has been applied to all snapshots. + type: str + returned: always + sample: "" + encrypted: + description: Indicates whether the snapshot is encrypted. + type: bool + returned: always + sample: false + owner_id: + description: Account id used when creating this snapshot. + type: str + returned: always + sample: 123456 + progress: + description: Progress this snapshot has made towards completing. + type: str + returned: always + sample: "" + snapshot_id: + description: Snapshot id that can be used to describe this snapshot. + type: str + returned: always + sample: snap-1234 + start_time: + description: Time this snapshot was started. This is the same for all snapshots initiated by the same request. + type: str + returned: always + sample: "2024-05-07T14:29:24.523000+00:00" + state: + description: Current state of the snapshot. + type: str + returned: always + sample: pending + tags: + description: Tags associated with this snapshot. + type: dict + returned: always + sample: "{ 'Name': 'instance-name' }" + volume_id: + description: The ID of the volume that was used to create the snapshot. + type: str + returned: always + sample: vol-01234567 + volume_size: + description: The size of the volume, in GiB. + type: int + returned: always + sample: 8 tags: description: Any tags assigned to the snapshot. type: dict diff --git a/plugins/modules/ec2_snapshot_info.py b/plugins/modules/ec2_snapshot_info.py index f2db12cbbc7..27d6dbad42a 100644 --- a/plugins/modules/ec2_snapshot_info.py +++ b/plugins/modules/ec2_snapshot_info.py @@ -49,23 +49,23 @@ max_results: description: - The maximum number of snapshot results returned in paginated output. - - When used only a single page along with a C(next_token_id) response element will be returned. - - The remaining results of the initial request can be seen by sending another request with the returned C(next_token_id) value. - - This value can be between 5 and 1000; if I(next_token_id) is given a value larger than 1000, only 1000 results are returned. + - When used only a single page along with a O(next_token_id) response element will be returned. + - The remaining results of the initial request can be seen by sending another request with the returned O(next_token_id) value. + - This value can be between 5 and 1000; if O(next_token_id) is given a value larger than 1000, only 1000 results are returned. - If this parameter is not used, then DescribeSnapshots returns all results. - - This parameter is mutually exclusive with I(snapshot_ids). + - This parameter is mutually exclusive with O(snapshot_ids). required: False type: int next_token_id: description: - - Contains the value returned from a previous paginated request where I(max_results) was used and the results exceeded the value of that parameter. - - Pagination continues from the end of the previous results that returned the I(next_token_id) value. - - This parameter is mutually exclusive with I(snapshot_ids) + - Contains the value returned from a previous paginated request where O(max_results) was used and the results exceeded the value of that parameter. + - Pagination continues from the end of the previous results that returned the O(next_token_id) value. + - This parameter is mutually exclusive with O(snapshot_ids) required: false type: str notes: - By default, the module will return all snapshots, including public ones. To limit results to snapshots owned by - the account use the filter 'owner-id'. + the account use the filter V(owner-id). extends_documentation_fragment: - amazon.aws.region.modules @@ -117,96 +117,94 @@ returned: success elements: dict contains: - snapshot_id: - description: The ID of the snapshot. Each snapshot receives a unique identifier when it is created. + create_volume_permissions: + description: + - The users and groups that have the permissions for creating volumes from the snapshot. + - The module will return empty list if the create volume permissions on snapshot are 'private'. + type: list + elements: dict + sample: [{"group": "all"}] + data_encryption_key_id: + description: + - The data encryption key identifier for the snapshot. This value is a unique identifier that + corresponds to the data encryption key that was used to encrypt the original volume or snapshot copy. type: str returned: always - sample: snap-01234567 - volume_id: - description: The ID of the volume that was used to create the snapshot. + sample: "arn:aws:kms:ap-southeast-2:123456789012:key/74c9742a-a1b2-45cb-b3fe-abcdef123456" + description: + description: The description for the snapshot. type: str returned: always - sample: vol-01234567 - state: - description: The snapshot state (completed, pending or error). - type: str + sample: "My important backup" + encrypted: + description: Indicates whether the snapshot is encrypted. + type: bool returned: always - sample: completed - state_message: + sample: "True" + kms_key_id: description: - - Encrypted Amazon EBS snapshots are copied asynchronously. If a snapshot copy operation fails (for example, if the proper - AWS Key Management Service (AWS KMS) permissions are not obtained) this field displays error state details to help you diagnose why the - error occurred. + - The full ARN of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to + protect the volume encryption key for the parent volume. type: str - returned: always - sample: - start_time: - description: The time stamp when the snapshot was initiated. + sample: "74c9742a-a1b2-45cb-b3fe-abcdef123456" + owner_id: + description: The AWS account ID of the EBS snapshot owner. type: str returned: always - sample: "2015-02-12T02:14:02+00:00" + sample: "123456789012" progress: description: The progress of the snapshot, as a percentage. type: str returned: always sample: "100%" - owner_id: - description: The AWS account ID of the EBS snapshot owner. + snapshot_id: + description: The ID of the snapshot. Each snapshot receives a unique identifier when it is created. type: str returned: always - sample: "123456789012" - description: - description: The description for the snapshot. + sample: snap-01234567 + start_time: + description: The time stamp when the snapshot was initiated. type: str returned: always - sample: "My important backup" - volume_size: - description: The size of the volume, in GiB. - type: int + sample: "2015-02-12T02:14:02+00:00" + state: + description: The snapshot state (completed, pending or error). + type: str returned: always - sample: 8 - owner_alias: - description: The AWS account alias (for example, amazon, self) or AWS account ID that owns the snapshot. + sample: completed + state_message: + description: + - Encrypted Amazon EBS snapshots are copied asynchronously. If a snapshot copy operation fails (for example, if the proper + AWS Key Management Service (AWS KMS) permissions are not obtained) this field displays error state details to help you diagnose why the + error occurred. + type: str + sample: + storage_tier: + description: The storage tier in which the snapshot is stored. type: str returned: always - sample: "123456789012" + sample: standard tags: description: Any tags assigned to the snapshot. type: dict returned: always sample: "{ 'my_tag_key': 'my_tag_value' }" - encrypted: - description: Indicates whether the snapshot is encrypted. - type: bool - returned: always - sample: "True" - kms_key_id: - description: - - The full ARN of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to - protect the volume encryption key for the parent volume. + volume_id: + description: The ID of the volume that was used to create the snapshot. type: str returned: always - sample: "74c9742a-a1b2-45cb-b3fe-abcdef123456" - data_encryption_key_id: - description: - - The data encryption key identifier for the snapshot. This value is a unique identifier that - corresponds to the data encryption key that was used to encrypt the original volume or snapshot copy. - type: str + sample: vol-01234567 + volume_size: + description: The size of the volume, in GiB. + type: int returned: always - sample: "arn:aws:kms:ap-southeast-2:123456789012:key/74c9742a-a1b2-45cb-b3fe-abcdef123456" - create_volume_permissions: - description: - - The users and groups that have the permissions for creating volumes from the snapshot. - - The module will return empty list if the create volume permissions on snapshot are 'private'. - type: list - elements: dict - sample: [{"group": "all"}] + sample: 8 next_token_id: description: - Contains the value returned from a previous paginated request where C(max_results) was used and the results exceeded the value of that parameter. - This value is null when there are no more results to return. type: str - returned: when option C(max_results) is set in input + returned: when option O(max_results) is set in input """ try: diff --git a/plugins/modules/ec2_spot_instance.py b/plugins/modules/ec2_spot_instance.py index 1bd56472409..246e1fe157a 100644 --- a/plugins/modules/ec2_spot_instance.py +++ b/plugins/modules/ec2_spot_instance.py @@ -50,7 +50,7 @@ security_groups: description: - Security group name (or list of group names) to use with the instance. - - Only supported with EC2 Classic. To launch in a VPC, use C(group_id) + - Only supported with EC2 Classic. To launch in a VPC, use O(launch_specification.security_group_ids). type: list elements: str key_name: @@ -75,7 +75,7 @@ suboptions: device_name: description: - - The device name (for example, /dev/sdh or xvdh ). + - The device name (for example, /dev/sdh or xvdh). type: str virtual_name: description: @@ -84,7 +84,7 @@ ebs: description: - Parameters used to automatically set up EBS volumes when the instance is launched, - see U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.request_spot_instances) + see U(https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html#EC2.Client.request_spot_instances). type: dict no_device: description: @@ -103,12 +103,12 @@ arn: description: - The Amazon Resource Name (ARN) of the instance profile. - - Only one of I(arn) or I(name) may be specified. + - Only one of O(launch_specification.iam_instance_profile.arn) or I(launch_specification.iam_instance_profile.name) may be specified. type: str name: description: - The name of the instance profile. - - Only one of I(arn) or I(name) may be specified. + - Only one of O(launch_specification.iam_instance_profile.arn) or I(launch_specification.iam_instance_profile.name) may be specified. type: str image_id: description: @@ -254,8 +254,8 @@ state: description: - Whether the spot request should be created or removed. - - When I(state=present), I(launch_specification) is required. - - When I(state=absent), I(spot_instance_request_ids) is required. + - When O(state=present), O(launch_specification) is required. + - When O(state=absent), O(spot_instance_request_ids) is required. default: 'present' choices: [ 'absent', 'present' ] type: str @@ -267,7 +267,7 @@ spot_type: description: - The type of spot request. - - After being interrupted a C(persistent) spot instance will be started once there is capacity to fill the request again. + - After being interrupted a V(persistent) spot instance will be started once there is capacity to fill the request again. default: 'one-time' choices: [ "one-time", "persistent" ] type: str @@ -283,7 +283,7 @@ terminate_instances: description: - Boolean value to set whether or not to terminate instances associated to spot request. - - Can be used only when I(state=absent). + - Can be used only when O(state=absent). default: False type: bool version_added: 5.4.0 @@ -341,7 +341,7 @@ RETURN = r""" spot_request: - description: The spot instance request details after creation + description: The spot instance request details after creation. returned: when success type: dict sample: { @@ -394,14 +394,14 @@ "message": "Your Spot request has been submitted for review, and is pending evaluation.", "update_time": "2021-08-23T22:59:12+00:00" }, + "tags": {}, "type": "one-time" - } cancelled_spot_request: - description: The spot instance request details that has been cancelled - returned: always + description: Details of the cancelled spot instance request. type: str + returned: when cancellation is successful sample: 'Spot requests with IDs: sir-1234abcd have been cancelled' """ diff --git a/plugins/modules/ec2_spot_instance_info.py b/plugins/modules/ec2_spot_instance_info.py index 7dc4abce831..e1fbea8693d 100644 --- a/plugins/modules/ec2_spot_instance_info.py +++ b/plugins/modules/ec2_spot_instance_info.py @@ -62,7 +62,7 @@ RETURN = r""" spot_request: - description: The gathered information about specified spot instance requests. + description: The gathered information about specified spot instance requests. returned: when success type: list elements: dict diff --git a/plugins/modules/ec2_tag.py b/plugins/modules/ec2_tag.py index 9773325c768..efe3bae9462 100644 --- a/plugins/modules/ec2_tag.py +++ b/plugins/modules/ec2_tag.py @@ -22,7 +22,7 @@ state: description: - Whether the tags should be present or absent on the resource. - - The use of I(state=list) to interrogate the tags of an instance was + - The use of O(state=list) to interrogate the tags of an instance was deprecated in release 1.0.0 and is no longer available in release 4.0.0. The 'list' functionality has been moved to a dedicated module M(amazon.aws.ec2_tag_info). @@ -32,13 +32,13 @@ tags: description: - A dictionary of tags to add or remove from the resource. - - If the value provided for a key is not set and I(state=absent), the tag will be removed regardless of its current value. + - If the value provided for a key is not set and O(state=absent), the tag will be removed regardless of its current value. type: dict required: true purge_tags: description: - Whether unspecified tags should be removed from the resource. - - Note that when combined with I(state=absent), specified tags with non-matching values are not purged. + - Note that when combined with O(state=absent), specified tags with non-matching values are not purged. type: bool default: false @@ -99,15 +99,15 @@ RETURN = r""" tags: - description: A dict containing the tags on the resource + description: A dict containing the tags on the resource. returned: always type: dict added_tags: - description: A dict of tags that were added to the resource + description: A dict of tags that were added to the resource. returned: If tags were added type: dict removed_tags: - description: A dict of tags that were removed from the resource + description: A dict of tags that were removed from the resource. returned: If tags were removed type: dict """ diff --git a/plugins/modules/ec2_tag_info.py b/plugins/modules/ec2_tag_info.py index 1efcd55822d..029d4e131b6 100644 --- a/plugins/modules/ec2_tag_info.py +++ b/plugins/modules/ec2_tag_info.py @@ -44,7 +44,7 @@ RETURN = r""" tags: - description: A dict containing the tags on the resource + description: A dict containing the tags on the resource. returned: always type: dict """ diff --git a/plugins/modules/ec2_vol.py b/plugins/modules/ec2_vol.py index de63d3703e3..e68c978c41c 100644 --- a/plugins/modules/ec2_vol.py +++ b/plugins/modules/ec2_vol.py @@ -11,12 +11,12 @@ short_description: Create and attach a volume, return volume ID and device map description: - Creates an EBS volume and optionally attaches it to an instance. - - If both I(instance) and I(name) are given and the instance has a device at the device name, then no volume is created and no attachment is made. + - If both O(instance) and O(name) are given and the instance has a device at the device name, then no volume is created and no attachment is made. options: instance: description: - Instance ID if you wish to attach the volume. - - Set to C(None) to detach the volume. + - Set to V(None) to detach the volume. type: str name: description: @@ -32,9 +32,9 @@ type: int volume_type: description: - - Type of EBS volume; C(standard) (magnetic), C(gp2) (SSD), C(gp3) (SSD), C(io1) (Provisioned IOPS), C(io2) (Provisioned IOPS), - C(st1) (Throughput Optimized HDD), C(sc1) (Cold HDD). - - C(standard) is the old EBS default and continues to remain the Ansible default for backwards compatibility. + - Type of EBS volume; V(standard) (magnetic), V(gp2) (SSD), V(gp3) (SSD), V(io1) (Provisioned IOPS), V(io2) (Provisioned IOPS), + V(st1) (Throughput Optimized HDD), V(sc1) (Cold HDD). + - V(standard) is the old EBS default and continues to remain the Ansible default for backwards compatibility. default: standard choices: ['standard', 'gp2', 'io1', 'st1', 'sc1', 'gp3', 'io2'] type: str @@ -72,15 +72,15 @@ state: description: - Whether to ensure the volume is present or absent. - - I(state=list) was deprecated in release 1.1.0 and is no longer available + - O(state=list) was deprecated in release 1.1.0 and is no longer available with release 4.0.0. - - The C(list) functionality has been moved to a dedicated module M(amazon.aws.ec2_vol_info). + - The V(list) functionality has been moved to a dedicated module M(amazon.aws.ec2_vol_info). default: present choices: ['absent', 'present'] type: str modify_volume: description: - - The volume won't be modified unless this key is C(true). + - The volume won't be modified unless this key is V(true). type: bool default: false version_added: 1.4.0 @@ -93,7 +93,7 @@ version_added: 1.4.0 multi_attach: description: - - If set to C(true), Multi-Attach will be enabled when creating the volume. + - If set to V(true), Multi-Attach will be enabled when creating the volume. - When you create a new volume, Multi-Attach is disabled by default. - This parameter is supported with io1 and io2 volumes only. type: bool @@ -107,7 +107,7 @@ author: - "Lester Wade (@lwade)" notes: - - Support for I(purge_tags) was added in release 1.5.0. + - Support for O(purge_tags) was added in release 1.5.0. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -205,45 +205,96 @@ RETURN = r""" device: - description: device name of attached volume + description: Device name of attached volume. returned: when success type: str sample: "/dev/sdf" volume_id: - description: the id of volume + description: The id of volume. returned: when success type: str sample: "vol-35b333d9" volume_type: - description: the volume type + description: The volume type. returned: when success type: str sample: "standard" volume: - description: a dictionary containing detailed attributes of the volume + description: A dictionary containing detailed attributes of the volume. returned: when success - type: str - sample: { - "attachment_set": [{ - "attach_time": "2015-10-23T00:22:29.000Z", - "deleteOnTermination": "false", - "device": "/dev/sdf", - "instance_id": "i-8356263c", - "status": "attached" - }], - "create_time": "2015-10-21T14:36:08.870Z", - "encrypted": false, - "id": "vol-35b333d9", - "iops": null, - "size": 1, - "snapshot_id": "", - "status": "in-use", - "tags": { - "env": "dev" - }, - "type": "standard", - "zone": "us-east-1b" - } + type: dict + contains: + attachment_set: + description: + - Information about the volume attachments. + - This was changed in version 2.0.0 from a dictionary to a list of dictionaries. + type: list + elements: dict + returned: when success + sample: [{ + "attach_time": "2015-10-23T00:22:29.000Z", + "deleteOnTermination": "false", + "device": "/dev/sdf", + "instance_id": "i-8356263c", + "status": "attached" + }] + create_time: + description: The time stamp when volume creation was initiated. + type: str + returned: when success + sample: "2015-10-21T14:36:08.870Z" + encrypted: + description: Indicates whether the volume is encrypted. + type: bool + returned: when success + sample: False + id: + description: The ID of the volume. + type: str + returned: when success + sample: "vol-35b333d9" + iops: + description: The number of I/O operations per second (IOPS) that the volume supports. + type: int + returned: when success + sample: null + size: + description: The size of the volume, in GiBs. + type: int + returned: when success + sample: 1 + snapshot_id: + description: The snapshot from which the volume was created, if applicable. + type: str + returned: when success + sample: "" + status: + description: The volume state. + type: str + returned: when success + sample: "in-use" + tags: + description: Any tags assigned to the volume. + type: dict + returned: when success + sample: { + env: "dev" + } + type: + description: The volume type. This can be gp2, io1, st1, sc1, or standard. + type: str + returned: when success + sample: "standard" + zone: + description: The Availability Zone of the volume. + type: str + returned: when success + sample: "us-east-1b" + throughput: + description: The throughput that the volume supports, in MiB/s. + type: int + returned: when success + sample: 131 """ import time diff --git a/plugins/modules/ec2_vpc_dhcp_option.py b/plugins/modules/ec2_vpc_dhcp_option.py index 7ed8865ca43..305a9814984 100644 --- a/plugins/modules/ec2_vpc_dhcp_option.py +++ b/plugins/modules/ec2_vpc_dhcp_option.py @@ -68,7 +68,7 @@ inherit_existing: description: - For any DHCP options not specified in these parameters, whether to - inherit them from the options set already applied to I(vpc_id), or to + inherit them from the options set already applied to O(vpc_id), or to reset them to be empty. type: bool default: false @@ -87,7 +87,7 @@ choices: [ 'absent', 'present' ] type: str notes: - - Support for I(purge_tags) was added in release 2.0.0. + - Support for O(purge_tags) was added in release 2.0.0. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules diff --git a/plugins/modules/ec2_vpc_endpoint.py b/plugins/modules/ec2_vpc_endpoint.py index c894412eb32..2ac7df38376 100644 --- a/plugins/modules/ec2_vpc_endpoint.py +++ b/plugins/modules/ec2_vpc_endpoint.py @@ -29,7 +29,7 @@ vpc_endpoint_subnets: description: - The list of subnets to attach to the endpoint. - - Requires I(vpc_endpoint_type=GatewayLoadBalancer) or I(vpc_endpoint_type=Interface). + - Requires O(vpc_endpoint_type=GatewayLoadBalancer) or O(vpc_endpoint_type=Interface). required: false type: list elements: str @@ -37,7 +37,7 @@ vpc_endpoint_security_groups: description: - The list of security groups to attach to the endpoint. - - Requires I(vpc_endpoint_type=GatewayLoadBalancer) or I(vpc_endpoint_type=Interface). + - Requires O(vpc_endpoint_type=GatewayLoadBalancer) or O(vpc_endpoint_type=Interface). required: false type: list elements: str @@ -59,15 +59,15 @@ type: json state: description: - - C(present) to ensure resource is created. - - C(absent) to remove resource. + - V(present) to ensure resource is created. + - V(absent) to remove resource. required: false default: present choices: [ "present", "absent" ] type: str wait: description: - - When specified, will wait for status to reach C(available) for I(state=present). + - When specified, will wait for status to reach available for O(state=present). - Unfortunately this is ignored for delete actions due to a difference in behaviour from AWS. required: false @@ -75,7 +75,7 @@ type: bool wait_timeout: description: - - Used in conjunction with I(wait). + - Used in conjunction with O(wait). - Number of seconds to wait for status. - Unfortunately this is ignored for delete actions due to a difference in behaviour from AWS. @@ -87,14 +87,14 @@ - List of one or more route table IDs to attach to the endpoint. - A route is added to the route table with the destination of the endpoint if provided. - - Route table IDs are only valid for C(Gateway) endpoints. + - Route table IDs are only valid for Gateway endpoints. required: false type: list elements: str vpc_endpoint_id: description: - One or more VPC endpoint IDs to remove from the AWS account. - - Required if I(state=absent). + - Required if O(state=absent). required: false type: str client_token: @@ -105,9 +105,9 @@ author: - Karen Cheng (@Etherdaemon) notes: - - Support for I(tags) and I(purge_tags) was added in release 1.5.0. - - The C(policy_file) paramater was removed in release 6.0.0 please use the - I(policy) option and a file lookup instead. + - Support for O(tags) and I(purge_tags) was added in release 1.5.0. + - The I(policy_file) paramater was removed in release 6.0.0 please use the + O(policy) option and the P(ansible.builtin.file#lookup) lookup plugin instead. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -150,36 +150,100 @@ RETURN = r""" endpoints: - description: The resulting endpoints from the module call + description: The resulting endpoints from the module call. returned: success type: list - sample: [ - { - "creation_timestamp": "2017-02-20T05:04:15+00:00", - "policy_document": { - "Id": "Policy1450910922815", - "Statement": [ - { - "Action": "s3:*", - "Effect": "Allow", - "Principal": "*", - "Resource": [ - "arn:aws:s3:::*/*", - "arn:aws:s3:::*" - ], - "Sid": "Stmt1450910920641" - } - ], - "Version": "2012-10-17" - }, - "route_table_ids": [ - "rtb-abcd1234" - ], - "service_name": "com.amazonaws.ap-southeast-2.s3", - "vpc_endpoint_id": "vpce-a1b2c3d4", - "vpc_id": "vpc-abbad0d0" - } - ] + elements: dict + contains: + creation_timestamp: + description: The date and time that the endpoint was created. + returned: always + type: str + dns_entries: + description: List of DNS entires for the endpoint. + returned: always + type: list + elements: dict + contains: + dns_name: + description: The DNS name. + returned: always + type: str + hosted_zone_id: + description: The ID of the private hosted zone. + type: str + groups: + description: List of security groups associated with the network interface. + returned: always + type: list + elements: dict + contains: + group_id: + description: The ID of the security group. + returned: always + type: str + group_name: + description: The name of the security group. + returned: always + type: str + ip_address_type: + description: The IP address type for the endpoint. + type: str + network_interface_ids: + description: List of network interfaces for the endpoint. + returned: always + type: list + elements: str + owner_id: + description: The ID of the AWS account that owns the endpoint. + returned: always + type: str + policy_document: + description: The policy document associated with the endpoint. + returned: always + type: str + private_dns_enabled: + description: Indicates whether the VPC is associated with a private hosted zone. + returned: always + type: bool + requester_managed: + description: Indicated whether the endpoint is being managed by its service. + returned: always + type: bool + route_table_ids: + description: List of route table IDs associated with the endpoint. + returned: always + type: list + elements: str + service_name: + description: The name of the service to which the endpoint is associated. + returned: always + type: str + state: + description: The state of the endpoint. + returned: always + type: str + subnet_ids: + description: List of subnets associated with the endpoint. + returned: always + type: list + tags: + description: List of tags associated with the endpoint. + returned: always + type: list + elements: dict + vpc_endpoint_id: + description: The ID of the endpoint. + returned: always + type: str + vpc_endpoint_type: + description: The type of endpoint. + returned: always + type: str + vpc_id: + description: The ID of the VPC. + returned: always + type: str """ import datetime diff --git a/plugins/modules/ec2_vpc_endpoint_info.py b/plugins/modules/ec2_vpc_endpoint_info.py index e94cf1a94a6..4dd4067214d 100644 --- a/plugins/modules/ec2_vpc_endpoint_info.py +++ b/plugins/modules/ec2_vpc_endpoint_info.py @@ -30,8 +30,8 @@ - amazon.aws.region.modules - amazon.aws.boto3 notes: - - Support for the C(query) parameter was dropped in release 6.0.0. This module now only queries - for endpoints. Information about endpoint services can be retrieved using the + - Support for the I(query) parameter was dropped in release 6.0.0. This module now only queries + for endpoints. Information about endpoint services can be retrieved using the M(amazon.aws.ec2_vpc_endpoint_service_info) module. """ @@ -86,7 +86,6 @@ type: str hosted_zone_id: description: The ID of the private hosted zone. - returned: always type: str groups: description: List of security groups associated with the network interface. @@ -102,6 +101,9 @@ description: The name of the security group. returned: always type: str + ip_address_type: + description: The IP address type for the endpoint. + type: str network_interface_ids: description: List of network interfaces for the endpoint. returned: always @@ -139,7 +141,7 @@ subnet_ids: description: List of subnets associated with the endpoint. returned: always - type: str + type: list tags: description: List of tags associated with the endpoint. returned: always diff --git a/plugins/modules/ec2_vpc_endpoint_service_info.py b/plugins/modules/ec2_vpc_endpoint_service_info.py index e462cfefdb2..9830766f3c2 100644 --- a/plugins/modules/ec2_vpc_endpoint_service_info.py +++ b/plugins/modules/ec2_vpc_endpoint_service_info.py @@ -109,6 +109,10 @@ - The verification state of the VPC endpoint service. - Consumers of an endpoint service cannot use the private name when the state is not C(verified). type: str + supported_ip_address_types: + returned: success + description: The supported IP address types. + type: str """ try: diff --git a/plugins/modules/ec2_vpc_igw.py b/plugins/modules/ec2_vpc_igw.py index b19507a9c72..b8d468aba41 100644 --- a/plugins/modules/ec2_vpc_igw.py +++ b/plugins/modules/ec2_vpc_igw.py @@ -10,7 +10,7 @@ version_added: 1.0.0 short_description: Manage an AWS VPC Internet gateway description: - - Manage an AWS VPC Internet gateway + - Manage an AWS VPC Internet gateway. author: Robert Estelle (@erydo) options: internet_gateway_id: @@ -21,33 +21,33 @@ type: str vpc_id: description: - - The VPC ID for the VPC to attach (when state=present) - - VPC ID can also be provided to find the internet gateway to manage that the VPC is attached to + - The VPC ID for the VPC to attach (when O(state=present)). + - VPC ID can also be provided to find the internet gateway to manage that the VPC is attached to. required: false type: str state: description: - - Create or terminate the IGW + - Create or terminate the IGW. default: present choices: [ 'present', 'absent' ] type: str force_attach: version_added: 7.0.0 description: - - Force attaching VPC to I(vpc_id). - - Setting this option to true will detach an existing VPC attachment and attach to the supplied I(vpc_id). - - Ignored when I(state=absent). - - I(vpc_id) must be specified when I(force_attach) is true + - Force attaching VPC to O(vpc_id). + - Setting this option to true will detach an existing VPC attachment and attach to the supplied O(vpc_id). + - Ignored when O(state=absent). + - O(vpc_id) must be specified when O(force_attach=true). default: false type: bool detach_vpc: version_added: 7.0.0 description: - - Remove attached VPC from gateway + - Remove attached VPC from gateway. default: false type: bool notes: -- Support for I(purge_tags) was added in release 1.3.0. +- Support for O(purge_tags) was added in release 1.3.0. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -118,20 +118,20 @@ gateway_id: description: The unique identifier for the Internet Gateway. type: str - returned: I(state=present) + returned: O(state=present) sample: gateway_id: "igw-XXXXXXXX" tags: description: The tags associated the Internet Gateway. type: dict - returned: I(state=present) + returned: O(state=present) sample: tags: "Ansible": "Test" vpc_id: description: The VPC ID associated with the Internet Gateway. type: str - returned: I(state=present) + returned: O(state=present) sample: vpc_id: "vpc-XXXXXXXX" """ diff --git a/plugins/modules/ec2_vpc_igw_info.py b/plugins/modules/ec2_vpc_igw_info.py index 583719c040f..6a76365d420 100644 --- a/plugins/modules/ec2_vpc_igw_info.py +++ b/plugins/modules/ec2_vpc_igw_info.py @@ -27,8 +27,8 @@ convert_tags: description: - Convert tags from boto3 format (list of dictionaries) to the standard dictionary format. - - Prior to release 4.0.0 this defaulted to C(False). - default: True + - Prior to release 4.0.0 this defaulted to V(false). + default: true type: bool version_added: 1.3.0 extends_documentation_fragment: @@ -67,7 +67,7 @@ description: True if listing the internet gateways succeeds. type: bool returned: always - sample: "false" + sample: false internet_gateways: description: The internet gateways for the account. returned: always @@ -75,27 +75,27 @@ contains: attachments: description: Any VPCs attached to the internet gateway. - returned: I(state=present) + returned: always type: complex contains: state: description: The current state of the attachment. - returned: I(state=present) + returned: always type: str sample: available vpc_id: description: The ID of the VPC. - returned: I(state=present) + returned: always type: str sample: vpc-02123b67 internet_gateway_id: description: The ID of the internet gateway. - returned: I(state=present) + returned: always type: str sample: igw-2123634d tags: description: Any tags assigned to the internet gateway. - returned: I(state=present) + returned: always type: dict sample: tags: diff --git a/plugins/modules/ec2_vpc_nat_gateway.py b/plugins/modules/ec2_vpc_nat_gateway.py index 2469789df48..fbc15292f16 100644 --- a/plugins/modules/ec2_vpc_nat_gateway.py +++ b/plugins/modules/ec2_vpc_nat_gateway.py @@ -43,12 +43,12 @@ eip_address: description: - The elastic IP address of the EIP you want attached to this NAT Gateway. - If this is not passed and the allocation_id is not passed, + If this is not passed and the O(allocation_id) is not passed, an EIP is generated for this NAT Gateway. type: str if_exist_do_not_create: description: - - if a NAT Gateway exists already in the subnet_id, then do not create a new one. + - If a NAT Gateway exists already in the O(subnet_id), then do not create a new one. required: false default: false type: bool @@ -77,11 +77,11 @@ type: str default_create: description: - - When I(default_create=True) and I(eip_address) has been set, but not yet + - When O(default_create=true) and O(eip_address) has been set, but not yet allocated, the NAT gateway is created and a new EIP is automatically allocated. - - When I(default_create=False) and I(eip_address) has been set, but not yet + - When O(default_create=false) and O(eip_address) has been set, but not yet allocated, the module will fail. - - If I(eip_address) has not been set, this parameter has no effect. + - If O(eip_address) has not been set, this parameter has no effect. default: false type: bool version_added: 6.2.0 @@ -91,7 +91,7 @@ - Karen Cheng (@Etherdaemon) - Alina Buzachis (@alinabuzachis) notes: - - Support for I(tags) and I(purge_tags) was added in release 1.4.0. + - Support for O(tags) and O(purge_tags) was added in release 1.4.0. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -197,24 +197,30 @@ """ RETURN = r""" +connectivity_type: + description: + - Indicates whether the NAT gateway supports public or private connectivity. + returned: always + type: str + sample: public create_time: description: The ISO 8601 date time format in UTC. - returned: In all cases. + returned: always type: str sample: "2016-03-05T05:19:20.282000+00:00'" nat_gateway_id: - description: id of the VPC NAT Gateway - returned: In all cases. + description: Id of the VPC NAT Gateway. + returned: always type: str sample: "nat-0d1e3a878585988f8" subnet_id: - description: id of the Subnet - returned: In all cases. + description: Id of the Subnet. + returned: always type: str sample: "subnet-12345" state: description: The current state of the NAT Gateway. - returned: In all cases. + returned: always type: str sample: "available" tags: @@ -225,21 +231,60 @@ tags: "Ansible": "Test" vpc_id: - description: id of the VPC. - returned: In all cases. + description: Id of the VPC. + returned: always type: str sample: "vpc-12345" nat_gateway_addresses: description: List of dictionaries containing the public_ip, network_interface_id, private_ip, and allocation_id. - returned: In all cases. - type: str + returned: always + type: complex + contains: + allocation_id: + description: The allocation ID of the Elastic IP address that's associated with the NAT gateway. + returned: always + type: str + sample: eipalloc-0853e66a40803da76 + association_id: + description: The association ID of the Elastic IP address that is associated with the NAT gateway. + returned: always + type: str + sample: eipassoc-0d6365c7eeb7d4932 + is_primary: + description: Defines if the IP address is the primary address. + returned: always + type: bool + sample: true + network_interface_id: + description: The ID of the network interface associated with the NAT gateway. + returned: always + type: str + sample: eni-0a37acdbe306c661c + private_ip: + description: The private IP address associated with the Elastic IP address. + returned: always + type: str + sample: 10.0.238.227 + public_ip: + description: The Elastic IP address associated with the NAT gateway. + returned: always + type: str + sample: 34.204.123.52 + status: + description: The address status. + returned: always + type: str + sample: succeeded sample: [ - { - 'public_ip': '52.52.52.52', - 'network_interface_id': 'eni-12345', - 'private_ip': '10.0.0.100', - 'allocation_id': 'eipalloc-12345' - } + { + "allocation_id": "eipalloc-08ec128d03629671d", + "association_id": "eipassoc-0d6365c7eeb7d4932", + "is_primary": true, + "network_interface_id": "eni-095104e630881bad6", + "private_ip": "10.1.0.250", + "public_ip": "34.202.90.172", + "status": "succeeded" + } ] """ diff --git a/plugins/modules/ec2_vpc_nat_gateway_info.py b/plugins/modules/ec2_vpc_nat_gateway_info.py index a8c76142a93..c805e7386dc 100644 --- a/plugins/modules/ec2_vpc_nat_gateway_info.py +++ b/plugins/modules/ec2_vpc_nat_gateway_info.py @@ -9,7 +9,7 @@ short_description: Retrieves AWS VPC Managed Nat Gateway details using AWS methods version_added: 1.0.0 description: - - Gets various details related to AWS VPC Managed Nat Gateways + - Gets various details related to AWS VPC Managed Nat Gateways. options: nat_gateway_ids: description: @@ -79,6 +79,12 @@ returned: suceess type: list contains: + connectivity_type: + description: + - Indicates whether the NAT gateway supports public or private connectivity. + returned: always + type: str + sample: public create_time: description: The date and time the NAT gateway was created. returned: always @@ -99,6 +105,16 @@ returned: always type: str sample: eipalloc-0853e66a40803da76 + association_id: + description: The association ID of the Elastic IP address that is associated with the NAT gateway. + returned: always + type: str + sample: eipassoc-0d6365c7eeb7d4932 + is_primary: + description: Defines if the IP address is the primary address. + returned: always + type: bool + sample: true network_interface_id: description: The ID of the network interface associated with the NAT gateway. returned: always @@ -114,6 +130,11 @@ returned: always type: str sample: 34.204.123.52 + status: + description: The address status. + returned: always + type: str + sample: succeeded nat_gateway_id: description: The ID of the NAT gateway. returned: always diff --git a/plugins/modules/ec2_vpc_net.py b/plugins/modules/ec2_vpc_net.py index 9e286201381..a3bc5aa9772 100644 --- a/plugins/modules/ec2_vpc_net.py +++ b/plugins/modules/ec2_vpc_net.py @@ -17,42 +17,42 @@ options: name: description: - - The name to give your VPC. This is used in combination with I(cidr_block) + - The name to give your VPC. This is used in combination with O(cidr_block) to determine if a VPC already exists. - - The value of I(name) overrides any value set for C(Name) in the I(tags) + - The value of O(name) overrides any value set for V(Name) in the O(tags) parameter. - - At least one of I(name) and I(vpc_id) must be specified. - - I(name) must be specified when creating a new VPC. + - At least one of O(name) and O(vpc_id) must be specified. + - O(name) must be specified when creating a new VPC. type: str vpc_id: version_added: 4.0.0 description: - The ID of the VPC. - - At least one of I(name) and I(vpc_id) must be specified. - - At least one of I(name) and I(cidr_block) must be specified. + - At least one of O(name) and O(vpc_id) must be specified. + - At least one of O(name) and O(cidr_block) must be specified. type: str cidr_block: description: - The primary CIDR of the VPC. - The first in the list will be used as the primary CIDR - and is used in conjunction with I(name) to ensure idempotence. - - Required when I(vpc_id) is not set. + and is used in conjunction with O(name) to ensure idempotence. + - Required when O(vpc_id) is not set. type: list elements: str ipv6_cidr: description: - Request an Amazon-provided IPv6 CIDR block with /56 prefix length. You cannot specify the range of IPv6 addresses, or the size of the CIDR block. - - Default value is C(false) when creating a new VPC. + - Default value is V(false) when creating a new VPC. type: bool purge_cidrs: description: - - Remove CIDRs that are associated with the VPC and are not specified in I(cidr_block). + - Remove CIDRs that are associated with the VPC and are not specified in O(cidr_block). default: false type: bool tenancy: description: - - Whether to be default or dedicated tenancy. + - Whether to be V(default) or V(dedicated) tenancy. - This cannot be changed after the VPC has been created. default: default choices: [ 'default', 'dedicated' ] @@ -60,12 +60,12 @@ dns_support: description: - Whether to enable AWS DNS support. - - Default value is C(true) when creating a new VPC. + - Default value is V(true) when creating a new VPC. type: bool dns_hostnames: description: - Whether to enable AWS hostname support. - - Default value is C(true) when creating a new VPC. + - Default value is V(true) when creating a new VPC. type: bool dhcp_opts_id: description: @@ -80,7 +80,7 @@ multi_ok: description: - By default the module will not create another VPC if there is another VPC with the same name and CIDR block. - Specify I(multi_ok=true) if you want duplicate VPCs created. + Specify O(multi_ok=true) if you want duplicate VPCs created. type: bool default: false extends_documentation_fragment: @@ -119,17 +119,17 @@ RETURN = r""" vpc: - description: info about the VPC that was created or deleted + description: Info about the VPC that was created or deleted. returned: always type: complex contains: cidr_block: - description: The CIDR of the VPC + description: The CIDR of the VPC. returned: always type: str sample: 10.0.0.0/16 cidr_block_association_set: - description: IPv4 CIDR blocks associated with the VPC + description: IPv4 CIDR blocks associated with the VPC. returned: success type: list sample: @@ -143,12 +143,12 @@ } ] dhcp_options_id: - description: the id of the DHCP options associated with this VPC + description: The id of the DHCP options associated with this VPC. returned: always type: str sample: dopt-12345678 id: - description: VPC resource id + description: VPC resource id. returned: always type: str sample: vpc-12345678 @@ -159,12 +159,12 @@ sample: MyVPC version_added: 4.0.0 instance_tenancy: - description: indicates whether VPC uses default or dedicated tenancy + description: Indicates whether VPC uses default or dedicated tenancy. returned: always type: str sample: default ipv6_cidr_block_association_set: - description: IPv6 CIDR blocks associated with the VPC + description: IPv6 CIDR blocks associated with the VPC. returned: success type: list sample: @@ -178,22 +178,22 @@ } ] is_default: - description: indicates whether this is the default VPC + description: Indicates whether this is the default VPC. returned: always type: bool sample: false state: - description: state of the VPC + description: State of the VPC. returned: always type: str sample: available tags: - description: tags attached to the VPC, includes name + description: Tags attached to the VPC, includes name. returned: always type: complex contains: Name: - description: name tag for the VPC + description: Name tag for the VPC. returned: always type: str sample: pk_vpc4 diff --git a/plugins/modules/ec2_vpc_net_info.py b/plugins/modules/ec2_vpc_net_info.py index 93b44fa7920..a9d357cfb86 100644 --- a/plugins/modules/ec2_vpc_net_info.py +++ b/plugins/modules/ec2_vpc_net_info.py @@ -8,9 +8,9 @@ --- module: ec2_vpc_net_info version_added: 1.0.0 -short_description: Gather information about ec2 VPCs in AWS +short_description: Gather information about EC2 VPCs in AWS description: - - Gather information about ec2 VPCs in AWS + - Gather information about EC2 VPCs in AWS. author: "Rob White (@wimnat)" options: vpc_ids: diff --git a/plugins/modules/ec2_vpc_route_table.py b/plugins/modules/ec2_vpc_route_table.py index 1d41b89eacf..57db93cdb91 100644 --- a/plugins/modules/ec2_vpc_route_table.py +++ b/plugins/modules/ec2_vpc_route_table.py @@ -19,18 +19,18 @@ gateway_id: description: - The ID of the gateway to associate with the route table. - - If I(gateway_id) is C('None') or C(''), gateway will be disassociated with the route table. + - If O(gateway_id) is V('None') or V(''), gateway will be disassociated with the route table. type: str version_added: 3.2.0 lookup: description: - - Look up route table by either I(tags) or by I(route_table_id). - - If I(lookup=tag) and I(tags) is not specified then no lookup for an + - Look up route table by either O(tags) or by O(route_table_id). + - If O(lookup=tag) and O(tags) is not specified then no lookup for an existing route table is performed and a new route table will be created. - - When using I(lookup=tag), multiple matches being found will result in + - When using O(lookup=tag), multiple matches being found will result in a failure and no changes will be made. - - To change the tags of a route table use I(lookup=id). - - I(vpc_id) must be specified when I(lookup=tag). + - To change the tags of a route table use O(lookup=id). + - O(vpc_id) must be specified when O(lookup=tag). default: tag choices: [ 'tag', 'id' ] type: str @@ -51,16 +51,16 @@ route_table_id: description: - The ID of the route table to update or delete. - - Required when I(lookup=id). + - Required when O(lookup=id). type: str routes: description: - List of routes in the route table. - - Routes are specified as dicts containing the keys C(dest) and one of C(gateway_id), - C(instance_id), C(network_interface_id), or C(vpc_peering_connection_id). - - The value of C(dest) is used for the destination match. It may be a IPv4 CIDR block + - Routes are specified as dicts containing the keys V(dest) and one of V(gateway_id), + V(instance_id), V(network_interface_id), or V(vpc_peering_connection_id). + - The value of V(dest) is used for the destination match. It may be a IPv4 CIDR block or a IPv6 CIDR block. - - If I(gateway_id) is specified, you can refer to the VPC's IGW by using the value C(igw). + - If V(gateway_id) is specified, you can refer to the VPC's IGW by using the value V(igw). - Routes are required for present states. type: list elements: dict @@ -78,10 +78,10 @@ vpc_id: description: - VPC ID of the VPC in which to create the route table. - - Required when I(state=present) or I(lookup=tag). + - Required when O(state=present) or O(lookup=tag). type: str notes: - - Tags are used to uniquely identify route tables within a VPC when the I(route_table_id) is not supplied. + - Tags are used to uniquely identify route tables within a VPC when the O(route_table_id) is not supplied. extends_documentation_fragment: - amazon.aws.common.modules - amazon.aws.region.modules @@ -207,10 +207,14 @@ type: str sample: subnet-82055af9 id: - description: ID of the route table (same as route_table_id for backwards compatibility). + description: ID of the route table (same as RV(route_table.route_table_id) for backwards compatibility). returned: always type: str sample: rtb-bf779ed7 + owner_id: + description: AWS account owning resource. + type: str + sample: 123456789012 propagating_vgws: description: List of Virtual Private Gateways propagating routes. returned: always diff --git a/plugins/modules/ec2_vpc_route_table_info.py b/plugins/modules/ec2_vpc_route_table_info.py index d330299af37..bde66f03378 100644 --- a/plugins/modules/ec2_vpc_route_table_info.py +++ b/plugins/modules/ec2_vpc_route_table_info.py @@ -10,7 +10,7 @@ version_added: 1.0.0 short_description: Gather information about ec2 VPC route tables in AWS description: - - Gather information about ec2 VPC route tables in AWS + - Gather information about EC2 VPC route tables in AWS. author: - "Rob White (@wimnat)" - "Mark Chappell (@tremble)" @@ -103,7 +103,7 @@ type: str sample: subnet-82055af9 id: - description: ID of the route table (same as route_table_id for backwards compatibility). + description: ID of the route table (same as RV(route_tables.route_table_id) for backwards compatibility). returned: always type: str sample: rtb-bf779ed7 diff --git a/plugins/modules/ec2_vpc_subnet.py b/plugins/modules/ec2_vpc_subnet.py index 29c7c75f226..e84ba577f7f 100644 --- a/plugins/modules/ec2_vpc_subnet.py +++ b/plugins/modules/ec2_vpc_subnet.py @@ -18,25 +18,25 @@ az: description: - The availability zone for the subnet. - - Required if I(outpost_arn) is set. + - Required if O(outpost_arn) is set. type: str cidr: description: - - The CIDR block for the subnet. E.g. C(192.0.2.0/24). + - The CIDR block for the subnet. E.g. V(192.0.2.0/24). type: str required: true ipv6_cidr: description: - The IPv6 CIDR block for the subnet. - The VPC must have a /56 block assigned and this value must be a valid IPv6 /64 that falls in the VPC range. - - Required if I(assign_instances_ipv6=true) + - Required if O(assign_instances_ipv6=true) type: str default: '' outpost_arn: description: - The Amazon Resource Name (ARN) of the Outpost. - If set, allows to create subnet in an Outpost. - - If I(outpost_arn) is set, I(az) must also be specified. + - If O(outpost_arn) is set, O(az) must also be specified. type: str default: '' state: @@ -58,7 +58,7 @@ assign_instances_ipv6: description: - Whether instances launched into the subnet should default to being automatically assigned an IPv6 address. - - If I(assign_instances_ipv6=true), I(ipv6_cidr) must also be specified. + - If O(assign_instances_ipv6=true), O(ipv6_cidr) must also be specified. type: bool default: false wait: @@ -69,7 +69,7 @@ wait_timeout: description: - Number of seconds to wait for changes to complete - - Ignored unless I(wait=True). + - Ignored unless O(wait=true). default: 300 type: int extends_documentation_fragment: @@ -114,77 +114,91 @@ RETURN = r""" subnet: - description: Dictionary of subnet values - returned: I(state=present) + description: Dictionary of subnet values. + returned: O(state=present) type: complex contains: id: - description: Subnet resource id - returned: I(state=present) + description: Subnet resource id. + returned: O(state=present) type: str sample: subnet-b883b2c4 cidr_block: - description: The IPv4 CIDR of the Subnet - returned: I(state=present) + description: The IPv4 CIDR of the Subnet. + returned: O(state=present) type: str sample: "10.0.0.0/16" ipv6_cidr_block: - description: The IPv6 CIDR block actively associated with the Subnet - returned: I(state=present) + description: The IPv6 CIDR block actively associated with the Subnet. + returned: O(state=present) type: str sample: "2001:db8:0:102::/64" availability_zone: - description: Availability zone of the Subnet - returned: I(state=present) + description: Availability zone of the Subnet. + returned: O(state=present) type: str sample: us-east-1a + availability_zone_id: + description: The AZ ID of the subnet. + returned: O(state=present) + type: str + sample: use1-az6 state: - description: state of the Subnet - returned: I(state=present) + description: State of the Subnet. + returned: O(state=present) type: str sample: available tags: - description: tags attached to the Subnet, includes name - returned: I(state=present) + description: Tags attached to the Subnet, includes name. + returned: O(state=present) type: dict sample: {"Name": "My Subnet", "env": "staging"} map_public_ip_on_launch: - description: whether public IP is auto-assigned to new instances - returned: I(state=present) + description: Whether public IP is auto-assigned to new instances. + returned: O(state=present) type: bool sample: false assign_ipv6_address_on_creation: - description: whether IPv6 address is auto-assigned to new instances - returned: I(state=present) + description: Whether IPv6 address is auto-assigned to new instances. + returned: O(state=present) type: bool sample: false vpc_id: - description: the id of the VPC where this Subnet exists - returned: I(state=present) + description: The id of the VPC where this Subnet exists. + returned: O(state=present) type: str sample: vpc-67236184 available_ip_address_count: - description: number of available IPv4 addresses - returned: I(state=present) + description: Number of available IPv4 addresses. + returned: O(state=present) type: str sample: 251 default_for_az: - description: indicates whether this is the default Subnet for this Availability Zone - returned: I(state=present) + description: Indicates whether this is the default Subnet for this Availability Zone. + returned: O(state=present) + type: bool + sample: false + enable_dns64: + description: + - Indicates whether DNS queries made should return synthetic IPv6 addresses for IPv4-only destinations. type: bool sample: false ipv6_association_id: - description: The IPv6 association ID for the currently associated CIDR - returned: I(state=present) + description: The IPv6 association ID for the currently associated CIDR. + returned: O(state=present) type: str sample: subnet-cidr-assoc-b85c74d2 + ipv6_native: + description: Indicates whether this is an IPv6 only subnet. + type: bool + sample: false ipv6_cidr_block_association_set: description: An array of IPv6 cidr block association set information. - returned: I(state=present) + returned: O(state=present) type: complex contains: association_id: - description: The association ID + description: The association ID. returned: always type: str ipv6_cidr_block: @@ -200,6 +214,30 @@ description: The CIDR block association state. returned: always type: str + map_customer_owned_ip_on_launch: + description: + - Indicates whether a network interface receives a customer-owned IPv4 address. + type: bool + sample: flase + owner_id: + description: The ID of the Amazon Web Services account that owns the subnet. + type: str + sample: 12344567 + private_dns_name_options_on_launch: + description: + - The type of hostnames to assign to instances in the subnet at launch. + - An instance hostname is based on the IPv4 address or ID of the instance. + type: dict + sample: { + "enable_resource_name_dns_a_record": false, + "enable_resource_name_dns_aaaa_record": false, + "hostname_type": "ip-name" + } + subnet_arn: + description: The Amazon Resource Name (ARN) of the subnet. + type: str + sample: arn:aws:ec2:us-east-1:xxx:subnet/subnet-xxx + """ diff --git a/plugins/modules/ec2_vpc_subnet_info.py b/plugins/modules/ec2_vpc_subnet_info.py index 654f5609a3b..9bf2133911a 100644 --- a/plugins/modules/ec2_vpc_subnet_info.py +++ b/plugins/modules/ec2_vpc_subnet_info.py @@ -8,9 +8,9 @@ --- module: ec2_vpc_subnet_info version_added: 1.0.0 -short_description: Gather information about ec2 VPC subnets in AWS +short_description: Gather information about EC2 VPC subnets in AWS description: - - Gather information about ec2 VPC subnets in AWS + - Gather information about EC2 VPC subnets in AWS. author: "Rob White (@wimnat)" options: subnet_ids: @@ -76,57 +76,87 @@ returned: success type: complex contains: - subnet_id: - description: The ID of the Subnet. + id: + description: Subnet resource id. returned: always type: str - id: - description: The ID of the Subnet (for backwards compatibility). + sample: subnet-b883b2c4 + cidr_block: + description: The IPv4 CIDR of the Subnet. returned: always type: str - vpc_id: - description: The ID of the VPC . + sample: "10.0.0.0/16" + ipv6_cidr_block: + description: The IPv6 CIDR block actively associated with the Subnet. returned: always type: str + sample: "2001:db8:0:102::/64" + availability_zone: + description: Availability zone of the Subnet. + returned: always + type: str + sample: us-east-1a + availability_zone_id: + description: The AZ ID of the subnet. + returned: always + type: str + sample: use1-az6 state: - description: The state of the subnet. + description: state of the Subnet. returned: always type: str + sample: available tags: - description: A dict of tags associated with the Subnet. + description: tags attached to the Subnet, includes name. returned: always type: dict + sample: {"Name": "My Subnet", "env": "staging"} map_public_ip_on_launch: - description: True/False depending on attribute setting for public IP mapping. + description: whether public IP is auto-assigned to new instances. returned: always type: bool - default_for_az: - description: True if this is the default subnet for AZ. + sample: false + assign_ipv6_address_on_creation: + description: whether IPv6 address is auto-assigned to new instances. returned: always type: bool - cidr_block: - description: The IPv4 CIDR block assigned to the subnet. + sample: false + vpc_id: + description: the id of the VPC where this Subnet exists. returned: always type: str + sample: vpc-67236184 available_ip_address_count: - description: Count of available IPs in subnet. + description: number of available IPv4 addresses. returned: always type: str - availability_zone: - description: The availability zone where the subnet exists. + sample: 251 + default_for_az: + description: indicates whether this is the default Subnet for this Availability Zone. returned: always - type: str - assign_ipv6_address_on_creation: - description: True/False depending on attribute setting for IPv6 address assignment. + type: bool + sample: false + enable_dns64: + description: + - Indicates whether DNS queries made should return synthetic IPv6 addresses for IPv4-only destinations. + type: bool + sample: false + ipv6_association_id: + description: The IPv6 association ID for the currently associated CIDR. returned: always + type: str + sample: subnet-cidr-assoc-b85c74d2 + ipv6_native: + description: Indicates whether this is an IPv6 only subnet. type: bool + sample: false ipv6_cidr_block_association_set: description: An array of IPv6 cidr block association set information. returned: always type: complex contains: association_id: - description: The association ID + description: The association ID. returned: always type: str ipv6_cidr_block: @@ -142,6 +172,33 @@ description: The CIDR block association state. returned: always type: str + map_customer_owned_ip_on_launch: + description: + - Indicates whether a network interface receives a customer-owned IPv4 address. + type: bool + sample: flase + owner_id: + description: The ID of the Amazon Web Services account that owns the subnet. + type: str + sample: 12344567 + private_dns_name_options_on_launch: + description: + - The type of hostnames to assign to instances in the subnet at launch. + - An instance hostname is based on the IPv4 address or ID of the instance. + type: dict + sample: { + "enable_resource_name_dns_a_record": false, + "enable_resource_name_dns_aaaa_record": false, + "hostname_type": "ip-name" + } + subnet_arn: + description: The Amazon Resource Name (ARN) of the subnet. + type: str + sample: arn:aws:ec2:us-east-1:xxx:subnet/subnet-xxx + subnet_id: + description: The ID of the Subnet. + returned: always + type: str """ try: diff --git a/plugins/modules/lambda_event.py b/plugins/modules/lambda_event.py index 2778aef4e08..424ad5abeca 100644 --- a/plugins/modules/lambda_event.py +++ b/plugins/modules/lambda_event.py @@ -54,22 +54,28 @@ type: str source_params: description: - - Sub-parameters required for event source. + - Sub-parameters required for event source. suboptions: source_arn: description: - - The Amazon Resource Name (ARN) of the SQS queue, Kinesis stream or DynamoDB stream that is the event source. + - The Amazon Resource Name (ARN) of the SQS queue, Kinesis stream or DynamoDB stream that is the event source. type: str required: true enabled: description: - - Indicates whether AWS Lambda should begin polling or readin from the event source. + - Indicates whether AWS Lambda should begin polling or readin from the event source. default: true type: bool batch_size: description: - - The largest number of records that AWS Lambda will retrieve from your event source at the time of invoking your function. - default: 100 + - The largest number of records that AWS Lambda will retrieve from your event source at the time of invoking your function. + - Amazon Kinesis - Default V(100). Max V(10000). + - Amazon DynamoDB Streams - Default V(100). Max V(10000). + - Amazon Simple Queue Service - Default V(10). For standard queues the max is V(10000). For FIFO queues the max is V(10). + - Amazon Managed Streaming for Apache Kafka - Default V(100). Max V(10000). + - Self-managed Apache Kafka - Default C(100). Max V(10000). + - Amazon MQ (ActiveMQ and RabbitMQ) - Default V(100). Max V(10000). + - DocumentDB - Default V(100). Max V(10000). type: int starting_position: description: @@ -84,6 +90,15 @@ elements: str choices: [ReportBatchItemFailures] version_added: 5.5.0 + maximum_batching_window_in_seconds: + description: + - The maximum amount of time, in seconds, that Lambda spends gathering records before invoking the function. + - You can configure O(source_params.maximum_batching_window_in_seconds) to any value from V(0) seconds to V(300) seconds in increments of seconds. + - For streams and Amazon SQS event sources, when O(source_params.batch_size) is set to a value greater than V(10), + O(source_params.maximum_batching_window_in_seconds) defaults to V(1). + - O(source_params.maximum_batching_window_in_seconds) is not supported by FIFO queues. + type: int + version_added: 8.0.0 required: true type: dict extends_documentation_fragment: @@ -135,6 +150,7 @@ type: list """ +import copy import re try: @@ -228,6 +244,37 @@ def get_qualifier(module): # --------------------------------------------------------------------------------------------------- +def set_default_values(module, source_params): + _source_params_cpy = copy.deepcopy(source_params) + + if module.params["event_source"].lower() == "sqs": + # Default 10. For standard queues the max is 10,000. For FIFO queues the max is 10. + _source_params_cpy.setdefault("batch_size", 10) + + if source_params["source_arn"].endswith(".fifo"): + if _source_params_cpy["batch_size"] > 10: + module.fail_json(msg="For FIFO queues the maximum batch_size is 10.") + if _source_params_cpy.get("maximum_batching_window_in_seconds"): + module.fail_json( + msg="maximum_batching_window_in_seconds is not supported by Amazon SQS FIFO event sources." + ) + else: + if _source_params_cpy["batch_size"] >= 10000: + module.fail_json(msg="For standard queue batch_size must be between lower than 10000.") + + elif module.params["event_source"].lower() == "stream": + # Default 100. + _source_params_cpy.setdefault("batch_size", 100) + + if not (100 <= _source_params_cpy["batch_size"] <= 10000): + module.fail_json(msg="batch_size for streams must be between 100 and 10000") + + if _source_params_cpy["batch_size"] > 10 and not _source_params_cpy.get("maximum_batching_window_in_seconds"): + _source_params_cpy["maximum_batching_window_in_seconds"] = 1 + + return _source_params_cpy + + def lambda_event_stream(module, client): """ Adds, updates or deletes lambda stream (DynamoDb, Kinesis) event notifications. @@ -252,13 +299,8 @@ def lambda_event_stream(module, client): else: module.fail_json(msg="Source parameter 'source_arn' is required for stream event notification.") - # check if optional sub-parameters are valid, if present - batch_size = source_params.get("batch_size") - if batch_size: - try: - source_params["batch_size"] = int(batch_size) - except ValueError: - module.fail_json(msg=f"Source parameter 'batch_size' must be an integer, found: {batch_size}") + if state == "present": + source_params = set_default_values(module, source_params) # optional boolean value needs special treatment as not present does not imply False source_param_enabled = module.boolean(source_params.get("enabled", "True")) @@ -285,6 +327,10 @@ def lambda_event_stream(module, client): api_params.update(Enabled=source_param_enabled) if source_params.get("batch_size"): api_params.update(BatchSize=source_params.get("batch_size")) + if source_params.get("maximum_batching_window_in_seconds"): + api_params.update( + MaximumBatchingWindowInSeconds=source_params.get("maximum_batching_window_in_seconds") + ) if source_params.get("function_response_types"): api_params.update(FunctionResponseTypes=source_params.get("function_response_types")) @@ -347,7 +393,18 @@ def main(): state=dict(required=False, default="present", choices=["present", "absent"]), lambda_function_arn=dict(required=True, aliases=["function_name", "function_arn"]), event_source=dict(required=False, default="stream", choices=source_choices), - source_params=dict(type="dict", required=True), + source_params=dict( + type="dict", + required=True, + options=dict( + source_arn=dict(type="str", required=True), + enabled=dict(type="bool", default=True), + batch_size=dict(type="int"), + starting_position=dict(type="str", choices=["TRIM_HORIZON", "LATEST"]), + function_response_types=dict(type="list", elements="str", choices=["ReportBatchItemFailures"]), + maximum_batching_window_in_seconds=dict(type="int"), + ), + ), alias=dict(required=False, default=None), version=dict(type="int", required=False, default=0), ) diff --git a/plugins/modules/lambda_info.py b/plugins/modules/lambda_info.py index 83ba4feaa98..fbd443bb7cc 100644 --- a/plugins/modules/lambda_info.py +++ b/plugins/modules/lambda_info.py @@ -95,7 +95,7 @@ elements: str architectures: description: The architectures supported by the function. - returned: successful run where botocore >= 1.21.51 + returned: success type: list elements: str sample: ['arm64'] diff --git a/plugins/modules/rds_cluster.py b/plugins/modules/rds_cluster.py index 0e35861f7d9..30a7145e705 100644 --- a/plugins/modules/rds_cluster.py +++ b/plugins/modules/rds_cluster.py @@ -170,7 +170,6 @@ - For the full list of DB instance classes and availability for your engine visit U(https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.DBInstanceClass.html). - This setting is required to create a Multi-AZ DB cluster. - - I(db_cluster_instance_class) require botocore >= 1.23.44. type: str version_added: 5.5.0 enable_iam_database_authentication: @@ -182,7 +181,6 @@ description: - The amount of storage in gibibytes (GiB) to allocate to each DB instance in the Multi-AZ DB cluster. - This setting is required to create a Multi-AZ DB cluster. - - I(allocated_storage) require botocore >= 1.23.44. type: int version_added: 5.5.0 storage_type: @@ -190,7 +188,6 @@ - Specifies the storage type to be associated with the DB cluster. - This setting is required to create a Multi-AZ DB cluster. - When specified, a value for the I(iops) parameter is required. - - I(storage_type) require botocore >= 1.23.44. - Defaults to C(io1). type: str choices: @@ -201,7 +198,6 @@ - The amount of Provisioned IOPS (input/output operations per second) to be initially allocated for each DB instance in the Multi-AZ DB cluster. - This setting is required to create a Multi-AZ DB cluster - Must be a multiple between .5 and 50 of the storage amount for the DB cluster. - - I(iops) require botocore >= 1.23.44. type: int version_added: 5.5.0 engine: diff --git a/plugins/modules/s3_object.py b/plugins/modules/s3_object.py index 0486d3b9f81..c3e45004a37 100644 --- a/plugins/modules/s3_object.py +++ b/plugins/modules/s3_object.py @@ -783,9 +783,6 @@ def upload_s3file( def download_s3file(module, s3, bucket, obj, dest, retries, version=None): if module.check_mode: module.exit_json(msg="GET operation skipped - running in check mode", changed=True) - # retries is the number of loops; range/xrange needs to be one - # more to get that count of loops. - _get_object_content(module, s3, bucket, obj, version) optional_kwargs = {"ExtraArgs": {"VersionId": version}} if version else {} for x in range(0, retries + 1): diff --git a/tests/integration/targets/backup_plan/tasks/main.yml b/tests/integration/targets/backup_plan/tasks/main.yml index ee8f62ec9a5..79e6e147953 100644 --- a/tests/integration/targets/backup_plan/tasks/main.yml +++ b/tests/integration/targets/backup_plan/tasks/main.yml @@ -344,12 +344,41 @@ - backup_plan_create_result.exists is true - backup_plan_create_result.changed is false + - name: Create another backup plan + amazon.aws.backup_plan: + backup_plan_name: "{{ backup_plan_name }}-1" + rules: + - rule_name: daily + target_backup_vault_name: "{{ backup_vault_name }}" + tags: + Environment: Test + register: backup_plan_create_result_1 + + - name: Verify backup plan create result + ansible.builtin.assert: + that: + - backup_plan_create_result_1.exists is true + - backup_plan_create_result_1.changed is true + + - name: Get info of all install plans + amazon.aws.backup_plan_info: + register: backup_plan_info_result + + - name: Assert that info of all backup plans is fetched + ansible.builtin.assert: + that: + - backup_plan_info_result is not failed + - backup_plan_info_result.backup_plans | length > 1 + always: - name: Delete AWS Backup plan created during this test amazon.aws.backup_plan: - backup_plan_name: "{{ backup_plan_name }}" + backup_plan_name: "{{ item }}" state: absent ignore_errors: true + with_items: + - "{{ backup_plan_name }}" + - "{{ backup_plan_name }}-1" - name: Delete AWS Backup vault created during this test amazon.aws.backup_vault: diff --git a/tests/integration/targets/cloudwatch_metric_alarm/tasks/main.yml b/tests/integration/targets/cloudwatch_metric_alarm/tasks/main.yml index 00c4501c0d8..df1f87a2781 100644 --- a/tests/integration/targets/cloudwatch_metric_alarm/tasks/main.yml +++ b/tests/integration/targets/cloudwatch_metric_alarm/tasks/main.yml @@ -211,13 +211,14 @@ name: "{{ alarm_full_name }}" metric: CPUUtilization namespace: AWS/EC2 - statistic: Average - comparison: LessThanOrEqualToThreshold + extended_statistic: p50 + comparison: GreaterThanOrEqualToThreshold threshold: 5.0 period: 60 evaluation_periods: 3 + evaluate_low_sample_count_percentile: "evaluate" unit: Percent - description: This will alarm when an instance's cpu usage average is lower than 5% for 3 minutes + description: This will alarm when an instance's cpu usage percentage is greater than or equal to 50% for 3 minutes check_mode: true register: ec2_instance_metric_alarm_update_check @@ -251,13 +252,14 @@ name: "{{ alarm_full_name }}" metric: CPUUtilization namespace: AWS/EC2 - statistic: Average - comparison: LessThanOrEqualToThreshold + extended_statistic: p50 + comparison: GreaterThanOrEqualToThreshold threshold: 5.0 period: 60 evaluation_periods: 3 + evaluate_low_sample_count_percentile: "evaluate" unit: Percent - description: This will alarm when an instance's cpu usage average is lower than 5% for 3 minutes + description: This will alarm when an instance's cpu usage percentage is greater than or equal to 50% for 3 minutes register: ec2_instance_metric_alarm_update - name: verify that alarm registers as updated @@ -271,12 +273,12 @@ - ec2_instance_metric_alarm_update.changed - ec2_instance_metric_alarm_update.period == 60 # Period should be 60, not matching old value - ec2_instance_metric_alarm_update.alarm_arn == ec2_instance_metric_alarm.alarm_arn - - ec2_instance_metric_alarm_update.statistic == alarm_info.metric_alarms[0].statistic + - ec2_instance_metric_alarm_update.extended_statistic == 'p50' + - ec2_instance_metric_alarm_update.evaluate_low_sample_count_percentile == 'evaluate' - ec2_instance_metric_alarm_update.name == alarm_info.metric_alarms[0].alarm_name - ec2_instance_metric_alarm_update.metric == alarm_info.metric_alarms[0].metric_name - ec2_instance_metric_alarm_update.namespace == alarm_info.metric_alarms[0].namespace - - ec2_instance_metric_alarm_update.statistic == alarm_info.metric_alarms[0].statistic - - ec2_instance_metric_alarm_update.comparison == alarm_info.metric_alarms[0].comparison_operator + - ec2_instance_metric_alarm_update.comparison == 'GreaterThanOrEqualToThreshold' - ec2_instance_metric_alarm_update.threshold == alarm_info.metric_alarms[0].threshold - ec2_instance_metric_alarm_update.unit == alarm_info.metric_alarms[0].unit - ec2_instance_metric_alarm_update.evaluation_periods == alarm_info.metric_alarms[0].evaluation_periods diff --git a/tests/integration/targets/lambda_event/tasks/main.yml b/tests/integration/targets/lambda_event/tasks/main.yml index f06482a629d..1e49d1373a3 100644 --- a/tests/integration/targets/lambda_event/tasks/main.yml +++ b/tests/integration/targets/lambda_event/tasks/main.yml @@ -6,11 +6,10 @@ secret_key: "{{ aws_secret_key }}" session_token: "{{ security_token | default(omit) }}" region: "{{ aws_region }}" - collections: - - community.general block: - name: Create test resources setup ansible.builtin.import_tasks: setup.yml + - name: Create DynamoDB stream event mapping (trigger) - check_mode amazon.aws.lambda_event: state: present diff --git a/tests/integration/targets/rds_instance_complex/defaults/main.yml b/tests/integration/targets/rds_instance_complex/defaults/main.yml index f2b7946092e..c7b6d0de978 100644 --- a/tests/integration/targets/rds_instance_complex/defaults/main.yml +++ b/tests/integration/targets/rds_instance_complex/defaults/main.yml @@ -14,4 +14,4 @@ storage_type: io1 iops: 1000 # For mariadb tests -mariadb_engine_version: 10.6.10 +mariadb_engine_version: 10.11.7 diff --git a/tests/integration/targets/rds_instance_modify/defaults/main.yml b/tests/integration/targets/rds_instance_modify/defaults/main.yml index 0384232d52a..0e09b9c4c8b 100644 --- a/tests/integration/targets/rds_instance_modify/defaults/main.yml +++ b/tests/integration/targets/rds_instance_modify/defaults/main.yml @@ -7,4 +7,4 @@ db_instance_class: db.t3.micro allocated_storage: 20 # For mariadb tests -mariadb_engine_version: 10.6.10 +mariadb_engine_version: 10.11.7 diff --git a/tests/integration/targets/rds_instance_snapshot/defaults/main.yml b/tests/integration/targets/rds_instance_snapshot/defaults/main.yml index d193876e7dd..e82f395a807 100644 --- a/tests/integration/targets/rds_instance_snapshot/defaults/main.yml +++ b/tests/integration/targets/rds_instance_snapshot/defaults/main.yml @@ -8,7 +8,7 @@ password: "{{ lookup('password', '/dev/null') }}" db_instance_class: db.t3.micro allocated_storage: 10 engine: mariadb -mariadb_engine_version: 10.6.10 +mariadb_engine_version: 10.11.7 # Create snapshot snapshot_id: "{{ instance_id }}-snapshot" diff --git a/tests/integration/targets/rds_option_group/defaults/main.yml b/tests/integration/targets/rds_option_group/defaults/main.yml index e0f04005f98..70a5946bf4b 100644 --- a/tests/integration/targets/rds_option_group/defaults/main.yml +++ b/tests/integration/targets/rds_option_group/defaults/main.yml @@ -1,7 +1,7 @@ --- option_group_name: "{{ resource_prefix }}rds-option-group" engine_name: mysql -major_engine_version: 5.6 +major_engine_version: 8.0 option_group_description: "{{ resource_prefix }}rds-option-group test" instance_id: "{{ resource_prefix }}" username: test diff --git a/tests/sanity/ignore-2.15.txt b/tests/sanity/ignore-2.15.txt index c65bc02952c..78c6a8f6792 100644 --- a/tests/sanity/ignore-2.15.txt +++ b/tests/sanity/ignore-2.15.txt @@ -1,2 +1,4 @@ plugins/inventory/aws_ec2.py yamllint:unparsable-with-libyaml # bug in ansible-test - https://github.com/ansible/ansible/issues/82353 plugins/modules/route53.py validate-modules:parameter-state-invalid-choice # route53_info needs improvements before we can deprecate this +plugins/inventory/aws_ec2.py pylint:collection-deprecated-version +plugins/modules/iam_policy.py pylint:collection-deprecated-version diff --git a/tests/sanity/ignore-2.16.txt b/tests/sanity/ignore-2.16.txt index c65bc02952c..78c6a8f6792 100644 --- a/tests/sanity/ignore-2.16.txt +++ b/tests/sanity/ignore-2.16.txt @@ -1,2 +1,4 @@ plugins/inventory/aws_ec2.py yamllint:unparsable-with-libyaml # bug in ansible-test - https://github.com/ansible/ansible/issues/82353 plugins/modules/route53.py validate-modules:parameter-state-invalid-choice # route53_info needs improvements before we can deprecate this +plugins/inventory/aws_ec2.py pylint:collection-deprecated-version +plugins/modules/iam_policy.py pylint:collection-deprecated-version diff --git a/tests/sanity/ignore-2.17.txt b/tests/sanity/ignore-2.17.txt index 09a7e9cbb50..ff6c70c3d42 100644 --- a/tests/sanity/ignore-2.17.txt +++ b/tests/sanity/ignore-2.17.txt @@ -1 +1,3 @@ plugins/modules/route53.py validate-modules:parameter-state-invalid-choice # route53_info needs improvements before we can deprecate this +plugins/inventory/aws_ec2.py pylint:collection-deprecated-version +plugins/modules/iam_policy.py pylint:collection-deprecated-version diff --git a/tests/sanity/ignore-2.18.txt b/tests/sanity/ignore-2.18.txt index 09a7e9cbb50..ff6c70c3d42 100644 --- a/tests/sanity/ignore-2.18.txt +++ b/tests/sanity/ignore-2.18.txt @@ -1 +1,3 @@ plugins/modules/route53.py validate-modules:parameter-state-invalid-choice # route53_info needs improvements before we can deprecate this +plugins/inventory/aws_ec2.py pylint:collection-deprecated-version +plugins/modules/iam_policy.py pylint:collection-deprecated-version diff --git a/tests/unit/plugins/modules/test_lambda_event.py b/tests/unit/plugins/modules/test_lambda_event.py index 5944d836887..c292329b49a 100644 --- a/tests/unit/plugins/modules/test_lambda_event.py +++ b/tests/unit/plugins/modules/test_lambda_event.py @@ -4,6 +4,7 @@ # This file is part of Ansible # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +from contextlib import nullcontext as does_not_raise from copy import deepcopy from unittest.mock import MagicMock from unittest.mock import patch @@ -12,6 +13,7 @@ from ansible_collections.amazon.aws.plugins.modules.lambda_event import get_qualifier from ansible_collections.amazon.aws.plugins.modules.lambda_event import lambda_event_stream +from ansible_collections.amazon.aws.plugins.modules.lambda_event import set_default_values from ansible_collections.amazon.aws.plugins.modules.lambda_event import validate_params mock_get_qualifier = "ansible_collections.amazon.aws.plugins.modules.lambda_event.get_qualifier" @@ -205,6 +207,7 @@ def test_lambda_event_stream_create_event_missing_starting_position(ansible_aws_ "event_source": "stream", "source_params": { "source_arn": "arn:aws:sqs:us-east-2:123456789012:ansible-test-sqs", + "maximum_batching_window_in_seconds": 1, "batch_size": 200, }, "alias": None, @@ -235,6 +238,7 @@ def test_lambda_event_stream_create_event_missing_starting_position(ansible_aws_ "event_source": "stream", "source_params": { "source_arn": "arn:aws:sqs:us-east-2:123456789012:ansible-test-sqs", + "maximum_batching_window_in_seconds": 1, "batch_size": 250, "starting_position": "END", "function_response_types": ["ReportBatchItemFailures"], @@ -247,6 +251,7 @@ def test_lambda_event_stream_create_event_missing_starting_position(ansible_aws_ "EventSourceArn": "arn:aws:sqs:us-east-2:123456789012:ansible-test-sqs", "StartingPosition": "END", "Enabled": True, + "MaximumBatchingWindowInSeconds": 1, "BatchSize": 250, "FunctionResponseTypes": ["ReportBatchItemFailures"], }, @@ -258,6 +263,7 @@ def test_lambda_event_stream_create_event_missing_starting_position(ansible_aws_ "event_source": "stream", "source_params": { "source_arn": "arn:aws:sqs:us-east-2:123456789012:ansible-test-sqs", + "maximum_batching_window_in_seconds": 1, "batch_size": 250, "starting_position": "END", "function_response_types": ["ReportBatchItemFailures"], @@ -271,6 +277,7 @@ def test_lambda_event_stream_create_event_missing_starting_position(ansible_aws_ "EventSourceArn": "arn:aws:sqs:us-east-2:123456789012:ansible-test-sqs", "StartingPosition": "END", "Enabled": False, + "MaximumBatchingWindowInSeconds": 1, "BatchSize": 250, "FunctionResponseTypes": ["ReportBatchItemFailures"], }, @@ -282,6 +289,7 @@ def test_lambda_event_stream_create_event_missing_starting_position(ansible_aws_ "event_source": "sqs", "source_params": { "source_arn": "arn:aws:sqs:us-east-2:123456789012:ansible-test-sqs", + "maximum_batching_window_in_seconds": 1, "batch_size": 101, }, "alias": None, @@ -291,6 +299,7 @@ def test_lambda_event_stream_create_event_missing_starting_position(ansible_aws_ "FunctionName": "sqs_consumer", "EventSourceArn": "arn:aws:sqs:us-east-2:123456789012:ansible-test-sqs", "Enabled": True, + "MaximumBatchingWindowInSeconds": 1, "BatchSize": 101, }, ), @@ -375,3 +384,161 @@ def test_lambda_event_stream_update_event( api_params.update({"FunctionName": function_name, "UUID": existing_event_source[0]["UUID"]}) assert dict(changed=True, events=event_source_updated) == result client.update_event_source_mapping.assert_called_once_with(**api_params) + + +@pytest.mark.parametrize( + "params, expected, exception, message, source_type", + [ + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052.fifo", + "enabled": True, + "batch_size": 100, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": None, + }, + None, + pytest.raises(SystemExit), + "For FIFO queues the maximum batch_size is 10.", + "sqs", + ), + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052.fifo", + "enabled": True, + "batch_size": 10, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": 1, + }, + None, + pytest.raises(SystemExit), + "maximum_batching_window_in_seconds is not supported by Amazon SQS FIFO event sources.", + "sqs", + ), + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052.fifo", + "enabled": True, + "batch_size": 10, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": None, + }, + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052.fifo", + "enabled": True, + "batch_size": 10, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": None, + }, + does_not_raise(), + None, + "sqs", + ), + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "batch_size": 11000, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": None, + }, + None, + pytest.raises(SystemExit), + "For standard queue batch_size must be lower than 10000.", + "sqs", + ), + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "batch_size": 100, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": None, + }, + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "batch_size": 100, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": 1, + }, + does_not_raise(), + None, + "sqs", + ), + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": None, + }, + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "batch_size": 100, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": 1, + }, + does_not_raise(), + None, + "stream", + ), + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "starting_position": None, + "function_response_types": None, + }, + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "batch_size": 10, + "starting_position": None, + "function_response_types": None, + }, + does_not_raise(), + None, + "sqs", + ), + ( + { + "source_arn": "arn:aws:sqs:us-east-1:123456789012:ansible-test-28277052", + "enabled": True, + "batch_size": 10, + "starting_position": None, + "function_response_types": None, + "maximum_batching_window_in_seconds": None, + }, + None, + pytest.raises(SystemExit), + "batch_size for streams must be between 100 and 10000", + "stream", + ), + ], +) +def test__set_default_values(params, expected, exception, message, source_type): + result = None + module = MagicMock() + module.check_mode = False + module.params = { + "event_source": source_type, + "source_params": params, + } + module.fail_json = MagicMock() + module.fail_json.side_effect = SystemExit(message) + with exception as e: + result = set_default_values(module, params) + assert message is None or message in str(e) + if expected is not None: + assert result == expected