AWS CloudFormation
User Guide (API Version 2010-05-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

AWS::EC2::Instance

The AWS::EC2::Instance type creates an Amazon EC2 instance.

If an Elastic IP address is attached to your instance, AWS CloudFormation reattaches the Elastic IP address after it updates the instance. For more information about updating stacks, see AWS CloudFormation Stacks Updates.

Syntax

{
   "Type" : "AWS::EC2::Instance",
   "Properties" : {
      "AvailabilityZone" : String,
      "BlockDeviceMappings" : [ EC2 Block Device Mapping, ... ],
      "DisableApiTermination" : Boolean,
      "EbsOptimized" : Boolean,
      "IamInstanceProfile" : String,
      "ImageId" : String,
      "InstanceType" : String,
      "KernelId" : String,
      "KeyName" : String,
      "Monitoring" : Boolean,
      "NetworkInterfaces" : [ EC2 Network Interface, ... ],
      "PlacementGroupName" : String,
      "PrivateIpAddress" : String,
      "RamdiskId" : String,
      "SecurityGroupIds" : [ String, ... ],
      "SecurityGroups" : [ String, ... ],
      "SourceDestCheck" : Boolean,
      "SubnetId" : String,
      "Tags" : [ EC2 Tag, ... ],
      "Tenancy" : String,
      "UserData" : String,
      "Volumes" : [ EC2 MountPoint, ... ]
   }
}

Properties

AvailabilityZone

Specifies the name of the Availability Zone in which the instance is located.

For more information about AWS regions and Availability Zones, see Regions and Availability Zones in the Amazon EC2 User Guide.

Required: No. If not specified, an Availability Zone will be automatically chosen for you based on the load balancing criteria for the region.

Type: String

Update requires: Replacement

BlockDeviceMappings

Defines a set of Amazon Elastic Block Store block device mappings, ephemeral instance store block device mappings, or both. For more information, see Amazon Elastic Block Store or Amazon EC2 Instance Store in the Amazon Elastic Compute Cloud Developer Guide.

Required: No

Type: A list of Amazon EC2 Block Device Mapping Property.

Update requires: Replacement, with one exception: if only the DeleteOnTermination setting of the Amazon Elastic Block Store Block Device Property is changed, the EBS block device mapping can be updated without interruption.

DisableApiTermination

Specifies whether the instance can be terminated through the API (specify "true" or "false").

Required: No

Type: Boolean

Update requires: no interruption

EbsOptimized

Specifies whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal EBS I/O performance.

The following instance types can be launched as EBS optimized instances:

  • Large (m1.large)

  • Extra large (m1.xlarge)

  • High-memory quadruple extra large (m2.4xlarge)

Additional fees are incurred when using EBS-optimized instances. For more information, see EBS-Optimized Instances in the Amazon Elastic Compute Cloud User Guide.

Required: No. If this property is not specified, "false" is used.

Type: Boolean

Update requires: Replacement

IamInstanceProfile

The name or a reference to an AWS::IAM::InstanceProfile type.

For more information about IAM roles, see Working with Roles in the AWS Identity and Access Management User Guide.

Required: No

Type: String

ImageId

Provides the unique ID of the Amazon Machine Image (AMI) that was assigned during registration.

Required: Yes

Type: String

Update requires: Replacement

InstanceType

The instance type, such as "m1.xlarge". The default type is "m1.small". For a list of instance types, see Instance Families and Types.

Required: No

Type: String

Update requires:

KernelId

The kernel ID.

Required: No

Type: String

Update requires:

KeyName

Provides the name of the Amazon EC2 key pair.

Required: No

Type: String

Update requires: Replacement

Monitoring

Specifies whether monitoring is enabled for the instance.

Required: No

Type: Boolean

Update requires: no interruption

NetworkInterfaces

A list of NetworkInterface embedded objects that describe the network interfaces to associate with this instance.

Note

If this resource has a public IP address and is also in a VPC that is defined in the same template, you must use the DependsOn attribute to declare a dependency on the VPC-gateway attachment. For more information, see DependsOn Attribute.

Required: No

Type: A list of NetworkInterface objects.

Update requires: Replacement

PlacementGroupName

The name of an existing placement group that you want to launch the instance into (for cluster instances).

Required: No

Type: String

Update requires: Replacement

PrivateIpAddress

The private IP address for this instance.

Important

If you make an update to an instance that requires replacement, you must assign a new private IP address. During a replacement, AWS CloudFormation creates a new instance but doesn't delete the old instance until the stack has successfully updated. If the stack update fails, AWS CloudFormation uses the old instance in order to roll back the stack to the previous working state. The old and new instances cannot have the same private IP address.

If you're using Amazon VPC, you can optionally use this parameter to assign the instance a specific available IP address from the subnet (for example, 10.0.0.25). By default, Amazon VPC selects an IP address from the subnet for the instance.

Required: No

Type: String

Update requires: Replacement

RamdiskId

The ID of the RAM disk to select. Some kernels require additional drivers at launch. Check the kernel requirements for information about whether you need to specify a RAM disk. To find kernel requirements, refer to the AWS Resource Center and search for the kernel ID.

Required: No

Type: String

Update requires:

SecurityGroupIds

A list that contains the security group IDs for VPC security groups to assign to the Amazon EC2 instance. If you specified the NetworkInterfaces property, do not specify this property.

Required: Conditional. Required for VPC security groups.

Type: A list of strings

Update requires: no interruption

SecurityGroups

Valid only for Amazon EC2 security groups. A list that contains the Amazon EC2 security groups to assign to the Amazon EC2 instance. The list can contain both the name of existing Amazon EC2 security groups or references to AWS::EC2::SecurityGroup resources created in the template.

Required: No

Type: A list of strings

Update requires: Replacement.

SourceDestCheck

Controls whether source/destination checking is enabled on the instance. Also determines if an instance in a VPC will perform network address translation (NAT).

A value of "true" means that source/destination checking is enabled, and a value of "false" means that checking is disabled. For the instance to perform NAT, the value must be "false". For more information, see NAT Instances in the Amazon Virtual Private Cloud User Guide.

Required: No

Type: Boolean

Update requires: no interruption

SubnetId

If you're using Amazon VPC, this property specifies the ID of the subnet that you want to launch the instance into. If you specified the NetworkInterfaces property, do not specify this property.

Required: No

Type: String

Update requires: Replacement

Tags

The tags that you want to attach to the instance.

Required: No

Type: A list of EC2 Tags.

Update requires: no interruption

Tenancy

The tenancy of the instance that you want to launch. This value can be either "default" or "dedicated". An instance that has a tenancy value of "dedicated" runs on single-tenant hardware and can be launched only into a VPC. For more information, see Using EC2 Dedicated Instances Within Your VPC in the Amazon Virtual Private Cloud User Guide.

Required: No

Type: String

Update requires: Replacement

UserData

Base64-encoded MIME user data that is made available to the instances.

Required: No

Type: String

Update requires:

Volumes

The Amazon EBS volumes to attach to the instance.

Required: No

Type: A list of EC2 MountPoints.

Update requires: You must unmount the filesystem that you want to update.

Return Values

Ref

When you pass the logical ID of an AWS::EC2::Instance object to the intrinsic Ref function, the object's InstanceId is returned. For example: i-636be302.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. This section lists the available attributes and corresponding return values.

AvailabilityZone

The Availability Zone where the specified instance is launched. For example: us-east-1b.

You can retrieve a list of all Availability Zones for a region by using the Fn::GetAZs intrinsic function.

PrivateDnsName

The private DNS name of the specified instance. For example: ip-10-24-34-0.ec2.internal.

PublicDnsName

The public DNS name of the specified instance. For example: ec2-107-20-50-45.compute-1.amazonaws.com.

PrivateIp

The private IP address of the specified instance. For example: 10.24.34.0.

PublicIp

The public IP address of the specified instance. For example: 192.0.2.0.

For more information about using Fn:GetAtt, see Fn::GetAtt.

Examples

EC2 Instance with an EBS Block Device Mapping

{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Description" : "Ec2 block device mapping",
   "Resources" : {
      "MyEC2Instance" : {
         "Type" : "AWS::EC2::Instance",
         "Properties" : {
            "ImageId" : "ami-79fd7eee",
            "KeyName" : "testkey",
            "BlockDeviceMappings" : [
               {
                  "DeviceName" : "/dev/sdm",
                  "Ebs" : {
                     "VolumeType" : "io1",
                     "Iops" : "200",
                     "DeleteOnTermination" : "false",
                     "VolumeSize" : "20"
                  }
               },
               {
                  "DeviceName" : "/dev/sdk",
                  "NoDevice" : {}
               }
            ]
         }
      }
   }
}        

Other Examples

You can download templates that show you how to use AWS::EC2::Instance to create a virtual private cloud (VPC):

For more information about an AWS::EC2::Instance that has an IAM instance profile, see: Create an EC2 instance with an associated instance profile.

For more information about EC2 template examples, see: Amazon EC2 Snippets.

See Also