AWS CloudFormation
User Guide (API Version 2010-05-15)
AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource Types Reference » AWS::EC2::Instance
« 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 Updating AWS CloudFormation Stacks.

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 EC2 Elastic Block Store (EBS) block device mappings. For more information about EBS, see Amazon Elastic Block Store in the Amazon Elastic Compute Cloud User Guide.

Required: No.

Type: A list of EC2 Block Device Mapping.

Update requires: replacement, with one exception: if only the DeleteOnTermination setting of the EC2 EBS Block Device 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: some interruptions

IamInstanceProfile

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.

Required: No.

Type: A list of NetworkInterface objects.

Update requires: no interruption

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.

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.

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.

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

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...