AWS EC2 Instance Terraform module

March 26, 2026 · View on GitHub

Terraform module which creates an EC2 instance on AWS.

Usage

Single EC2 Instance

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

  name = "single-instance"

  instance_type = "t3.micro"
  key_name      = "user1"
  monitoring    = true
  subnet_id     = "subnet-eddcdzz4"

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

Multiple EC2 Instance

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

  for_each = toset(["one", "two", "three"])

  name = "instance-${each.key}"

  instance_type = "t3.micro"
  key_name      = "user1"
  monitoring    = true
  subnet_id     = "subnet-eddcdzz4"

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

Spot EC2 Instance

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

  name = "spot-instance"

  create_spot_instance = true
  spot_price           = "0.60"
  spot_type            = "persistent"

  instance_type = "t3.micro"
  key_name      = "user1"
  monitoring    = true
  subnet_id     = "subnet-eddcdzz4"

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

Examples

Make an encrypted AMI for use

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 20.04 base image.

provider "aws" {
  region = "us-west-2"
}

data "aws_ami" "ubuntu" {
  most_recent = true
  owners      = ["679593333241"]

  filter {
    name   = "name"
    values = ["ubuntu-minimal/images/hvm-ssd/ubuntu-focal-20.04-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }
}

resource "aws_ami_copy" "ubuntu_encrypted_ami" {
  name              = "ubuntu-encrypted-ami"
  description       = "An encrypted root ami based off ${data.aws_ami.ubuntu.id}"
  source_ami_id     = data.aws_ami.ubuntu.id
  source_ami_region = "eu-west-2"
  encrypted         = true

  tags = { Name = "ubuntu-encrypted-ami" }
}

data "aws_ami" "encrypted-ami" {
  most_recent = true

  filter {
    name   = "name"
    values = [aws_ami_copy.ubuntu_encrypted_ami.id]
  }

  owners = ["self"]
}

Conditional creation

The following combinations are supported to conditionally create resources:

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

  # Disable creation of EC2 and all resources
  create = false

  # Enable creation of spot instance
  create_spot_instance = true

  # Enable creation of EC2 IAM instance profile
  create_iam_instance_profile = true

  # Disable creation of security group
  create_security_group = false

  # Enable creation of elastic IP
  create_eip = true

  # ... omitted
}

Notes

network_interface can't be specified together with vpc_security_group_ids, associate_public_ip_address, subnet_id. See complete example for details.
In regards to spot instances, you must grant the AWSServiceRoleForEC2Spot service-linked role access to any custom KMS keys, otherwise your spot request and instances will fail with bad parameters. You can see more details about why the request failed by using the awscli and aws ec2 describe-spot-instance-requests

Requirements

Name	Version
terraform	>= 1.5.7
aws	>= 6.37

Providers

Name	Version
aws	>= 6.37

Modules

No modules.

Resources

Name	Type
aws_ebs_volume.this	resource
aws_ec2_tag.spot_instance	resource
aws_eip.this	resource
aws_iam_instance_profile.this	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.this	resource
aws_instance.ignore_ami	resource
aws_instance.this	resource
aws_security_group.this	resource
aws_spot_instance_request.this	resource
aws_volume_attachment.this	resource
aws_vpc_security_group_egress_rule.this	resource
aws_vpc_security_group_ingress_rule.this	resource
aws_iam_policy_document.assume_role_policy	data source
aws_partition.current	data source
aws_ssm_parameter.this	data source
aws_subnet.this	data source

Inputs

Name	Description	Type	Default	Required
ami	ID of AMI to use for the instance	`string`	`null`	no
ami_ssm_parameter	SSM parameter name for the AMI ID. For Amazon Linux AMI SSM parameters see reference	`string`	`"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64"`	no
associate_public_ip_address	Whether to associate a public IP address with an instance in a VPC	`bool`	`null`	no
availability_zone	AZ to start the instance in	`string`	`null`	no
capacity_reservation_specification	Describes an instance's Capacity Reservation targeting option	object({ capacity_reservation_preference = optional(string) capacity_reservation_target = optional(object({ capacity_reservation_id = optional(string) capacity_reservation_resource_group_arn = optional(string) })) })	`null`	no
cpu_credits	The credit option for CPU usage (unlimited or standard)	`string`	`null`	no
cpu_options	Defines CPU options to apply to the instance at launch time.	object({ amd_sev_snp = optional(string) core_count = optional(number) nested_virtualization = optional(string) threads_per_core = optional(number) })	`null`	no
create	Whether to create an instance	`bool`	`true`	no
create_eip	Determines whether a public EIP will be created and associated with the instance.	`bool`	`false`	no
create_iam_instance_profile	Determines whether an IAM instance profile is created or to use an existing IAM instance profile	`bool`	`false`	no
create_security_group	Determines whether a security group will be created	`bool`	`true`	no
create_spot_instance	Depicts if the instance is a spot instance	`bool`	`false`	no
disable_api_stop	If true, enables EC2 Instance Stop Protection	`bool`	`null`	no
disable_api_termination	If true, enables EC2 Instance Termination Protection	`bool`	`null`	no
ebs_optimized	If true, the launched EC2 instance will be EBS-optimized	`bool`	`null`	no
ebs_volumes	Additional EBS volumes to attach to the instance	map(object({ encrypted = optional(bool) final_snapshot = optional(bool) iops = optional(number) kms_key_id = optional(string) multi_attach_enabled = optional(bool) outpost_arn = optional(string) size = optional(number) snapshot_id = optional(string) tags = optional(map(string), {}) throughput = optional(number) type = optional(string, "gp3") volume_initialization_rate = optional(number) # Attachment device_name = optional(string) # Will fall back to use map key as device name force_detach = optional(bool) skip_destroy = optional(bool) stop_instance_before_detaching = optional(bool) }))	`null`	no
eip_domain	Indicates if this EIP is for use in VPC	`string`	`"vpc"`	no
eip_tags	A map of additional tags to add to the eip	`map(string)`	`{}`	no
enable_primary_ipv6	Whether to assign a primary IPv6 Global Unicast Address (GUA) to the instance when launched in a dual-stack or IPv6-only subnet	`bool`	`null`	no
enable_volume_tags	Whether to enable volume tags (if enabled it conflicts with root_block_device tags)	`bool`	`true`	no
enclave_options_enabled	Whether Nitro Enclaves will be enabled on the instance. Defaults to `false`	`bool`	`null`	no
ephemeral_block_device	Customize Ephemeral (also known as Instance Store) volumes on the instance	map(object({ device_name = string no_device = optional(bool) virtual_name = optional(string) }))	`null`	no
force_destroy	Destroys instance even if `disable_api_termination` or `disable_api_stop` is set to true. Once this parameter is set to true, a successful terraform apply run before a destroy is required to update this value in the resource state. Without a successful terraform apply after this parameter is set, this flag will have no effect. If setting this field in the same operation that would require replacing the instance or destroying the instance, this flag will not work. Additionally when importing an instance, a successful terraform apply is required to set this value in state before it will take effect on a destroy operation.	`bool`	`null`	no
get_password_data	If true, wait for password data to become available and retrieve it	`bool`	`null`	no
hibernation	If true, the launched EC2 instance will support hibernation	`bool`	`null`	no
host_id	ID of a dedicated host that the instance will be assigned to. Use when an instance is to be launched on a specific dedicated host	`string`	`null`	no
host_resource_group_arn	ARN of the host resource group in which to launch the instances. If you specify an ARN, omit the `tenancy` parameter or set it to `host`	`string`	`null`	no
iam_instance_profile	IAM Instance Profile to launch the instance with. Specified as the name of the Instance Profile	`string`	`null`	no
iam_role_description	Description of the role	`string`	`null`	no
iam_role_name	Name to use on IAM role created	`string`	`null`	no
iam_role_path	IAM role path	`string`	`null`	no
iam_role_permissions_boundary	ARN of the policy that is used to set the permissions boundary for the IAM role	`string`	`null`	no
iam_role_policies	Policies attached to the IAM role	`map(string)`	`{}`	no
iam_role_tags	A map of additional tags to add to the IAM role/profile created	`map(string)`	`{}`	no
iam_role_use_name_prefix	Determines whether the IAM role name (`iam_role_name` or `name`) is used as a prefix	`bool`	`true`	no
ignore_ami_changes	Whether changes to the AMI ID changes should be ignored by Terraform. Note - changing this value will result in the replacement of the instance	`bool`	`false`	no
instance_initiated_shutdown_behavior	Shutdown behavior for the instance. Amazon defaults this to stop for EBS-backed instances and terminate for instance-store instances. Cannot be set on instance-store instance	`string`	`null`	no
instance_market_options	The market (purchasing) option for the instance. If set, overrides the `create_spot_instance` variable	object({ market_type = optional(string) spot_options = optional(object({ instance_interruption_behavior = optional(string) max_price = optional(string) spot_instance_type = optional(string) valid_until = optional(string) })) })	`null`	no
instance_tags	Additional tags for the instance	`map(string)`	`{}`	no
instance_type	The type of instance to start	`string`	`"t3.micro"`	no
ipv6_address_count	A number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet	`number`	`null`	no
ipv6_addresses	Specify one or more IPv6 addresses from the range of the subnet to associate with the primary network interface	`list(string)`	`null`	no
key_name	Key name of the Key Pair to use for the instance; which can be managed using the `aws_key_pair` resource	`string`	`null`	no
launch_template	Specifies a Launch Template to configure the instance. Parameters configured on this resource will override the corresponding parameters in the Launch Template	object({ id = optional(string) name = optional(string) version = optional(string) })	`null`	no
maintenance_options	The maintenance options for the instance	object({ auto_recovery = optional(string) })	`null`	no
metadata_options	Customize the metadata options of the instance	object({ http_endpoint = optional(string, "enabled") http_protocol_ipv6 = optional(string) http_put_response_hop_limit = optional(number, 1) http_tokens = optional(string, "required") instance_metadata_tags = optional(string) })	{ "http_endpoint": "enabled", "http_put_response_hop_limit": 1, "http_tokens": "required" }	no
monitoring	If true, the launched EC2 instance will have detailed monitoring enabled	`bool`	`null`	no
name	Name to be used on EC2 instance created	`string`	`""`	no
network_interface	Customize network interfaces to be attached at instance boot time	map(object({ delete_on_termination = optional(bool) device_index = optional(number) # Will fall back to use map key as device index network_card_index = optional(number) network_interface_id = string }))	`null`	no
placement_group	The Placement Group to start the instance in	`string`	`null`	no
placement_group_id	Placement Group ID to start the instance in	`string`	`null`	no
placement_partition_number	Number of the partition the instance is in. Valid only if the `aws_placement_group` resource's `strategy` argument is set to `partition`	`number`	`null`	no
private_dns_name_options	Customize the private DNS name options of the instance	object({ enable_resource_name_dns_a_record = optional(bool) enable_resource_name_dns_aaaa_record = optional(bool) hostname_type = optional(string) })	`null`	no
private_ip	Private IP address to associate with the instance in a VPC	`string`	`null`	no
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
region	Region where the resource(s) will be managed. Defaults to the Region set in the provider configuration	`string`	`null`	no
root_block_device	Customize details about the root block device of the instance. See Block Devices below for details	object({ delete_on_termination = optional(bool) encrypted = optional(bool) iops = optional(number) kms_key_id = optional(string) tags = optional(map(string)) throughput = optional(number) size = optional(number) type = optional(string) })	`null`	no
secondary_network_interface	Customize secondary network interfaces to be attached to the EC2 instance	map(object({ delete_on_termination = optional(bool) device_index = optional(number) # Will fall back to use map key as device index interface_type = optional(string) network_card_index = number private_ip_address_count = optional(number) private_ip_addresses = optional(list(string)) secondary_subnet_id = string }))	`null`	no
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
security_group_description	Description of the security group	`string`	`null`	no
security_group_egress_rules	Egress rules to add to the security group	map(object({ cidr_ipv4 = optional(string) cidr_ipv6 = optional(string) description = optional(string) from_port = optional(number) ip_protocol = optional(string, "tcp") prefix_list_id = optional(string) referenced_security_group_id = optional(string) tags = optional(map(string), {}) to_port = optional(number) }))	{ "ipv4_default": { "cidr_ipv4": "0.0.0.0/0", "description": "Allow all IPv4 traffic", "ip_protocol": "-1" }, "ipv6_default": { "cidr_ipv6": "::/0", "description": "Allow all IPv6 traffic", "ip_protocol": "-1" } }	no
security_group_ingress_rules	Ingress rules to add to the security group	map(object({ cidr_ipv4 = optional(string) cidr_ipv6 = optional(string) description = optional(string) from_port = optional(number) ip_protocol = optional(string, "tcp") prefix_list_id = optional(string) referenced_security_group_id = optional(string) tags = optional(map(string), {}) to_port = optional(number) }))	`null`	no
security_group_name	Name to use on security group created	`string`	`null`	no
security_group_tags	A map of additional tags to add to the security group created	`map(string)`	`{}`	no
security_group_use_name_prefix	Determines whether the security group name (`security_group_name` or `name`) is used as a prefix	`bool`	`true`	no
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
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
spot_instance_interruption_behavior	Indicates Spot instance behavior when it is interrupted. Valid values are `terminate`, `stop`, or `hibernate`	`string`	`null`	no
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
spot_price	The maximum price to request on the spot market. Defaults to on-demand price	`string`	`null`	no
spot_type	If set to one-time, after the instance is terminated, the spot request will be closed. Default `persistent`	`string`	`null`	no
spot_valid_from	The start date and time of the request, in UTC RFC3339 format(for example, YYYY-MM-DDTHH:MM:SSZ)	`string`	`null`	no
spot_valid_until	The end date and time of the request, in UTC RFC3339 format(for example, YYYY-MM-DDTHH:MM:SSZ)	`string`	`null`	no
spot_wait_for_fulfillment	If set, Terraform will wait for the Spot Request to be fulfilled, and will throw an error if the timeout of 10m is reached	`bool`	`null`	no
subnet_id	The VPC Subnet ID to launch in	`string`	`null`	no
tags	A mapping of tags to assign to the resource	`map(string)`	`{}`	no
tenancy	The tenancy of the instance (if the instance is running in a VPC). Available values: default, dedicated, host	`string`	`null`	no
timeouts	Define maximum timeout for creating, updating, and deleting EC2 instance resources	object({ create = optional(string) update = optional(string) delete = optional(string) })	`null`	no
user_data	The user data to provide when launching the instance. Do not pass gzip-compressed data via this argument; see user_data_base64 instead	`string`	`null`	no
user_data_base64	Can be used instead of user_data to pass base64-encoded binary data directly. Use this instead of user_data whenever the value is not a valid UTF-8 string. For example, gzip-encoded user data must be base64-encoded and passed via this argument to avoid corruption	`string`	`null`	no
user_data_replace_on_change	When used in combination with user_data or user_data_base64 will trigger a destroy and recreate when set to true. Defaults to false if not set	`bool`	`null`	no
volume_tags	A mapping of tags to assign to the devices created by the instance at launch time	`map(string)`	`{}`	no
vpc_security_group_ids	A list of security group IDs to associate with	`list(string)`	`[]`	no

Outputs

Name	Description
ami	AMI ID that was used to create the instance
arn	The ARN of the instance
availability_zone	The availability zone of the created instance
capacity_reservation_specification	Capacity reservation specification of the instance
ebs_block_device	EBS block device information
ebs_volumes	Map of EBS volumes created and their attributes
ephemeral_block_device	Ephemeral block device information
iam_instance_profile_arn	ARN assigned by AWS to the instance profile
iam_instance_profile_id	Instance profile's ID
iam_instance_profile_unique	Stable and unique string identifying the IAM instance profile
iam_role_arn	The Amazon Resource Name (ARN) specifying the IAM role
iam_role_name	The name of the IAM role
iam_role_unique_id	Stable and unique string identifying the IAM role
id	The ID of the instance
instance_state	The state of the instance
ipv6_addresses	The IPv6 address assigned to the instance, if applicable
outpost_arn	The ARN of the Outpost the instance is assigned to
password_data	Base-64 encoded encrypted password data for the instance. Useful for getting the administrator password for instances running Microsoft Windows. This attribute is only exported if `get_password_data` is true
primary_network_interface_id	The ID of the instance's primary network interface
private_dns	The private DNS name assigned to the instance. Can only be used inside the Amazon EC2, and only available if you've enabled DNS hostnames for your VPC
private_ip	The private IP address assigned to the instance
public_dns	The public DNS name assigned to the instance. For EC2-VPC, this is only available if you've enabled DNS hostnames for your VPC
public_ip	The public IP address assigned to the instance, if applicable.
root_block_device	Root block device information
security_group_arn	Amazon Resource Name (ARN) of the security group
security_group_id	ID of the security group
spot_bid_status	The current bid status of the Spot Instance Request
spot_instance_id	The Instance ID (if any) that is currently fulfilling the Spot Instance request
spot_request_state	The current request state of the Spot Instance Request
tags_all	A map of tags assigned to the resource, including those inherited from the provider default_tags configuration block

Authors

Module is maintained by Anton Babenko with help from these awesome contributors.

License

Apache 2 Licensed. See LICENSE for full details.

Additional information for users from Russia and Belarus

Russia has illegally annexed Crimea in 2014 and brought the war in Donbas followed by full-scale invasion of Ukraine in 2022.
Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
Putin khuylo!