terraform-aws-modules/terraform-aws-ec2-instance

The wrappers sub-module implements a single module wrapper pattern. This allows you to manage multiple instances of the EC2 module within a single configuration block. This is particularly useful in environments like Terragrunt where native Terraform for_each might not be feasible for managing multiple resource copies without duplicating configuration files.

Note that this wrapper does not add any new functionality; it simply iterates over a map of items using the arguments provided by the root module.

In v6.x, the root_block_device configuration has changed from a list to a single object, as an instance can only have one root block device.

Configuration Changes

• Data Structure: Change from a list(object) to a single object.
• Attribute Names:
  • volume_size is now size.
  • volume_type is now type.

# v6.x Root Block Device Configuration
root_block_device = {
  encrypted   = true
  size        = 50
  type        = "gp3"
  throughput  = 200
  tags = {
    Name = "my-root-block"
  }
}

When configuring the module, be aware of the following constraints:

• Network Interface Conflict: You cannot specify network_interface at the same time as vpc_security_group_ids, associate_public_ip_address, or subnet_id.
• Spot Instance KMS Permissions: As noted in the Spot EC2 section, ensure AWSServiceRoleForEC2Spot has access to custom KMS keys to avoid bad parameters errors.

In v6.x, the module has moved from a list-based EBS configuration to a map-based configuration using ebs_volumes. This change allows for more flexible management of EBS volumes via aws_ebs_volume and aws_volume_attachment resources without causing unintended diffs.

Configuration Changes

• Variable Name: Rename ebs_block_device to ebs_volumes.
• Data Structure: Change from a list(object) to a map(object).
• Attribute Names:
  • volume_size is now size.
  • volume_type is now type.
• Keys: The map key can be the device_name (e.g., "/dev/sdf"), or you can specify the device_name attribute within the object.

# v6.x EBS Volume Configuration
ebs_volumes = {
  "/dev/sdf" = {
    encrypted  = true
    size       = 5
    type       = "gp3"
    throughput = 200
    tags = {
      MountPoint = "/mnt/data"
    }
  }
}

To use the wrapper with Terragrunt, define the source in the terraform block and provide configuration via the inputs block. You must provide two main maps:

1. defaults: A map of arguments that will be applied to every instance.
2. items: A map where each key represents a unique instance and the value is a map of arguments specific to that instance. Any argument supported by the base EC2 instance module can be used here.

terraform {
  source = "tfr:///terraform-aws-modules/ec2-instance/aws//wrappers"
}

inputs = {
  defaults = {
    create = true
    tags = {
      Terraform   = "true"
      Environment = "dev"
    }
  }

  items = {
    my-item = {
      # any argument supported by the module
    }
    my-second-item = {
      # any argument supported by the module
    }
  }
}

When upgrading the terraform-aws-modules/ec2-instance/aws module from version 5.x to 6.x, note the following breaking changes and requirements:

Requirements

• Terraform version: Minimum v1.10.0 required.
• AWS provider version: Minimum v6.0.0 required.

Breaking Changes

• AMI Default: The ami_ssm_parameter default changed from Amazon Linux 2 (/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2) to Amazon Linux 2023 (/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64).
• EBS Configuration: The ebs_block_device list has been removed and replaced by the ebs_volumes map.
• Variable Types: Variable definitions now use detailed object types instead of any.
• Removed Variables: cpu_core_count and cpu_threads_per_core are no longer supported.

To use the wrapper directly in Terraform, call it as a module and pass the defaults and items maps. The items map keys will define the unique identifiers for each instance created by the wrapper.

module "wrapper" {
  source = "terraform-aws-modules/ec2-instance/aws//wrappers"

  defaults = {
    create = true
    tags = {
      Terraform   = "true"
      Environment = "dev"
    }
  }

  items = {
    my-item = {
      # any argument supported by the module
    }
    my-second-item = {
      # any argument supported by the module
    }
  }
}

Once the infrastructure is deployed, you can connect to the private EC2 instance using the AWS CLI.

1. Install the Plugin: You must have the Session Manager plugin for the AWS CLI installed on your local machine.
2. Retrieve the Command: The Terraform output ssm_connect_command provides the exact command needed for your specific instance and region.
3. Execute: The command follows this format:

   aws ssm start-session --target <INSTANCE-ID> --region <REGION>

To deploy the complete EC2 instance configuration, which demonstrates various arguments such as Elastic IPs, network interfaces, and credit specifications, execute the standard Terraform workflow.

Warning: This example creates real AWS resources that may incur costs. Ensure you run terraform destroy to clean up resources when finished.

$ terraform init
$ terraform plan
$ terraform apply

This configuration creates an EC2 instance that is not connected to the Internet. Instead, it provides private network access using AWS Systems Manager (SSM) Session Manager through VPC Endpoints. This setup allows for secure management of instances without requiring public IP addresses or internet gateways.

Requirements

• Terraform: >= 1.5.7
• AWS Provider: >= 6.37

Deployment Steps

1. Initialize the working directory:

   terraform init

2. Review the execution plan:

   terraform plan

3. Apply the configuration:

   terraform apply

WARNING

This example creates resources that may incur costs. Run terraform destroy to clean up resources when they are no longer needed.

$ terraform init
$ terraform plan
$ terraform apply