Class InstanceProps

Properties of an EC2 Instance.

Inheritance

object

InstanceProps

Implements

IInstanceProps

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: Amazon.CDK.AWS.EC2

Assembly: Amazon.CDK.Lib.dll

Syntax (csharp)

public class InstanceProps : IInstanceProps

Syntax (vb)

Public Class InstanceProps Implements IInstanceProps

Remarks

ExampleMetadata: infused

Examples

// Creates a distribution from an EC2 instance
            Vpc vpc;

            // Create an EC2 instance in a VPC. 'subnetType' can be private.
            var instance = new Instance(this, "Instance", new InstanceProps {
                Vpc = vpc,
                InstanceType = InstanceType.Of(InstanceClass.BURSTABLE3, InstanceSize.MICRO),
                MachineImage = MachineImage.LatestAmazonLinux2023(),
                VpcSubnets = new SubnetSelection { SubnetType = SubnetType.PRIVATE_WITH_EGRESS }
            });
            new Distribution(this, "myDist", new DistributionProps {
                DefaultBehavior = new BehaviorOptions { Origin = VpcOrigin.WithEc2Instance(instance) }
            });

Synopsis

Constructors

InstanceProps()

Properties of an EC2 Instance.

Properties

AllowAllIpv6Outbound	Whether the instance could initiate IPv6 connections to anywhere by default.
AllowAllOutbound	Whether the instance could initiate connections to anywhere by default.
AssociatePublicIpAddress	Whether to associate a public IP address to the primary network interface attached to this instance.
AvailabilityZone	In which AZ to place the instance within the VPC.
BlockDevices	Specifies how block devices are exposed to the instance. You can specify virtual devices and EBS volumes.
CreditSpecification	Specifying the CPU credit type for burstable EC2 instance types (T2, T3, T3a, etc).
DetailedMonitoring	Whether "Detailed Monitoring" is enabled for this instance Keep in mind that Detailed Monitoring results in extra charges.
DisableApiTermination	If true, the instance will not be able to be terminated using the Amazon EC2 console, CLI, or API.
EbsOptimized	Indicates whether the instance is optimized for Amazon EBS I/O.
EnclaveEnabled	Whether the instance is enabled for AWS Nitro Enclaves.
HibernationEnabled	Whether the instance is enabled for hibernation.
HttpEndpoint	Enables or disables the HTTP metadata endpoint on your instances.
HttpProtocolIpv6	Enables or disables the IPv6 endpoint for the instance metadata service.
HttpPutResponseHopLimit	The desired HTTP PUT response hop limit for instance metadata requests.
HttpTokens	The state of token usage for your instance metadata requests.
Init	Apply the given CloudFormation Init configuration to the instance at startup.
InitOptions	Use the given options for applying CloudFormation Init.
InstanceInitiatedShutdownBehavior	Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown).
InstanceMetadataTags	Set to enabled to allow access to instance tags from the instance metadata.
InstanceName	The name of the instance.
InstanceProfile	The instance profile used to pass role information to EC2 instances.
InstanceType	Type of instance to launch.
Ipv6AddressCount	The number of IPv6 addresses to associate with the primary network interface.
KeyName	(deprecated) Name of SSH keypair to grant access to instance.
KeyPair	The SSH keypair to grant access to the instance.
MachineImage	AMI to launch.
PlacementGroup	The placement group that you want to launch the instance into.
PrivateIpAddress	Defines a private IP address to associate with an instance.
PropagateTagsToVolumeOnCreation	Propagate the EC2 instance tags to the EBS volumes.
RequireImdsv2	Whether IMDSv2 should be required on this instance.
ResourceSignalTimeout	The length of time to wait for the resourceSignalCount.
Role	An IAM role to associate with the instance profile assigned to this Auto Scaling Group.
SecurityGroup	Security Group to assign to this instance.
SourceDestCheck	Specifies whether to enable an instance launched in a VPC to perform NAT.
SsmSessionPermissions	Add SSM session permissions to the instance role.
UserData	Specific UserData to use.
UserDataCausesReplacement	Changes to the UserData force replacement.
Vpc	VPC to launch the instance in.
VpcSubnets	Where to place the instance within the VPC.

Constructors

InstanceProps()

Properties of an EC2 Instance.

public InstanceProps()

Remarks

ExampleMetadata: infused

Examples

// Creates a distribution from an EC2 instance
            Vpc vpc;

            // Create an EC2 instance in a VPC. 'subnetType' can be private.
            var instance = new Instance(this, "Instance", new InstanceProps {
                Vpc = vpc,
                InstanceType = InstanceType.Of(InstanceClass.BURSTABLE3, InstanceSize.MICRO),
                MachineImage = MachineImage.LatestAmazonLinux2023(),
                VpcSubnets = new SubnetSelection { SubnetType = SubnetType.PRIVATE_WITH_EGRESS }
            });
            new Distribution(this, "myDist", new DistributionProps {
                DefaultBehavior = new BehaviorOptions { Origin = VpcOrigin.WithEc2Instance(instance) }
            });

Properties

AllowAllIpv6Outbound

Whether the instance could initiate IPv6 connections to anywhere by default.

public bool? AllowAllIpv6Outbound { get; set; }

Property Value

bool?

Remarks

This property is only used when you do not provide a security group.

Default: false

AllowAllOutbound

Whether the instance could initiate connections to anywhere by default.

public bool? AllowAllOutbound { get; set; }

Property Value

bool?

Remarks

This property is only used when you do not provide a security group.

Default: true

AssociatePublicIpAddress

Whether to associate a public IP address to the primary network interface attached to this instance.

public bool? AssociatePublicIpAddress { get; set; }

Property Value

bool?

Remarks

You cannot specify this property and ipv6AddressCount at the same time.

Default: - public IP address is automatically assigned based on default behavior

AvailabilityZone

In which AZ to place the instance within the VPC.

public string? AvailabilityZone { get; set; }

Property Value

string

Remarks

Default: - Random zone.

BlockDevices

Specifies how block devices are exposed to the instance. You can specify virtual devices and EBS volumes.

public IBlockDevice[]? BlockDevices { get; set; }

Property Value

IBlockDevice[]

Remarks

Each instance that is launched has an associated root device volume, either an Amazon EBS volume or an instance store volume. You can use block device mappings to specify additional EBS volumes or instance store volumes to attach to an instance when it is launched.

Default: - Uses the block device mapping of the AMI

See: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html

CreditSpecification

Specifying the CPU credit type for burstable EC2 instance types (T2, T3, T3a, etc).

public CpuCredits? CreditSpecification { get; set; }

Property Value

CpuCredits?

Remarks

The unlimited CPU credit option is not supported for T3 instances with a dedicated host.

Default: - T2 instances are standard, while T3, T4g, and T3a instances are unlimited.

DetailedMonitoring

Whether "Detailed Monitoring" is enabled for this instance Keep in mind that Detailed Monitoring results in extra charges.

public bool? DetailedMonitoring { get; set; }

Property Value

bool?

Remarks

Default: - false

See: http://aws.amazon.com/cloudwatch/pricing/

DisableApiTermination

If true, the instance will not be able to be terminated using the Amazon EC2 console, CLI, or API.

public bool? DisableApiTermination { get; set; }

Property Value

bool?

Remarks

To change this attribute after launch, use ModifyInstanceAttribute. Alternatively, if you set InstanceInitiatedShutdownBehavior to terminate, you can terminate the instance by running the shutdown command from the instance.

Default: false

See: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-instance.html#cfn-ec2-instance-disableapitermination

EbsOptimized

Indicates whether the instance is optimized for Amazon EBS I/O.

public bool? EbsOptimized { get; set; }

Property Value

bool?

Remarks

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

EnclaveEnabled

Whether the instance is enabled for AWS Nitro Enclaves.

public bool? EnclaveEnabled { get; set; }

Property Value

bool?

Remarks

Nitro Enclaves requires a Nitro-based virtualized parent instance with specific Intel/AMD with at least 4 vCPUs or Graviton with at least 2 vCPUs instance types and Linux/Windows host OS, while the enclave itself supports only Linux OS.

You can't set both enclaveEnabled and hibernationEnabled to true on the same instance.

Default: - false

See: https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html#nitro-enclave-reqs

HibernationEnabled

Whether the instance is enabled for hibernation.

public bool? HibernationEnabled { get; set; }

Property Value

bool?

Remarks

You can't set both enclaveEnabled and hibernationEnabled to true on the same instance.

Default: - false

See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-instance-hibernationoptions.html

HttpEndpoint

Enables or disables the HTTP metadata endpoint on your instances.

public bool? HttpEndpoint { get; set; }

Property Value

bool?

Remarks

Default: true

See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-instance-metadataoptions.html#cfn-ec2-instance-metadataoptions-httpendpoint

HttpProtocolIpv6

Enables or disables the IPv6 endpoint for the instance metadata service.

public bool? HttpProtocolIpv6 { get; set; }

Property Value

bool?

Remarks

Default: false

See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-instance-metadataoptions.html#cfn-ec2-instance-metadataoptions-httpprotocolipv6

HttpPutResponseHopLimit

The desired HTTP PUT response hop limit for instance metadata requests.

public double? HttpPutResponseHopLimit { get; set; }

Property Value

double?

Remarks

The larger the number, the further instance metadata requests can travel.

Possible values: Integers from 1 to 64

Default: - No default value specified by CloudFormation

See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-instance-metadataoptions.html#cfn-ec2-instance-metadataoptions-httpputresponsehoplimit

HttpTokens

The state of token usage for your instance metadata requests.

public HttpTokens? HttpTokens { get; set; }

Property Value

HttpTokens?

Remarks

Set to 'required' to enforce IMDSv2. This is equivalent to using requireImdsv2: true, but allows you to configure other metadata options alongside IMDSv2 enforcement.

Default: - The default is conditional based on the AMI and account-level settings:

If the AMI's ImdsSupport is v2.0 and the account level default is no-preference, the default is HttpTokens.REQUIRED
If the AMI's ImdsSupport is v2.0 and the account level default is V1 or V2, the default is HttpTokens.OPTIONAL
See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html#instance-metadata-options-order-of-precedence

See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-instance-metadataoptions.html#cfn-ec2-instance-metadataoptions-httptokens

Init

Apply the given CloudFormation Init configuration to the instance at startup.

public CloudFormationInit? Init { get; set; }

Property Value

CloudFormationInit

Remarks

Default: - no CloudFormation init

InitOptions

Use the given options for applying CloudFormation Init.

public IApplyCloudFormationInitOptions? InitOptions { get; set; }

Property Value

IApplyCloudFormationInitOptions

Remarks

Describes the configsets to use and the timeout to wait

Default: - default options

InstanceInitiatedShutdownBehavior

Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown).

public InstanceInitiatedShutdownBehavior? InstanceInitiatedShutdownBehavior { get; set; }

Property Value

InstanceInitiatedShutdownBehavior?

Remarks

Default: InstanceInitiatedShutdownBehavior.STOP

See: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingInstanceInitiatedShutdownBehavior

InstanceMetadataTags

Set to enabled to allow access to instance tags from the instance metadata.

public bool? InstanceMetadataTags { get; set; }

Property Value

bool?

Remarks

Set to disabled to turn off access to instance tags from the instance metadata.

Default: false

See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-instance-metadataoptions.html#cfn-ec2-instance-metadataoptions-instancemetadatatags

InstanceName

The name of the instance.

public string? InstanceName { get; set; }

Property Value

string

Remarks

Default: - CDK generated name

InstanceProfile

The instance profile used to pass role information to EC2 instances.

public IInstanceProfile? InstanceProfile { get; set; }

Property Value

IInstanceProfile

Remarks

Note: You can provide an instanceProfile or a role, but not both.

Default: - No instance profile

InstanceType

Type of instance to launch.

public InstanceType InstanceType { get; set; }

Property Value

InstanceType

Remarks

ExampleMetadata: infused

Ipv6AddressCount

The number of IPv6 addresses to associate with the primary network interface.

public double? Ipv6AddressCount { get; set; }

Property Value

double?

Remarks

Amazon EC2 chooses the IPv6 addresses from the range of your subnet.

You cannot specify this property and associatePublicIpAddress at the same time.

Default: - For instances associated with an IPv6 subnet, use 1; otherwise, use 0.

KeyName

(deprecated) Name of SSH keypair to grant access to instance.

[Obsolete("- Use `keyPair` instead - https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2-readme.html#using-an-existing-ec2-key-pair")]
public string? KeyName { get; set; }

Property Value

string

Remarks

Default: - No SSH access will be possible.

Stability: Deprecated

KeyPair

The SSH keypair to grant access to the instance.

public IKeyPair? KeyPair { get; set; }

Property Value

IKeyPair

Remarks

Default: - No SSH access will be possible.

MachineImage

AMI to launch.

public IMachineImage MachineImage { get; set; }

Property Value

IMachineImage

Remarks

ExampleMetadata: infused

PlacementGroup

The placement group that you want to launch the instance into.

public IPlacementGroupRef? PlacementGroup { get; set; }

Property Value

IPlacementGroupRef

Remarks

Default: - no placement group will be used for this instance.

PrivateIpAddress

Defines a private IP address to associate with an instance.

public string? PrivateIpAddress { get; set; }

Property Value

string

Remarks

Private IP should be available within the VPC that the instance is build within.

Default: - no association

PropagateTagsToVolumeOnCreation

Propagate the EC2 instance tags to the EBS volumes.

public bool? PropagateTagsToVolumeOnCreation { get; set; }

Property Value

bool?

Remarks

Default: - false

RequireImdsv2

Whether IMDSv2 should be required on this instance.

public bool? RequireImdsv2 { get; set; }

Property Value

bool?

Remarks

This is a simple boolean flag that enforces IMDSv2 by creating a Launch Template with httpTokens: 'required'. Use this for straightforward IMDSv2 enforcement.

For more granular control over metadata options (like disabling the metadata endpoint, configuring hop limits, or enabling instance tags), use the individual metadata option properties instead.

Default: - false

ResourceSignalTimeout

The length of time to wait for the resourceSignalCount.

public Duration? ResourceSignalTimeout { get; set; }

Property Value

Duration

Remarks

The maximum value is 43200 (12 hours).

Default: Duration.minutes(5)

Role

An IAM role to associate with the instance profile assigned to this Auto Scaling Group.

public IRole? Role { get; set; }

Property Value

IRole

Remarks

The role must be assumable by the service principal ec2.amazonaws.com: Note: You can provide an instanceProfile or a role, but not both.

Default: - A role will automatically be created, it can be accessed via the role property

Examples

var role = new Role(this, "MyRole", new RoleProps {
                 AssumedBy = new ServicePrincipal("ec2.amazonaws.com")
             });

SecurityGroup

Security Group to assign to this instance.

public ISecurityGroup? SecurityGroup { get; set; }

Property Value

ISecurityGroup

Remarks

Default: - create new security group

SourceDestCheck

Specifies whether to enable an instance launched in a VPC to perform NAT.

public bool? SourceDestCheck { get; set; }

Property Value

bool?

Remarks

This controls whether source/destination checking is enabled on the instance. A value of true means that checking is enabled, and false means that checking is disabled. The value must be false for the instance to perform NAT.

Default: true

SsmSessionPermissions

Add SSM session permissions to the instance role.

public bool? SsmSessionPermissions { get; set; }

Property Value

bool?

Remarks

Setting this to true adds the necessary permissions to connect to the instance using SSM Session Manager. You can do this from the AWS Console.

NOTE: Setting this flag to true may not be enough by itself. You must also use an AMI that comes with the SSM Agent, or install the SSM Agent yourself. See Working with SSM Agent in the SSM Developer Guide.

Default: false

UserData

Specific UserData to use.

public UserData? UserData { get; set; }

Property Value

UserData

Remarks

The UserData may still be mutated after creation.

Default: - A UserData object appropriate for the MachineImage's Operating System is created.

UserDataCausesReplacement

Changes to the UserData force replacement.

public bool? UserDataCausesReplacement { get; set; }

Property Value

bool?

Remarks

Depending the EC2 instance type, changing UserData either restarts the instance or replaces the instance.

By default, restarting does not execute the new UserData so you will need a different mechanism to ensure the instance is restarted.

Setting this to true will make the instance's Logical ID depend on the UserData, which will cause CloudFormation to replace it if the UserData changes.

Default: - true if initOptions is specified, false otherwise.

Vpc

VPC to launch the instance in.

public IVpc Vpc { get; set; }

Property Value

IVpc

Remarks

ExampleMetadata: infused

VpcSubnets

Where to place the instance within the VPC.

public ISubnetSelection? VpcSubnets { get; set; }

Property Value

ISubnetSelection

Remarks

Default: - Private subnets.

Implements

IInstanceProps