Updates to ec2_instance_create_delete role

Author: hakbailey

roles/ec2_instance_create_delete/README.md

@@ -2,108 +2,84 @@
 
 A role to create an EC2 instance in AWS.
 
-Users can specify various parameters for instance configuration, including instance type, AMI ID, key pair, tags, and VPC/subnet configuration.
-
-This role also supports the creation of optional networking resources, such as an external security group and an Elastic IP (EIP). You can choose to wait for the EC2 instance to finish booting before continuing.
+Users can specify various parameters for instance configuration, including instance type, AMI ID, key pair, tags, VPC/subnet configuration, and whether to associate an EIP. You can choose to wait for the EC2 instance to finish booting before continuing.
+
+This role can be combined with the [cloud.aws_ops.ec2_networking_resources role](../ec2_networking_resources/README.md) to create networking resources for the instance, see [examples](#examples).
+
+## Requirements
+
+An AWS account with the following permissions:
+
+* ec2:AllocateAddress
+* ec2:AssociateAddress
+* ec2:CreateKeyPair
+* ec2:DeleteKeyPair
+* ec2:DescribeAddresses
+* ec2:DescribeInstanceAttribute
+* ec2:DescribeInstances
+* ec2:DescribeInstanceStatus
+* ec2:DescribeKeyPairs
+* ec2:DescribeSecurityGroups
+* ec2:DescribeSubnets
+* ec2:DescribeVpcs
+* ec2:DisassociateAddress
+* ec2:ModifyInstanceAttribute
+* ec2:ReleaseAddress
+* ec2:RunInstances
+* ec2:TerminateInstances
 
 ## Role Variables
 
 The following variables can be set in the role to customize EC2 instance creation and networking configurations:
 
-### Role Operation
-
 * **ec2_instance_create_delete_operation**: (Optional)
-  - Goal state for the instances.
-  - "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 are [present, terminated, running, started, stopped, restarted, rebooted, absent]
-  Default is `present`.
-
-### EC2 Instance Configuration
-
-* **ec2_instance_create_delete_aws_region**: (Required)
-  The AWS region in which to create the EC2 instance.
+  Target operation for the ec2 instance role. Choices are ["create", "delete"]. Defaults to "create".
 
 * **ec2_instance_create_delete_instance_name**: (Required)
   The name of the EC2 instance to be created.
 
-* **ec2_instance_create_delete_instance_type**: (Required)
-  The instance type for the EC2 instance (e.g., `t2.micro`, `m5.large`).
+* **ec2_instance_create_delete_instance_type**: (Optional)
+  The instance type for the EC2 instance (e.g., `t2.micro`, `m5.large`). Required when `ec2_instance_create_delete_operation` is `true`
 
-* **ec2_instance_create_delete_ami_id**: (Required)
-  The AMI ID for the EC2 instance.
+* **ec2_instance_create_delete_ami_id**: (Optional)
+  The AMI ID for the EC2 instance. Required when `ec2_instance_create_delete_operation` is `true`
 
 * **ec2_instance_create_delete_key_name**: (Optional)
   The name of the key pair to use for SSH access to the EC2 instance.
   If the key does not exist, a key pair will be created with the name.
+  If not provided, instance will not be accessible via SSH.
 
 * **ec2_instance_create_delete_vpc_subnet_id**: (Optional)
   The ID of the VPC subnet in which the instance will be launched.
-  If not provided, instance might get created with `default` subnet in the AWS region if present.
+  If not provided, instance will be created in the default subnet for the default VPC in the AWS region if present.
 
 * **ec2_instance_create_delete_tags**: (Optional)
   A dictionary of tags to assign to the EC2 instance.
 
-* **ec2_instance_create_delete_wait_for_boot**: (Optional)
-  Whether to wait for the EC2 instance to be in the "running" or "terminated" state before continuing. Default is `true`.
-
-### Optional Networking Resources
-
-#### Elastic IP
+* **ec2_instance_create_delete_wait_for_state**: (Optional)
+  Whether to wait for the EC2 instance to be in the "running" (if creating an instance) or "terminated" (if deleting an instance) state before continuing. Default is `true`.
 
-* **ec2_instance_create_delete_vpc_id**: (Optional)
-  The ID of the VPC used for security group and internet gateway.
-  Required if `ec2_instance_create_delete_associate_igw` or `ec2_instance_create_delete_associate_eip` is `true`.
+* **ec2_instance_create_delete_associate_security_groups**: (Optional)
+  List of security group IDs to associate with the EC2 instance.
 
 * **ec2_instance_create_delete_associate_eip**: (Optional)
   Whether to create an Elastic IP (EIP) and associate it with the EC2 instance. Default is `false`.
-  If set to `true` and the provided VPC doesn't have an Internet Gateway (IGW) attached, set `ec2_instance_create_delete_associate_igw` to `true` to avoid failure.
+  If true, EC2 instance must be launched in a VPC with an Internet Gateway (IGW) attached, otherwise this will fail. Use [cloud.aws_ops.ec2_networking_resources role](../ec2_networking_resources/README.md) to create the necessary networking resources.
 
 * **ec2_instance_create_delete_eip_tags**: (Optional)
   Tags to assign to the elastic IP.
 
-#### Internet Gateway
-
-* **ec2_instance_create_delete_associate_igw**: (Optional)
-  Whether to create and associate an internet gateway with the EC2 instance. Default is `false`.
-  If set to `true`, an internet gateway will be created or associated with the instance.
-
-* **ec2_instance_create_delete_igw_tags**: (Optional)
-  Tags to assign to the internet gateway.
-
-#### External Security Group
+## Dependencies
 
-* **ec2_instance_create_delete_associate_external_sg**: (Optional)
-  Whether to create and associate an security group with the EC2 instance. Default is `false`.
-  If set to `true`, an security group will be created or associated with the instance.
+- role: [aws_setup_credentials](../aws_setup_credentials/README.md)
 
-* **ec2_instance_create_delete_external_sg_name**: (Required)
-  The name of the security group to use for the EC2 instance.
-  The role will check if an SG with this name exists. If not, it will create a new one.
-  Default is `ec2_instance_create-default-external-sg`.
+## Examples
 
-* **ec2_instance_create_delete_external_sg_description**: (Optional)
-  A description for the security group. Default is `Security group for external access`.
-
-* **ec2_instance_create_delete_external_sg_rules**: (Optional)
-  A list of custom rules to add to the security group. Each rule is a dictionary with `proto`, `ports`, and `cidr_ip` keys. Default is to allow SSH (port 22) from `0.0.0.0/0`.
-
-* **ec2_instance_create_delete_external_sg_tags**: (Optional)
-  Tags to assign to the security group.
-
-### Example:
-
-Here's an example of how to use the role in a playbook.
+Using the role on its own in a playbook:
 
 ```yaml
 ---
-- name: Playbook for creating EC2 instance using cloud.aws_ops.ec2_instance_create role
+- name: Create EC2 instance
   hosts: localhost
   gather_facts: false
   roles:
@@ -118,54 +94,59 @@ Here's an example of how to use the role in a playbook.
           ec2_instance_create_delete_tags:
             Component: my-test-instance
             Environment: Testing
-          ec2_instance_create_delete_wait_for_boot: true
-          ec2_instance_create_delete_vpc_id: vpc-xxxx
-          # Optionally, enable security group creation
-          ec2_instance_create_delete_associate_external_sg: true
-          ec2_instance_create_delete_external_sg_name: my-custom-sg
-          ec2_instance_create_delete_external_sg_description: Security group for my custom access
-          ec2_instance_create_delete_external_sg_rules:
-            - proto: tcp
-              ports: "80"
-              cidr_ip: "0.0.0.0/0"
-          ec2_instance_create_delete_external_sg_tags:
-            Component: my-custom-sg
-            Environment: Testing
-          # Optionally, enable Elastic IP association
-          ec2_instance_create_delete_associate_eip: true
-          ec2_instance_create_delete_eip_tags:
-            Component: my-custom-eip
-            Environment: Testing
-          # Optionally, enable Internet Gateway association
-          ec2_instance_create_delete_associate_igw: true
-          ec2_instance_create_delete_igw_tags:
-            Environment: Testing
-            Name: "{{ resource_prefix }}-igw"
+          ec2_instance_create_delete_wait_for_state: true
+```
+
+Combining the role with [cloud.aws_ops.ec2_networking_resources](../ec2_networking_resources/README.md):
 
+```yaml
 ---
-- name: Playbook for deleting EC2 instance and other role resources using cloud.aws_ops.ec2_instance_create role
+- name: Create EC2 networking resources and EC2 instance
   hosts: localhost
   gather_facts: false
   roles:
+    - role: cloud.aws_ops.ec2_networking_resources:
+      vars:
+        ec2_networking_resources_vpc_name: my-vpc
+        ec2_networking_resources_vpc_cidr_block: 10.0.0.0/24
+        ec2_networking_resources_subnet_cidr_block: 10.0.0.0/25
+        ec2_networking_resources_sg_internal_name: my-internal-sg
+        ec2_networking_resources_sg_external_name: my-external-sg
+        ec2_networking_resources_create_igw: true
     - role: cloud.aws_ops.ec2_instance_create
       vars:
-          ec2_instance_create_delete_operation: absent
-          ec2_instance_create_delete_aws_region: us-west-2
+        ec2_instance_create_delete_operation: present
+        ec2_instance_create_delete_instance_name: my-test-instance
+        ec2_instance_create_delete_instance_type: t2.micro
+        ec2_instance_create_delete_ami_id: ami-066a7fbaa12345678
+        ec2_instance_create_delete_vpc_subnet_id: "{{ ec2_networking_resources_subnet_result.subnet.id }}"
+        ec2_instance_create_delete_associate_security_groups:
+          - my-internal-sg
+          - my-external-sg
+        ec2_instance_create_delete_associate_eip: true
+```
+
+Deleting an EC2 instance:
+
+```yaml
+---
+- name: Delete EC2 instance
+  hosts: localhost
+  gather_facts: false
+  roles:
+    - role: cloud.aws_ops.ec2_instance_create_delete
+      vars:
+          ec2_instance_create_delete_operation: delete
           ec2_instance_create_delete_instance_name: my-test-instance
-          ec2_instance_create_delete_wait_for_boot: true
-          ec2_instance_create_delete_associate_external_sg: true
-          ec2_instance_create_delete_external_sg_name: my-custom-sg
-          ec2_instance_create_delete_associate_igw: true
-          ec2_instance_create_delete_vpc_id: vpc-xxxx
+          ec2_instance_create_delete_wait_for_state: true
+```
 
-License
--------
+## License
 
 GNU General Public License v3.0 or later
 
 See [LICENSE](../../LICENSE) to see the full text.
 
-Author Information
-------------------
+## Author Information
 
 - Ansible Cloud Content Team

roles/ec2_instance_create_delete/defaults/main.yml

@@ -1,12 +1,4 @@
 ---
-ec2_instance_create_delete_operation: present
+ec2_instance_create_delete_operation: create
+ec2_instance_create_delete_wait_for_state: true
 ec2_instance_create_delete_associate_eip: false
-ec2_instance_create_delete_associate_external_sg: false
-ec2_instance_create_delete_associate_igw: false
-ec2_instance_create_delete_external_sg_description: "Security group for external access"
-ec2_instance_create_delete_external_sg_name: "ec2_instance_create-default-external-sg"
-ec2_instance_create_delete_wait_for_boot: true
-ec2_instance_create_delete_external_sg_rules:
-  - proto: tcp
-    ports: "22"
-    cidr_ip: "0.0.0.0/0"

roles/ec2_instance_create_delete/meta/argument_specs.yml

@@ -4,8 +4,8 @@ argument_specs:
     short_description: A role to create an EC2 instance with optional networking resources.
     description:
       - A role to create an EC2 instance.
-      - Optionally can create a security group and associate an Elastic IP with the instance.
-      - Supports custom configurations for instance settings, including instance type, AMI, key pair, tags, VPC/subnet, and networking configurations.
+      - Can optionally attach security groups and associate an Elastic IP with the instance.
+      - Supports custom configurations for instance settings including instance type, AMI, key pair, tags, VPC/subnet, and networking configurations.
     options:
       ec2_instance_create_delete_operation:
         description:
@@ -14,101 +14,56 @@ argument_specs:
         type: str
         default: create
         choices: [create, delete]
-      ec2_instance_create_delete_aws_region:
-        description:
-          - The AWS region in which to create the EC2 instance.
-        required: true
-        type: str
       ec2_instance_create_delete_instance_name:
         description:
           - The name of the EC2 instance to be created.
         required: true
         type: str
       ec2_instance_create_delete_instance_type:
         description:
-          - The instance type for the EC2 instance.
-        required: true
+          - The instance type for the EC2 instance. Required when `ec2_instance_create_delete_operation` is `true`.
+        required: false
         type: str
       ec2_instance_create_delete_ami_id:
         description:
-          - The AMI ID for the EC2 instance.
-        required: true
+          - The AMI ID for the EC2 instance. Required when `ec2_instance_create_delete_operation` is `true`.
+        required: false
         type: str
       ec2_instance_create_delete_key_name:
         description:
-          - The name of the key pair to use for SSH access to the EC2 instance.
+          - The name of the key pair to use for SSH access to the EC2 instance. If the key does not exist, a key pair will be created with the name. If not provided, instance will not be accessible via SSH.
         required: false
         type: str
       ec2_instance_create_delete_vpc_subnet_id:
         description:
-          - The ID of the VPC subnet in which the instance will be launched.
+          - The ID of the VPC subnet in which the instance will be launched. If not provided, instance will be created in the default subnet for the default VPC in the AWS region, if present.
         required: false
         type: str
       ec2_instance_create_delete_tags:
         description:
           - A dictionary of tags to assign to the EC2 instance.
         required: false
         type: dict
-      ec2_instance_create_delete_wait_for_boot:
+      ec2_instance_create_delete_wait_for_state:
         description:
-          - Whether to wait for the EC2 instance to be in the running state before continuing.
+          - Whether to wait for the EC2 instance to be in the running/terminated state before continuing.
         required: false
         default: true
         type: bool
-      ec2_instance_create_delete_associate_eip:
-        description:
-          - Whether to create and associate an Elastic IP (EIP) with the EC2 instance.
-        required: false
-        default: false
-        type: bool
-      ec2_instance_create_delete_associate_external_sg:
-        description:
-          - Whether to associate an existing or a new security group for external access.
-        required: false
-        default: false
-        type: bool
-      ec2_instance_create_delete_external_sg_name:
-        description:
-          - The name of the security group to create.
-        required: false
-        default: "ec2_instance_create-default-external-sg"
-        type: str
-      ec2_instance_create_delete_external_sg_description:
-        description:
-          - A description of the security group.
-        required: false
-        default: "Security group for external access"
-        type: str
-      ec2_instance_create_delete_external_sg_tags:
+      ec2_instance_create_delete_associate_security_groups:
         description:
-          - Tags to assign to the security group.
+          - List of security group names or IDs to associate with the EC2 instance.
         required: false
-        type: dict
-      ec2_instance_create_delete_associate_igw:
+        type: list
+        elements: str
+      ec2_instance_create_delete_associate_eip:
         description:
-          - Whether to create and associate an internal gateway.
+          - Whether to create and associate an Elastic IP (EIP) with the EC2 instance.
         required: false
         default: false
         type: bool
-      ec2_instance_create_delete_vpc_id:
-        description:
-          - The ID of the VPC used for security group and internet gateway.
-          - This is required when `ec2_instance_create_delete_associate_external_sg` or `ec2_instance_create_delete_associate_igw` is `true`.
-        required: false
-        type: str
       ec2_instance_create_delete_eip_tags:
         description:
           - Tags to assign to the Elastic IP.
         required: false
         type: dict
-      ec2_instance_create_delete_external_sg_rules:
-        description:
-          - A list of dict containing custom rules to add to the security group. Each rule is a dictionary with `proto`, `ports`, and `cidr_ip` keys. Default is to allow SSH (port 22) from `0.0.0.0/0`.
-        required: false
-        type: list
-        elements: dict
-      ec2_instance_create_delete_igw_tags:
-        description:
-          - Tags to assign to the internet gateway.
-        required: false
-        type: dict