X EC2 (or 1 ASG X:X); X external volumes; X network interfaces; KMS key for volumes; Key pair
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Guillaume Donval b5a08670fa
doc: fixes variables descriptions
2 days ago
examples fix: makes sure suffixes for volumes works in multiple instances context 2 days ago
.gitignore tech: updates .gitignore 1 month ago
.pre-commit-config.yaml test: fixes availability zones for one example 1 month ago
CHANGELOG.md doc: updates CHANGELOG 2 days ago
Jenkinsfile refactor: fixes style 1 month ago
LICENSE fix: output KMS key ID when it is created by the module 3 weeks ago
README.md doc: fixes variables descriptions 2 days ago
data.tf fix: do not create extra EIP nor extra network interface is ASG is selected 4 weeks ago
main.tf fix: makes sure suffixes for volumes works in multiple instances context 2 days ago
outputs.tf fix: removes the compact in KMS key output 3 weeks ago
variables.tf doc: fixes variables descriptions 2 days ago
versions.tf fix: fix AutoScaling group creation with latest AWS provider 2 weeks ago


Terraform module: Virtual Machine (EC2, AutoScaling Group)

This module have the following features, they are all optional:

  • X EC2 instances or one AutoScaling Group with X capacity.
  • X extra volumes attached to each instances, encrypted by default, with optional KMS key (only for EC2).
  • X extra network interfaces attached to each instances (only for EC2).
  • A Key Pair shared with all instances.
  • Elastic IPS for each instances and/or for specific extra network interfaces (only for EC2).

This module creates the same kind of instances. They share the same features. To create different instances, calls this module multiple times.


To install pre-commit hooks: pre-commit install. It will automatically validate, fmt and update README.md for you.

The variable root_block_device_delete_on_termination set to false is not tested because it will create resources that will persist a terraform build. Therefore untill we find a more permanent solution for this we do NOT test this feature.


  • AWS does not handle external volumes with AutoScaling Groups. Because of this, if an AutoScaling Group with one or more EBS volume is destroy, the EBS volumes would be preserved, resulting in phantom volumes (unseen by Terraform). That’s why every extra volumes within an AutoScaling group will always be destroyed by using this module (delete_on_termination = true).
  • Same kind of resources will share the same tags. It’s not possible to assign tag to a specific instance, as specific volume or a specific network interface.


Name Version
terraform >= 0.12
aws ~> 2.54
null ~>v2.1


Name Version
aws ~> 2.54
null ~>v2.1


Name Description Type Default Required
ami The AMI to use for the instances or the launch template. string "" no
associate_public_ip_address Associate a public ip address for each instances (or launch template) main network interface. bool false no
autoscaling_group_default_cooldown The amount of time, in seconds, after a scaling activity completes before another scaling activity can start. number null no
autoscaling_group_enabled_metrics A list of metrics to collect. The allowed values are GroupDesiredCapacity, GroupInServiceCapacity, GroupPendingCapacity, GroupMinSize, GroupMaxSize, GroupInServiceInstances, GroupPendingInstances, GroupStandbyInstances, GroupStandbyCapacity, GroupTerminatingCapacity, GroupTerminatingInstances, GroupTotalCapacity, GroupTotalInstances. set(string) null no
autoscaling_group_health_check_grace_period Time (in seconds) after instance comes into service before checking health. number null no
autoscaling_group_health_check_type ‘EC2’ or ‘ELB’. Controls how health checking is done. string null no
autoscaling_group_max_instance_lifetime The maximum amount of time, in seconds, that an instance can be in service, values must be either equal to 0 or between 604800 and 31536000 seconds. number null no
autoscaling_group_max_size The maximum size of the auto scale group. number 1 no
autoscaling_group_metrics_granularity The granularity to associate with the metrics to collect. The only valid value is 1Minute. Default is 1Minute. string null no
autoscaling_group_min_elb_capacity Setting this causes Terraform to wait for this number of instances from this autoscaling group to show up healthy in the ELB only on creation. Updates will not wait on ELB instance number changes. number null no
autoscaling_group_min_size The minimum size of the auto scale group. number 1 no
autoscaling_group_name The name of the auto scaling group. By default generated by Terraform. string null no
autoscaling_group_suspended_processes A list of processes to suspend for the AutoScaling Group. The allowed values are Launch, Terminate, HealthCheck, ReplaceUnhealthy, AZRebalance, AlarmNotification, ScheduledActions, AddToLoadBalancer. Note that if you suspend either the Launch or Terminate process types, it can prevent your autoscaling group from functioning properly. set(string) null no
autoscaling_group_tags Tags specific to the AutoScaling Group. Will be merged with var.tags. map {} no
autoscaling_group_target_group_arns A list of aws_alb_target_group ARNs, for use with Application or Network Load Balancing. list(string) [] no
autoscaling_group_termination_policies A list of policies to decide how the instances in the auto scale group should be terminated. The allowed values are OldestInstance, NewestInstance, OldestLaunchConfiguration, ClosestToNextInstanceHour, OldestLaunchTemplate, AllocationStrategy, Default. list(string) null no
autoscaling_group_wait_for_capacity_timeout A maximum duration that Terraform should wait for ASG instances to be healthy before timing out. (See also Waiting for Capacity below.) Setting this to ‘0’ causes Terraform to skip all Capacity Waiting behavior. string null no
autoscaling_group_wait_for_elb_capacity Setting this will cause Terraform to wait for exactly this number of healthy instances from this autoscaling group in all attached load balancers on both create and update operations. (Takes precedence over min_elb_capacity behavior.) number null no
cpu_core_count Sets the number of CPU cores for an instance (or launch template). This option is only supported on creation of instance type that support CPU Options CPU Cores and Threads Per CPU Core Per Instance Type - specifying this option for unsupported instance types will return an error from the EC2 API. number null no
cpu_credits The credit option for CPU usage. Can be ‘standard’ or ‘unlimited’. T3 instances are launched as unlimited by default. T2 instances are launched as standard by default. string null no
cpu_threads_per_core (has no effect unless cpu_core_count is also set) If set to to 1, hyperthreading is disabled on the launched instance (or launch template). Defaults to 2 if not set. See Optimizing CPU Options for more information. number null no
disable_api_termination If true, enables EC2 Instance (or launch template) Termination Protection. bool false no
ebs_optimized If true, the launched EC2 instance (or launch template) will be EBS-optimized. Note that if this is not set on an instance type that is optimized by default then this will show as disabled but if the instance type is optimized by default then there is no need to set this and there is no effect to disabling it. bool false no
ec2_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
ec2_private_ips Private IPs of the instances. If set, the list must contain as many IP as the number of var.instance_count. list(string) null no
ec2_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 true no
ec2_volume_name Tag name of the root block device of the instance. string "root-volume" no
ec2_volume_tags Tags of the root volume of the instance. Will be merged with tags. map {} no
eip_create Whether or not to create an public elastic IP per instance. bool false no
ephemeral_block_devices Customize Ephemeral (also known as Instance Store) volumes on the instance (or launch template):
* device_name (required, string): The name of the block device to mount on the instance.
* virtual_name (optional, string): The Instance Store Device Name (e.g. “ephemeral0”).
* no_device (optional, string): Suppresses the specified device included in the AMI's block device mapping.
list [] no
external_volume_count Number of external volumes to create. number 0 no
external_volume_device_names Device names for the external volumes. list(string)
external_volume_name Prefix of the external volumes to create. string "extra-volumes" no
external_volume_num_suffix_offset The starting point of the numerical suffix for external volumes. Will combine with var.num_suffix_offset. An offset of 1 here and num_suffix_offset of 2 would mean external volumes resources suffix starts at 4. number 1 no
external_volume_sizes Size of the external volumes. list(number)
external_volume_tags Tags for the external volumes. Will be merged with tags. Tags will be shared among all external volumes. map {} no
external_volume_types The type of EBS volume. Can be ‘standard’, ‘gp2’, ‘io1’, ‘sc1’ or ‘st1’ (Default: ‘gp2’). list(string)
extra_network_interface_count How many extra network interface to create per instance. This has no influence on the default network interface. number 0 no
extra_network_interface_eips_count How many extra network interfaces will have a public elastic IP. Should be the exact number of “true” in the var.extra_network_interface_eips_enabled list. number 0 no
extra_network_interface_eips_enabled Respectively, for each instance, a list of boolean that indicates whether or not the extra network interface should have an elastic IP or not. Should have as many “true” as var.extra_network_interface_eips_count. list(bool) [] no
extra_network_interface_private_ips List of private IPs to assign to the extra ENIs. Make sure you have as many element in the list as ENIs times the number of instances. list(list(string))
extra_network_interface_private_ips_counts Number of secondary private IPs to assign to the ENI. The total number of private IPs will be 1 + private_ips_count, as a primary private IP will be assiged to an ENI by default. Make sure you have as many element in the list as ENIs times the number of instances. list(number)
extra_network_interface_security_group_count How many security groups to attach per extra ENI. This cannot be computed automatically from var.extra_network_interface_security_group_ids in terraform 0.12. number 0 no
extra_network_interface_security_group_ids List of security group IDs to assign to the extra ENIs. All ENIs will have the same security groups. list(list(string)) null no
extra_network_interface_source_dest_checks Whether to enable source destination checking for the extra ENIs. Default true. list(bool)
extra_network_interface_tags Tags for the extra ENIs. Will be merged with tags. Tags will be shared among all extra ENIs. map {} no
host_id The Id of a dedicated host that the instance will be assigned to. Use when an instance (or launch template) is to be launched on a specific dedicated host. string null no
iam_instance_profile_create Whether or not to create an instance profile for the virtual machines. bool true no
iam_instance_profile_external_name Name of an instance profile to be used by the virtual machines. If this value is given, this will be used instead of creating a new instance profile. string null no
iam_instance_profile_iam_role_description The description of the instance profile role. string "Instance profile role" no
iam_instance_profile_iam_role_name The name of the instance profile role. If omitted, Terraform will assign a random, unique name. string null no
iam_instance_profile_iam_role_policy_arns The ARNs of the policies you want to apply to the instance profile role. list(string) [] no
iam_instance_profile_iam_role_policy_count How many policy ARNs there are in var.instance_profile_iam_role_policy_arns. This value cannot be computed automatically in Terraform 0.12. number 0 no
iam_instance_profile_iam_role_tags Tags to be used for the instance profile role. Will be merged with var.tags. map {} no
iam_instance_profile_name The profile's name. If omitted, Terraform will assign a random, unique name. string null no
iam_instance_profile_path Path in which to create the profile. Instance profile role will share the same path. string "/" no
instance_count Number of instances to create. For AutoScaling Group, this value will be the desired capacity. Setting this value to 0 will disable the module. number 1 no
instance_initiated_shutdown_behavior Shutdown behavior for the instance (or launch template). Amazon defaults this to stop for EBS-backed instances and terminate for instance-store instances. Cannot be set on instance-store instances. string null no
instance_tags Tags specific to the instances (or launch template). map {} no
instance_type The type of instance (or launch template) to start. Updates to this field will trigger a stop/start of the EC2 instance though this is not true with launch template. string "t3.small" no
ipv6_address_count A number of IPv6 addresses to associate with the primary network interface of the instances or launch templlate. Amazon EC2 chooses the IPv6 addresses from the range of your subnet. number 0 no
key_pair_create Whether or not to create a key pair. bool false no
key_pair_name The name for the key pair. If this is not null and key_pair_create = false, this name will be used as a key pair. string null no
key_pair_public_key The public key material. string null no
key_pair_tags Tags for the key pair. Will be merged with tags. map {} no
launch_template_ipv4_address_count The number of secondary private IPv4 addresses to assign to a network interface. Conflicts with ipv4_addresses. number 0 no
launch_template_name The name of the launch template. If you leave this blank, Terraform will auto-generate a unique name. string "" no
launch_template_tags Tags to be used by the launch template. Will be merge with var.tags. map {} no
monitoring If true, the launched EC2 instances (or launch template) will have detailed monitoring enabled. bool false no
name Name prefix of the instances themselves (tag Name) whether or not ASG is used. Will be suffixed by a var.num_suffix_digits count index. string "" no
num_suffix_digits Number of significant digits to append to all resources of the module. number 2 no
num_suffix_offset The starting point of the numerical suffix. An offset of 1 would mean resources suffix starts at 2. number 0 no
placement_group The Placement Group to start the instances (or launch template) in. string null no
root_block_device_delete_on_termination Whether or not to delete the root block device on termination. **Note: It's is strongly discouraged to set this to false, only change this value if you have no other choice as this will leave a volume that will not be managed by terraform (even if the tag says it does) and you may end up building up costs.** bool true no
root_block_device_encrypted Customize details about the root block device of the instance or launch template root volume: Enables EBS encryption on the volume (Default: true). Cannot be used with snapshot_id. Must be configured to perform drift detection. string true no
root_block_device_iops The amount of provisioned IOPS. This must be set with a volume_type of ‘io1’. string null no
root_block_device_volume_size Customize details about the root block device of the instance or launch template root volume: The size of the volume in gibibytes (GiB). string null no
root_block_device_volume_type Customize details about the root block device of the instance or launch template root volume: The type of volume. Can be ‘standard’, ‘gp2’, or ‘io1’. (Default: ‘gp2’). string null no
subnet_id Subnet ID where to provision all the instances (or launch template). Can be used instead or along with var.subnet_ids. string "" no
subnet_ids Subnet IDs where to provision the instances (or launch template). Can be used instead or along with var.subnet_id. list(string)
subnet_ids_count How many subnet IDs in subnet_ids. Cannot be computed automatically from other variables in Terraform 0.12.X. number 0 no
tags Tags to be used for all this module resources. Will be merged with specific tags. map {} no
tenancy The tenancy of the instance (if the instance or launch template will be running in a VPC). An instance with a tenancy of dedicated runs on single-tenant hardware. The host tenancy is not supported for the import-instance command. string "default" no
use_autoscaling_group Weither or not to create an AutoScaling Group instead of EC2 instances. bool false no
use_num_suffix Always append numerical suffix to instance name, even if instance_count is 1. bool false no
user_data The user data to provide when launching the instance (or launch template). string null no
volume_kms_key_alias Alias of the KMS key used to encrypt the volumes. string "alias/default/ec2" no
volume_kms_key_arn KMS key used to encrypt the volumes. To be used when var.volume_kms_key_create is set to false. string null no
volume_kms_key_create Whether or not to create a KMS key to be used for volumes encryption. bool false no
volume_kms_key_customer_master_key_spec Specifies whether the key contains a symmetric key or an asymmetric key pair and the encryption algorithms or signing algorithms that the key supports for the KMS key to be used for volumes. Valid values: SYMMETRIC_DEFAULT, RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, or ECC_SECG_P256K1. Defaults to SYMMETRIC_DEFAULT. string null no
volume_kms_key_name Name prefix for the KMS key to be used for volumes. Will be suffixes with a two-digit count index. string null no
volume_kms_key_policy A valid policy JSON document for the KMS key to be used for volumes. string null no
volume_kms_key_tags Tags for the KMS key to be used for volumes. Will be merge with var.tags. map {} no
vpc_security_group_ids An object containing the list of security group IDs to associate with each instance (or launch template). list(list(string)) null no


Name Description
autoscaling_group_arn n/a
autoscaling_group_id n/a
availability_zones n/a
ec2_arns n/a
ec2_ids n/a
ec2_primary_network_interface_ids n/a
ec2_private_dns n/a
ec2_private_ips n/a
ec2_public_dns n/a
ec2_public_ips n/a
eip_ids n/a
eip_network_interfaces n/a
eip_private_dns n/a
eip_private_ips n/a
eip_public_dns n/a
eip_public_ips n/a
external_volume_arns n/a
external_volume_ids n/a
extra_network_interface_ids n/a
extra_network_interface_mac_addresses n/a
extra_network_interface_private_ips n/a
extra_network_interface_public_ips n/a
iam_instance_profile_arn n/a
iam_instance_profile_iam_role_arn n/a
iam_instance_profile_iam_role_id n/a
iam_instance_profile_iam_role_unique_id n/a
iam_instance_profile_id n/a
iam_instance_profile_unique_id n/a
key_pair_fingerprint n/a
key_pair_id n/a
key_pair_name n/a
kms_key_id n/a
launch_template_arn n/a
launch_template_default_version n/a
launch_template_id n/a
launch_template_latest_version n/a
subnet_ids n/a