Syntax Properties Return values Examples See also

AWS::EC2::Instance

Specifies an 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

To declare this entity in your CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::EC2::Instance",
  "Properties" : {
      "AdditionalInfo" : String,
      "Affinity" : String,
      "AvailabilityZone" : String,
      "BlockDeviceMappings" : [ BlockDeviceMapping, ... ],
      "CpuOptions" : CpuOptions,
      "CreditSpecification" : CreditSpecification,
      "DisableApiTermination" : Boolean,
      "EbsOptimized" : Boolean,
      "ElasticGpuSpecifications" : [ ElasticGpuSpecification, ... ],
      "ElasticInferenceAccelerators" : [ ElasticInferenceAccelerator, ... ],
      "EnclaveOptions" : EnclaveOptions,
      "HibernationOptions" : HibernationOptions,
      "HostId" : String,
      "HostResourceGroupArn" : String,
      "IamInstanceProfile" : String,
      "ImageId" : String,
      "InstanceInitiatedShutdownBehavior" : String,
      "InstanceType" : String,
      "Ipv6AddressCount" : Integer,
      "Ipv6Addresses" : [ InstanceIpv6Address, ... ],
      "KernelId" : String,
      "KeyName" : String,
      "LaunchTemplate" : LaunchTemplateSpecification,
      "LicenseSpecifications" : [ LicenseSpecification, ... ],
      "MetadataOptions" : MetadataOptions,
      "Monitoring" : Boolean,
      "NetworkInterfaces" : [ NetworkInterface, ... ],
      "PlacementGroupName" : String,
      "PrivateDnsNameOptions" : PrivateDnsNameOptions,
      "PrivateIpAddress" : String,
      "PropagateTagsToVolumeOnCreation" : Boolean,
      "RamdiskId" : String,
      "SecurityGroupIds" : [ String, ... ],
      "SecurityGroups" : [ String, ... ],
      "SourceDestCheck" : Boolean,
      "SsmAssociations" : [ SsmAssociation, ... ],
      "SubnetId" : String,
      "Tags" : [ Tag, ... ],
      "Tenancy" : String,
      "UserData" : String,
      "Volumes" : [ Volume, ... ]
    }
}

YAML


Type: AWS::EC2::Instance
Properties:
  AdditionalInfo: String
  Affinity: String
  AvailabilityZone: String
  BlockDeviceMappings: 
    - BlockDeviceMapping
  CpuOptions: 
    CpuOptions
  CreditSpecification: 
    CreditSpecification
  DisableApiTermination: Boolean
  EbsOptimized: Boolean
  ElasticGpuSpecifications: 
    - ElasticGpuSpecification
  ElasticInferenceAccelerators: 
    - ElasticInferenceAccelerator
  EnclaveOptions: 
    EnclaveOptions
  HibernationOptions: 
    HibernationOptions
  HostId: String
  HostResourceGroupArn: String
  IamInstanceProfile: String
  ImageId: String
  InstanceInitiatedShutdownBehavior: String
  InstanceType: String
  Ipv6AddressCount: Integer
  Ipv6Addresses: 
    - InstanceIpv6Address
  KernelId: String
  KeyName: String
  LaunchTemplate: 
    LaunchTemplateSpecification
  LicenseSpecifications: 
    - LicenseSpecification
  MetadataOptions: 
    MetadataOptions
  Monitoring: Boolean
  NetworkInterfaces: 
    - NetworkInterface
  PlacementGroupName: String
  PrivateDnsNameOptions: 
    PrivateDnsNameOptions
  PrivateIpAddress: String
  PropagateTagsToVolumeOnCreation: Boolean
  RamdiskId: String
  SecurityGroupIds: 
    - String
  SecurityGroups: 
    - String
  SourceDestCheck: Boolean
  SsmAssociations: 
    - SsmAssociation
  SubnetId: String
  Tags: 
    - Tag
  Tenancy: String
  UserData: String
  Volumes: 
    - Volume

Properties

AdditionalInfo

This property is reserved for internal use. If you use it, the stack fails with this error: Bad property set: [Testing this property] (Service: AmazonEC2; Status Code: 400; Error Code: InvalidParameterCombination; Request ID: 0XXXXXX-49c7-4b40-8bcc-76885dcXXXXX).

Required: No

Type: String

Update requires: Some interruptions

Affinity

Indicates whether the instance is associated with a dedicated host. If you want the instance to always restart on the same host on which it was launched, specify host. If you want the instance to restart on any available host, but try to launch onto the last host it ran on (on a best-effort basis), specify default.

Required: No

Type: String

Allowed values: default | host

Update requires: Some interruptions

AvailabilityZone

The Availability Zone of the instance.

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

This parameter is not supported by DescribeImageAttribute.

Required: No

Type: String

Update requires: Replacement

BlockDeviceMappings

The block device mapping entries that defines the block devices to attach to the instance at launch.

By default, the block devices specified in the block device mapping for the AMI are used. You can override the AMI block device mapping using the instance block device mapping. For the root volume, you can override only the volume size, volume type, volume encryption settings, and the DeleteOnTermination setting.

Important

After the instance is running, you can modify only the DeleteOnTermination parameter for the attached volumes without interrupting the instance. Modifying any other parameter results in instance replacement.

Required: No

Type: Array of BlockDeviceMapping

Update requires: Some interruptions

CpuOptions

The CPU options for the instance. For more information, see Optimize CPU options in the Amazon Elastic Compute Cloud User Guide.

Required: No

Type: CpuOptions

Update requires: Replacement

CreditSpecification

The credit option for CPU usage of the burstable performance instance. Valid values are standard and unlimited. To change this attribute after launch, use ModifyInstanceCreditSpecification. For more information, see Burstable performance instances in the Amazon EC2 User Guide.

Default: standard (T2 instances) or unlimited (T3/T3a/T4g instances)

For T3 instances with host tenancy, only standard is supported.

Required: No

Type: CreditSpecification

Update requires: No interruption

DisableApiTermination

Indicates whether termination protection is enabled for the instance. The default is false, which means that you can terminate the instance using the Amazon EC2 console, command line tools, or API. You can enable termination protection when you launch an instance, while the instance is running, or while the instance is stopped.

Required: No

Type: Boolean

Update requires: No interruption

EbsOptimized

Indicates whether the instance is optimized for Amazon EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal Amazon EBS I/O performance. This optimization isn't available with all instance types. Additional usage charges apply when using an EBS-optimized instance.

Default: false

Required: No

Type: Boolean

Update requires: Some interruptions

ElasticGpuSpecifications

An elastic GPU to associate with the instance.

Note

Amazon Elastic Graphics reached end of life on January 8, 2024.

Required: No

Type: Array of ElasticGpuSpecification

Update requires: Replacement

ElasticInferenceAccelerators

An elastic inference accelerator to associate with the instance.

Note

Amazon Elastic Inference is no longer available.

Required: No

Type: Array of ElasticInferenceAccelerator

Update requires: Replacement

EnclaveOptions

Indicates whether the instance is enabled for AWS Nitro Enclaves.

Required: No

Type: EnclaveOptions

Update requires: Replacement

HibernationOptions

Indicates whether an instance is enabled for hibernation. This parameter is valid only if the instance meets the hibernation prerequisites. For more information, see Hibernate your Amazon EC2 instance in the Amazon EC2 User Guide.

You can't enable hibernation and AWS Nitro Enclaves on the same instance.

Required: No

Type: HibernationOptions

Update requires: Replacement

HostId

If you specify host for the Affinity property, the ID of a dedicated host that the instance is associated with. If you don't specify an ID, Amazon EC2 launches the instance onto any available, compatible dedicated host in your account. This type of launch is called an untargeted launch. Note that for untargeted launches, you must have a compatible, dedicated host available to successfully launch instances.

Required: No

Type: String

Update requires: Some interruptions

HostResourceGroupArn

The ARN of the host resource group in which to launch the instances. If you specify a host resource group ARN, omit the