feat: Updates from testing, add upgrade guide

Author: bryantbiggs

README.md

@@ -72,12 +72,6 @@ module "ec2_instance" {
 }
 ```
 
-## Module wrappers
-
-Users of this Terraform module can create multiple similar resources by using [`for_each` meta-argument within `module` block](https://www.terraform.io/language/meta-arguments/for_each) which became available in Terraform 0.13.
-
-Users of Terragrunt can achieve similar results by using modules provided in the [wrappers](https://github.com/terraform-aws-modules/terraform-aws-ec2-instance/tree/master/wrappers) directory, if they prefer to reduce amount of configuration files.
-
 ## Examples
 
 - [Complete EC2 instance](https://github.com/terraform-aws-modules/terraform-aws-ec2-instance/tree/master/examples/complete)
@@ -87,7 +81,7 @@ Users of Terragrunt can achieve similar results by using modules provided in the
 
 This module does not support encrypted AMI's out of the box however it is easy enough for you to generate one for use
 
-This example creates an encrypted image from the latest ubuntu 16.04 base image.
+This example creates an encrypted image from the latest ubuntu 20.04 base image.
 
 ```hcl
 provider "aws" {
@@ -135,8 +129,6 @@ data "aws_ami" "encrypted-ami" {
 
 The following combinations are supported to conditionally create resources:
 
-- Disable resource creation (no resources created):
-
 ```hcl
 module "ec2_instance" {
   source  = "terraform-aws-modules/ec2-instance/aws"
@@ -188,6 +180,7 @@ No modules.
 | Name | Type |
 |------|------|
 | [aws_ebs_volume.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ebs_volume) | resource |
+| [aws_ec2_tag.spot_instance](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ec2_tag) | resource |
 | [aws_eip.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/eip) | resource |
 | [aws_iam_instance_profile.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_instance_profile) | resource |
 | [aws_iam_role.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
@@ -262,16 +255,17 @@ No modules.
 | <a name="input_private_ip"></a> [private\_ip](#input\_private\_ip) | Private IP address to associate with the instance in a VPC | `string` | `null` | no |
 | <a name="input_putin_khuylo"></a> [putin\_khuylo](#input\_putin\_khuylo) | Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Putin_khuylo! | `bool` | `true` | no |
 | <a name="input_region"></a> [region](#input\_region) | Region where the resource(s) will be managed. Defaults to the Region set in the provider configuration | `string` | `null` | no |
-| <a name="input_root_block_device"></a> [root\_block\_device](#input\_root\_block\_device) | Customize details about the root block device of the instance. See Block Devices below for details | <pre>map(object({<br/>    delete_on_termination = optional(bool)<br/>    encrypted             = optional(bool)<br/>    iops                  = optional(number)<br/>    kms_key_id            = optional(string)<br/>    tags                  = optional(map(string), {})<br/>    throughput            = optional(number)<br/>    size                  = optional(number)<br/>    type                  = optional(string)<br/>  }))</pre> | `null` | no |
+| <a name="input_root_block_device"></a> [root\_block\_device](#input\_root\_block\_device) | Customize details about the root block device of the instance. See Block Devices below for details | <pre>object({<br/>    delete_on_termination = optional(bool)<br/>    encrypted             = optional(bool)<br/>    iops                  = optional(number)<br/>    kms_key_id            = optional(string)<br/>    tags                  = optional(map(string), {})<br/>    throughput            = optional(number)<br/>    size                  = optional(number)<br/>    type                  = optional(string)<br/>  })</pre> | `null` | no |
 | <a name="input_secondary_private_ips"></a> [secondary\_private\_ips](#input\_secondary\_private\_ips) | A list of secondary private IPv4 addresses to assign to the instance's primary network interface (eth0) in a VPC. Can only be assigned to the primary network interface (eth0) attached at instance creation, not a pre-existing network interface i.e. referenced in a `network_interface block` | `list(string)` | `null` | no |
 | <a name="input_security_group_description"></a> [security\_group\_description](#input\_security\_group\_description) | Description of the security group | `string` | `null` | no |
-| <a name="input_security_group_egress_rules"></a> [security\_group\_egress\_rules](#input\_security\_group\_egress\_rules) | Egress rules to add to the security group | <pre>map(object({<br/>    cidr_ipv4                    = optional(string)<br/>    cidr_ipv6                    = optional(string)<br/>    description                  = optional(string)<br/>    from_port                    = optional(number)<br/>    ip_protocol                  = optional(string)<br/>    prefix_list_id               = optional(string)<br/>    referenced_security_group_id = optional(string)<br/>    tags                         = optional(map(string), {})<br/>    to_port                      = optional(number)<br/>  }))</pre> | <pre>{<br/>  "ipv4_default": {<br/>    "cidr_ipv4": "0.0.0.0/0",<br/>    "description": "Allow all IPv4 traffic",<br/>    "ip_protocol": "-1"<br/>  },<br/>  "ipv6_default": {<br/>    "cidr_ipv6": "::/0",<br/>    "description": "Allow all IPv6 traffic",<br/>    "ip_protocol": "-1"<br/>  }<br/>}</pre> | no |
-| <a name="input_security_group_ingress_rules"></a> [security\_group\_ingress\_rules](#input\_security\_group\_ingress\_rules) | Egress rules to add to the security group | <pre>map(object({<br/>    cidr_ipv4                    = optional(string)<br/>    cidr_ipv6                    = optional(string)<br/>    description                  = optional(string)<br/>    from_port                    = optional(number)<br/>    ip_protocol                  = optional(string)<br/>    prefix_list_id               = optional(string)<br/>    referenced_security_group_id = optional(string)<br/>    tags                         = optional(map(string), {})<br/>    to_port                      = optional(number)<br/>  }))</pre> | `null` | no |
+| <a name="input_security_group_egress_rules"></a> [security\_group\_egress\_rules](#input\_security\_group\_egress\_rules) | Egress rules to add to the security group | <pre>map(object({<br/>    cidr_ipv4                    = optional(string)<br/>    cidr_ipv6                    = optional(string)<br/>    description                  = optional(string)<br/>    from_port                    = optional(number)<br/>    ip_protocol                  = optional(string, "tcp")<br/>    prefix_list_id               = optional(string)<br/>    referenced_security_group_id = optional(string)<br/>    tags                         = optional(map(string), {})<br/>    to_port                      = optional(number)<br/>  }))</pre> | <pre>{<br/>  "ipv4_default": {<br/>    "cidr_ipv4": "0.0.0.0/0",<br/>    "description": "Allow all IPv4 traffic",<br/>    "ip_protocol": "-1"<br/>  },<br/>  "ipv6_default": {<br/>    "cidr_ipv6": "::/0",<br/>    "description": "Allow all IPv6 traffic",<br/>    "ip_protocol": "-1"<br/>  }<br/>}</pre> | no |
+| <a name="input_security_group_ingress_rules"></a> [security\_group\_ingress\_rules](#input\_security\_group\_ingress\_rules) | Egress rules to add to the security group | <pre>map(object({<br/>    cidr_ipv4                    = optional(string)<br/>    cidr_ipv6                    = optional(string)<br/>    description                  = optional(string)<br/>    from_port                    = optional(number)<br/>    ip_protocol                  = optional(string, "tcp")<br/>    prefix_list_id               = optional(string)<br/>    referenced_security_group_id = optional(string)<br/>    tags                         = optional(map(string), {})<br/>    to_port                      = optional(number)<br/>  }))</pre> | `null` | no |
 | <a name="input_security_group_name"></a> [security\_group\_name](#input\_security\_group\_name) | Name to use on security group created | `string` | `null` | no |
 | <a name="input_security_group_tags"></a> [security\_group\_tags](#input\_security\_group\_tags) | A map of additional tags to add to the security group created | `map(string)` | `{}` | no |
 | <a name="input_security_group_use_name_prefix"></a> [security\_group\_use\_name\_prefix](#input\_security\_group\_use\_name\_prefix) | Determines whether the security group name (`security_group_name` or `name`) is used as a prefix | `bool` | `true` | no |
 | <a name="input_security_group_vpc_id"></a> [security\_group\_vpc\_id](#input\_security\_group\_vpc\_id) | VPC ID to create the security group in. If not set, the security group will be created in the default VPC | `string` | `null` | no |
 | <a name="input_source_dest_check"></a> [source\_dest\_check](#input\_source\_dest\_check) | Controls if traffic is routed to the instance when the destination address does not match the instance. Used for NAT or VPNs | `bool` | `null` | no |
+| <a name="input_spot_instance_interruption_behavior"></a> [spot\_instance\_interruption\_behavior](#input\_spot\_instance\_interruption\_behavior) | Indicates Spot instance behavior when it is interrupted. Valid values are `terminate`, `stop`, or `hibernate` | `string` | `null` | no |
 | <a name="input_spot_launch_group"></a> [spot\_launch\_group](#input\_spot\_launch\_group) | A launch group is a group of spot instances that launch together and terminate together. If left empty instances are launched and terminated individually | `string` | `null` | no |
 | <a name="input_spot_price"></a> [spot\_price](#input\_spot\_price) | The maximum price to request on the spot market. Defaults to on-demand price | `string` | `null` | no |
 | <a name="input_spot_type"></a> [spot\_type](#input\_spot\_type) | If set to one-time, after the instance is terminated, the spot request will be closed. Default `persistent` | `string` | `null` | no |

UPGRADE-6.0.md

@@ -0,0 +1,183 @@
+# Upgrade from v5.x to v6.x
+
+If you have any questions regarding this upgrade process, please consult the `examples` directory:
+
+- [Complete](https://github.com/terraform-aws-modules/terraform-aws-ec2-instance/tree/master/examples/complete)
+
+If you find a bug, please open an issue with supporting configuration to reproduce.
+
+## List of backwards incompatible changes
+
+- Terraform v1.10.0 is now minimum supported version
+- AWS provider v6.0.0 is now minimum supported version
+- The default value for `ami_ssm_parameter` was changed from `"/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2"` to `"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64"`. AL2 is approaching end of life.
+
+## Additional changes
+
+### Added
+
+- Support for creating a security group within the module; this is now the default behavior and can be disabled by setting `create_security_group = false`.
+- Support for `region` parameter to specify the AWS region for the resources created if different from the provider region.
+- Support for tagging spot instances
+
+### Modified
+
+- Variable definitions now contain detailed `object` types in place of the previously used `any` type.
+- Inline `ebs_block_device` argument has been removed in favor of `ebs_volumes` which is a map of EBS volumes created through `aws_ebs_volume` and `aws_ebs_volume_attachment` resources. This provides the same API as before, but allows for more flexibility without generating diffs when adding or removing EBS volumes as well as unintended changes to the volumes.
+- Correct tag precedence ordering (least specific to most specific)
+
+### Removed
+
+- The `volume-attachment` example  has been removed since the module has been updated to use the corrected form of EBS volume creation and attachment (tl;dr - example is no longer useful).
+
+### Variable and output changes
+
+1. Removed variables:
+
+   - `cpu_core_count` - removed from provider `v6.x`
+   - `cpu_threads_per_core` - removed from provider `v6.x`
+
+2. Renamed variables:
+
+   - `ebs_block_device` -> `ebs_volumes`
+
+3. Added variables:
+
+   - `region`
+   - `enable_primary_ipv6`
+   - `host_resource_group_arn`
+   - `instance_market_options`
+   - `placement_partition_number`
+   - `create_security_group`
+   - `security_group_name`
+   - `security_group_use_name_prefix`
+   - `security_group_description`
+   - `security_group_vpc_id`
+   - `security_group_tags`
+   - `security_group_egress_rules`
+   - `security_group_ingress_rules`
+
+4. Removed outputs:
+
+   - None
+
+5. Renamed outputs:
+
+   - None
+
+6. Added outputs:
+
+   - `ebs_volumes`
+
+## Upgrade State Migrations
+
+### Before 5.x Example
+
+```hcl
+module "ec2_upgrade" {
+  source  = "terraform-aws-modules/ec2-instance/aws"
+  version = "5.8.0"
+
+  # Truncated for brevity, only relevant module API changes are shown ...
+
+  root_block_device = [
+    {
+      encrypted   = true
+      volume_size = 50
+      volume_type = "gp3"
+      throughput  = 200
+      tags = {
+        Name = "my-root-block"
+      }
+    },
+  ]
+
+  ebs_block_device = [
+    {
+      device_name = "/dev/sdf"
+      encrypted   = true
+      volume_size = 5
+      volume_type = "gp3"
+      throughput  = 200
+      tags = {
+        MountPoint = "/mnt/data"
+      }
+    }
+  ]
+
+  network_interface = [
+    {
+      device_index          = 0
+      network_interface_id  = aws_network_interface.this.id
+      delete_on_termination = false
+    }
+  ]
+
+  tags = local.tags
+}
+```
+
+### After 6.x Example
+
+```hcl
+module "ec2_upgrade" {
+  source  = "terraform-aws-modules/ec2-instance/aws"
+  version = "6.0.0"
+
+  # Truncated for brevity, only relevant module API changes are shown ...
+
+  # There can only be one root block device, so the wrapping list is removed
+  root_block_device = {
+    encrypted   = true
+    size        = 50 # Was `volume_size`
+    type        = "gp3" # Was `volume_type`
+    throughput  = 200
+    tags = {
+      Name = "my-root-block"
+    }
+  }
+
+  # Now a map of EBS volumes is used instead of a list
+  ebs_volumes = {
+    # The device_name can be the key of the map, or set by `device_name` attribute
+    "/dev/sdf" = {
+      encrypted  = true
+      size       = 5 # Was `volume_size`
+      type       = "gp3" # Was `volume_type`, `gp3` is now the default
+      throughput = 200
+      tags = {
+        MountPoint = "/mnt/data"
+      }
+    }
+  }
+
+  # Now a map of network interfaces is used instead of a list
+  network_interface = {
+    # The device_index can be the key of the map, or set by `device_index` attribute
+    0 = {
+      network_interface_id  = aws_network_interface.this.id
+      delete_on_termination = false
+    }
+  }
+
+  tags = local.tags
+}
+```
+
+To migrate from the `v5.x` version to `v6.x` version example shown above, the following state move commands can be performed to maintain the current resources without modification:
+
+> [!NOTE]
+> State move commands should only be required on instances that have additional EBS volumes attached to them.
+
+```bash
+terraform state rm 'module.ec2_complete.aws_instance.this[0]'
+terraform import 'module.ec2_complete.aws_instance.this[0]' <INSTANCE_ID>
+
+# Do the following for each additional EBS volume attached to the instance
+terraform import 'module.ec2_complete.aws_ebs_volume.this["/dev/sdf"]' <VOLUME_ID>
+terraform import 'module.ec2_complete.aws_volume_attachment.this["/dev/sdf"]' <DEVICE_NAME>:<VOLUME_ID>:<INSTANCE_ID>
+```
+
+> [!TIP]
+> If you encounter a situation where Terraform wants to recreate the instance due to user data changes, you can set the `user_data_replace_on_change` variable to `false` to prevent this behavior.
+> This is related to https://github.com/hashicorp/terraform-provider-aws/issues/5011

examples/complete/README.md

@@ -33,7 +33,6 @@ Note that this example may create resources which can cost money. Run `terraform
 | Name | Source | Version |
 |------|--------|---------|
 | <a name="module_ec2_complete"></a> [ec2\_complete](#module\_ec2\_complete) | ../../ | n/a |
-| <a name="module_ec2_cpu_options"></a> [ec2\_cpu\_options](#module\_ec2\_cpu\_options) | ../../ | n/a |
 | <a name="module_ec2_disabled"></a> [ec2\_disabled](#module\_ec2\_disabled) | ../../ | n/a |
 | <a name="module_ec2_ignore_ami_changes"></a> [ec2\_ignore\_ami\_changes](#module\_ec2\_ignore\_ami\_changes) | ../../ | n/a |
 | <a name="module_ec2_metadata_options"></a> [ec2\_metadata\_options](#module\_ec2\_metadata\_options) | ../../ | n/a |