Minor update on module_utils/ec2 + add mew module ec2_launch_template…

…_info

changelogs/fragments/20241002-module_utils-ec2-add-shared-code.yml

@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - Move function ``determine_iam_role`` from module ``ec2_instance`` to module_utils/ec2 so that it can be used by ``community.aws.ec2_launch_template`` module (https://github.com/ansible-collections/amazon.aws/pull/2319).
+  - module_utils/ec2 - add some shared code for Launch template AWS API calls (https://github.com/ansible-collections/amazon.aws/pull/2319).

meta/runtime.yml

@@ -43,6 +43,7 @@ action_groups:
     - ec2_instance_info
     - ec2_key
     - ec2_key_info
+    - ec2_launch_template_info
     - ec2_security_group
     - ec2_security_group_info
     - ec2_snapshot

plugins/doc_fragments/tags.py

@@ -11,19 +11,19 @@ class ModuleDocFragment:
   tags:
     description:
       - A dictionary representing the tags to be applied to the resource.
-      - If the I(tags) parameter is not set then tags will not be modified.
+      - If the O(tags) parameter is not set then tags will not be modified.
     type: dict
     required: false
     aliases: ['resource_tags']
   purge_tags:
     description:
-      - If I(purge_tags=true) and I(tags) is set, 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, even
-        if I(purge_tags=True).
-      - Tag keys beginning with C(aws:) are reserved by Amazon and can not be
+      - If O(purge_tags=true) and O(tags) is set, 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, even
+        if O(purge_tags=True).
+      - Tag keys beginning with V(aws:) are reserved by Amazon and can not be
         modified.  As such they will be ignored for the purposes of the
-        I(purge_tags) parameter.  See the Amazon documentation for more information
+        O(purge_tags) parameter.  See the Amazon documentation for more information
         U(https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions).
     type: bool
     default: true

plugins/module_utils/ec2.py

@@ -58,6 +58,7 @@
 
 # Used to live here, moved into ansible_collections.amazon.aws.plugins.module_utils.arn
 from .arn import is_outpost_arn as is_outposts_arn  # pylint: disable=unused-import
+from .arn import validate_aws_arn
 
 # Used to live here, moved into ansible_collections.amazon.aws.plugins.module_utils.botocore
 from .botocore import HAS_BOTO3  # pylint: disable=unused-import
@@ -1110,7 +1111,6 @@ def authorize_security_group_egress(client, **params: Dict[str, Any]) -> bool:
 
 # EC2 Egress only internet Gateway
 class EC2EgressOnlyInternetGatewayErrorHandler(AWSErrorHandler):
-    _CUSTOM_EXCEPTION = AnsibleEC2Error
 
     @classmethod
     def _is_missing(cls):
@@ -1241,6 +1241,99 @@ def replace_network_acl_association(client, network_acl_id: str, association_id:
     ]
 
 
+# EC2 Launch template
+class EC2LaunchTemplateErrorHandler(AWSErrorHandler):
+    _CUSTOM_EXCEPTION = AnsibleEC2Error
+
+    @classmethod
+    def _is_missing(cls):
+        return is_boto3_error_code(["InvalidLaunchTemplateName.NotFoundException", "InvalidLaunchTemplateId.NotFound"])
+
+
+@EC2LaunchTemplateErrorHandler.list_error_handler("describe launch templates", [])
+@AWSRetry.jittered_backoff()
+def describe_launch_templates(
+    client,
+    launch_template_ids: Optional[List[str]] = None,
+    launch_template_names: Optional[List[str]] = None,
+    filters: Optional[List[Dict[str, List[str]]]] = None,
+) -> List[Dict[str, Any]]:
+    params = {}
+    if launch_template_ids:
+        params["LaunchTemplateIds"] = launch_template_ids
+    if launch_template_names:
+        params["LaunchTemplateNames"] = launch_template_names
+    if filters:
+        params["Filters"] = filters
+    paginator = client.get_paginator("describe_launch_templates")
+    return paginator.paginate(**params).build_full_result()["LaunchTemplates"]
+
+
+@EC2LaunchTemplateErrorHandler.common_error_handler("describe launch template versions")
+@AWSRetry.jittered_backoff()
+def describe_launch_template_versions(client, **params: Dict[str, Any]) -> List[Dict[str, Any]]:
+    paginator = client.get_paginator("describe_launch_template_versions")
+    return paginator.paginate(**params).build_full_result()["LaunchTemplateVersions"]
+
+
+@EC2LaunchTemplateErrorHandler.common_error_handler("delete launch template versions")
+@AWSRetry.jittered_backoff()
+def delete_launch_template_versions(
+    client, versions: List[str], launch_template_id: Optional[str] = None, launch_template_name: Optional[str] = None
+) -> Dict[str, Any]:
+    params = {"Versions": versions}
+    if launch_template_id:
+        params["LaunchTemplateId"] = launch_template_id
+    if launch_template_name:
+        params["LaunchTemplateName"] = launch_template_name
+    return client.delete_launch_template_versions(**params)
+
+
+@EC2LaunchTemplateErrorHandler.common_error_handler("delete launch template")
+@AWSRetry.jittered_backoff()
+def delete_launch_template(
+    client, launch_template_id: Optional[str] = None, launch_template_name: Optional[str] = None
+) -> Dict[str, Any]:
+    params = {}
+    if launch_template_id:
+        params["LaunchTemplateId"] = launch_template_id
+    if launch_template_name:
+        params["LaunchTemplateName"] = launch_template_name
+    return client.delete_launch_template(**params)["LaunchTemplate"]
+
+
+@EC2LaunchTemplateErrorHandler.common_error_handler("create launch template")
+@AWSRetry.jittered_backoff()
+def create_launch_template(
+    client,
+    launch_template_name: str,
+    launch_template_data: Dict[str, Any],
+    tags: Optional[EC2TagSpecifications] = None,
+    **kwargs: Dict[str, Any],
+) -> Dict[str, Any]:
+    params = {"LaunchTemplateName": launch_template_name, "LaunchTemplateData": launch_template_data}
+    if tags:
+        params["TagSpecifications"] = boto3_tag_specifications(tags, types="launch-template")
+    params.update(kwargs)
+    return client.create_launch_template(**params)["LaunchTemplate"]
+
+
+@EC2LaunchTemplateErrorHandler.common_error_handler("create launch template version")
+@AWSRetry.jittered_backoff()
+def create_launch_template_version(
+    client, launch_template_data: Dict[str, Any], **params: Dict[str, Any]
+) -> Dict[str, Any]:
+    return client.create_launch_template_version(LaunchTemplateData=launch_template_data, **params)[
+        "LaunchTemplateVersion"
+    ]
+
+
+@EC2LaunchTemplateErrorHandler.common_error_handler("modify launch template")
+@AWSRetry.jittered_backoff()
+def modify_launch_template(client, **params: Dict[str, Any]) -> Dict[str, Any]:
+    return client.modify_launch_template(**params)["LaunchTemplate"]
+
+
 def get_ec2_security_group_ids_from_names(sec_group_list, ec2_connection, vpc_id=None, boto3=None):
     """Return list of security group IDs from security group names. Note that security group names are not unique
     across VPCs.  If a name exists across multiple VPCs and no VPC ID is supplied, all matching IDs will be returned. This
@@ -1462,3 +1555,21 @@ def normalize_ec2_vpc_dhcp_config(option_config: List[Dict[str, Any]]) -> Dict[s
                 config_data[option] = [val["Value"] for val in config_item["Values"]]
 
     return config_data
+
+
+def determine_iam_arn_from_name(module, name_or_arn: str) -> str:
+    if validate_aws_arn(name_or_arn, service="iam", resource_type="instance-profile"):
+        return name_or_arn
+    iam = module.client("iam", retry_decorator=AWSRetry.jittered_backoff())
+    try:
+        return iam.get_instance_profile(InstanceProfileName=name_or_arn, aws_retry=True)["InstanceProfile"]["Arn"]
+    except is_boto3_error_code("NoSuchEntity") as e:
+        module.fail_json_aws(e, msg=f"Could not find IAM instance profile {name_or_arn}")
+    except (
+        botocore.exceptions.ClientError,
+        botocore.exceptions.BotoCoreError,
+    ) as e:  # pylint: disable=duplicate-except
+        module.fail_json_aws(
+            e,
+            msg=f"An error occurred while searching for IAM instance profile {name_or_arn}. Please try supplying the full ARN.",
+        )

plugins/modules/ec2_instance.py

@@ -1338,8 +1338,6 @@
 from ansible.module_utils.common.dict_transformations import snake_dict_to_camel_dict
 from ansible.module_utils.six import string_types
 
-from ansible_collections.amazon.aws.plugins.module_utils.arn import validate_aws_arn
-from ansible_collections.amazon.aws.plugins.module_utils.botocore import is_boto3_error_code
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import AnsibleEC2Error
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import associate_iam_instance_profile
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import attach_network_interface
@@ -1349,6 +1347,7 @@
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import describe_instances
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import describe_subnets
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import describe_vpcs
+from ansible_collections.amazon.aws.plugins.module_utils.ec2 import determine_iam_arn_from_name
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import ensure_ec2_tags
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import get_ec2_security_group_ids_from_names
 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import modify_instance_attribute
@@ -1396,7 +1395,7 @@ def add_or_update_instance_profile(
             # great, the profile we asked for is what's there
             return False
         else:
-            desired_arn = determine_iam_role(module, desired_profile_name)
+            desired_arn = determine_iam_arn_from_name(module, desired_profile_name)
             if instance_profile_setting.get("Arn") == desired_arn:
                 return False
 
@@ -1412,7 +1411,7 @@ def add_or_update_instance_profile(
             replace_iam_instance_profile_association(
                 client,
                 association_id=association[0]["AssociationId"],
-                iam_instance_profile={"Arn": determine_iam_role(module, desired_profile_name)},
+                iam_instance_profile={"Arn": determine_iam_arn_from_name(module, desired_profile_name)},
             )
             return True
         except AnsibleEC2Error as e:
@@ -1423,7 +1422,7 @@ def add_or_update_instance_profile(
         try:
             associate_iam_instance_profile(
                 client,
-                iam_instance_profile={"Arn": determine_iam_role(module, desired_profile_name)},
+                iam_instance_profile={"Arn": determine_iam_arn_from_name(module, desired_profile_name)},
                 instance_id=instance["InstanceId"],
             )
             return True
@@ -1806,7 +1805,7 @@ def build_run_instance_spec(client, module: AnsibleAWSModule, current_count: int
 
     # IAM profile
     if params.get("iam_instance_profile"):
-        spec["IamInstanceProfile"] = dict(Arn=determine_iam_role(module, params.get("iam_instance_profile")))
+        spec["IamInstanceProfile"] = dict(Arn=determine_iam_arn_from_name(module, params.get("iam_instance_profile")))
 
     if params.get("instance_type"):
         spec["InstanceType"] = params["instance_type"]
@@ -2310,25 +2309,6 @@ def pretty_instance(i):
     return instance
 
 
-def determine_iam_role(module: AnsibleAWSModule, name_or_arn: Optional[str]) -> str:
-    if validate_aws_arn(name_or_arn, service="iam", resource_type="instance-profile"):
-        return name_or_arn
-    iam = module.client("iam", retry_decorator=AWSRetry.jittered_backoff())
-    try:
-        role = iam.get_instance_profile(InstanceProfileName=name_or_arn, aws_retry=True)
-        return role["InstanceProfile"]["Arn"]
-    except is_boto3_error_code("NoSuchEntity") as e:
-        module.fail_json_aws(e, msg=f"Could not find iam_instance_profile {name_or_arn}")
-    except (
-        botocore.exceptions.ClientError,
-        botocore.exceptions.BotoCoreError,
-    ) as e:  # pylint: disable=duplicate-except
-        module.fail_json_aws(
-            e,
-            msg=f"An error occurred while searching for iam_instance_profile {name_or_arn}. Please try supplying the full ARN.",
-        )
-
-
 def modify_instance_type(
     client,
     module: AnsibleAWSModule,