RunInstances#

Description#

Launches the specified number of instances using an image for which you have permissions.

If network parameters (NetworkInterface, SubnetId, SecurityGroupId, etc.) are not specified, the instance will be launched in the default subnet (if necessary, use CreateDefaultSubnet to create such a subnet). If an instance is created using a launch template that specifies a security group from other than the default VPC, specify a subnet ID as well. If the launch template contains NetworkInterface, BlockDeviceMapping or TagSpecification parameters and these parameters are also passed in the request, they will be merged and those specified in the request will take precedence. For NetworkInterface, merging is based on DeviceIndex, while for BlockDeviceMapping, it is based on DeviceName, and for TagSpecification, it is based on ResourceType and Key.

Request Parameters#

Required parameters#

  • MinCount — The minimum number of instances to launch.

    • Type: Integer

    • Required: Yes

  • MaxCount — The maximum number of instances to launch.

    • Type: Integer

    • Required: Yes

Optional parameters#

  • AddressingType — The type of address. With the value public, a public IP address will be associated with the primary interface when the instance is created in a VPC and there are available allocated Elastic IP addresses.

    • Type: String

    • Required: No

    • Valid values: public | private

  • BlockDeviceMapping.N — The block device mapping.

  • DisableApiTermination — Prohibits to delete the instance via API.

    • Type: Boolean

    • Required: No

  • HighAvailable — The high availability mode.

    • Type: Boolean

    • Default value: True

    • Required: No

  • imageId — The image ID.

    • Type: String

    • Required: No

  • InstanceInitiatedShutdownBehavior — Indicates whether the instance will be stopped or terminated when you run the shutdown command using the operating system.

    • Type: String

    • Required: No

    • Valid values: stop | terminate

  • InstanceType — The instance type..

    • Type: String

    • Required: No

  • KernelId — Not supported

  • KeyName — The name of the SSH key.

    • Type: String

    • Required: No

  • LaunchTemplate — The launch template to use to create instances. Any parameters specified in RunInstances take precedence over the same parameters in the launch template. You can specify either the launch template ID, or the launch template name.

    • Type: LaunchTemplateSpecification object

    • Required: No

    • Constraints: SubnetID is required if the launch template specifies a security group from a non-default VPC

  • Monitoring.Enabled — Enables the monitoring for instance and attached volumes.

    • Type: Boolean

    • Default value: True

    • Required: No

  • NetworkInterface.N — The network interfaces of the instance.

  • Placement —The instance placement rules.

  • PrivateIpAddress — The private IP-address.

    • Type: String

    • Required: No

  • RamdiskId — Not supported

  • RamMonitoring — Indicates whether RAM monitoring is enabled for the instance. Monitoring requires to additional configuration of the instance.

    • Type: Boolean

    • Default value: False

    • Required: No

  • RootDeviceName — The name of the root (boot) device of the instance.

    • Type: String

    • Required: No

    • Valid values: disk<N> | cdrom<N> | floppy<N> | menu

    • By default: Inherits from the image attributes

  • SecurityGroupId.N — The IDs of security groups.

    • Type: Array of strings

    • Required: No

    • Restriction: if SubnetId is not specified, then the selected security group must be created in the default VPC

  • SubnetId — The ID of the subnet.

    • Type: String

    • Required: No

  • SwitchId.N — IDs of virtual switches.

    • Type: Array of strings

    • Required: No

  • TagSpecification.N — Tags assigned to a resource when it is created. Tagging is available only for instance | volume.

  • UserData — The user data for the instance. You must pass base64-encoded text in this parameter. The text length must not exceed 16 KB.

    • Type: String

    • Required: No

  • VirtualizationType — The virtualization type.

    • Type: String

    • Required: No

    • Possible values: hvm | hvm-legacy

Response Elements#

  • groupSet — The security groups for the instance.

  • instancesSet — Information about instances.

  • ownerId — The ID of the project.

    • Type: String

  • requestId — The request ID.

    • Type: String

Specification#

Using a subnet or a virtual switch:

  • AddressingType

  • PrivateIpAddress

  • SecurityGroupId (list)

  • SubnetId

  • SwitchId (list)

# single subnet:
    c2-ec2 RunInstances ImageId <image_id> InstanceType <type> MinCount 1 MaxCount 1 SubnetId <subnet_id>
    aws <...> run-instances --image-id <image_id> --count 1 --instance-type m1.micro --subnet-id <subnet_id>

# single switch:
    c2-ec2 RunInstances ImageId <image_id> InstanceType <type> MinCount 1 MaxCount 1 SwitchId.0 <switch_id>
    (not supported in awscli)

# multiple switches:
    c2-ec2 RunInstances ImageId <image_id> InstanceType <type> MinCount 1 MaxCount 1 SwitchId.0 <switch_id> SwitchId.1 <switch_id>
    (not supported in awscli)

Using a new or existing interface:

  • NetworkInterface (list)

    -either- existing interface:

    • DeviceIndex

    • NetworkInterfaceId

    -or- new interface:

    • AssociatePublicIpAddress

    • DeleteOnTermination

    • DeviceIndex

    • Description

    • Primary

    • PrivateIpAddress

    • PrivateIpAddresses (list)

    • SecurityGroupId (list)

    • SubnetId

# single subnet interface (new, with additional security groups):
    c2-ec2 RunInstances ImageId <image_id> InstanceType <type> MinCount 1 MaxCount 1 NetworkInterface.0.DeviceIndex 0 NetworkInterface.0.SubnetId <subnet_id> NetworkInterface.0.SecurityGroupId.0 <group1_id> NetworkInterface.0.SecurityGroupId.1 <group2_id>
    aws <...> run-instances --image-id <image_id> --count 1 --instance-type <type> --network-interfaces "[{\"DeviceIndex\": 0, \"SubnetId\": \"<subnet_id>\", \"Groups\": [\"<group1_id>\", \"<group2_id>\"]}]"

# single switch interface (new):
    c2-ec2 RunInstances ImageId <image_id> InstanceType <type> MinCount 1 MaxCount 1 NetworkInterface.0.DeviceIndex 0 NetworkInterface.0.SubnetId <switch_id>
    aws <...> run-instances --image-id <image_id> --count 1 --instance-type <type> --network-interfaces "[{\"DeviceIndex\": 0, \"SubnetId\": \"<switch_id>\"}]"

# single existing interface (subnet or switch):
    c2-ec2 RunInstances ImageId <image_id> InstanceType <type> MinCount 1 MaxCount 1 NetworkInterface.0.DeviceIndex 0 NetworkInterface.0.NetworkInterfaceId <network_interface_id>
    aws <...> run-instances --image-id <image_id> --count 1 --instance-type <type> --network-interfaces "[{\"DeviceIndex\": 0, \"NetworkInterfaceId\": \"<network_interface_id>\"}]"

# multiple interfaces (new and existing):
    c2-ec2 RunInstances ImageId <image_id> InstanceType <type> MinCount 1 MaxCount 1 NetworkInterface.0.DeviceIndex 0 NetworkInterface.0.NetworkInterfaceId <network_interface_id> NetworkInterface.1.DeviceIndex 1 NetworkInterface.1.SubnetId <switch_or_subnet_id> NetworkInterface.1.Description "eth1_description..." NetworkInterface.1.DeleteOnTermination True
    aws <...> run-instances --image-id <image_id> --count 1 --instance-type <type> --network-interfaces "[{\"DeviceIndex\": 0, \"NetworkInterfaceId\": \"<network_interface_id>\"}, {\"DeviceIndex\": 1, \"SubnetId\": \"<switch_or_subnet_id>\", \"Description\": \"eth1_description...\", \"DeleteOnTermination\": True}]"

Examples#

c2-ec2 RunInstances ImageId cmi-01234567 InstanceType m1.micro MaxCount 1 MinCount 1

c2-ec2 RunInstances ImageId cmi-01234567 InstanceType m1.micro MaxCount 1 MinCount 1 SecurityGroupId.1 sg-01234567 SubnetId subnet-01234567 AddressingType private

c2-ec2 RunInstances ImageId cmi-01234567 InstanceType m1.micro MaxCount 1 MinCount 1 SecurityGroupId.1 sg-01234567 \
            TagSpecification.0.ResourceType instance \
            TagSpecification.0.Tag.0.Key Name \
            TagSpecification.0.Tag.0.Value my_description

c2-ec2 RunInstances ImageId cmi-078880A0 InstanceType m1.micro \
            MaxCount 1 MinCount 1 TagSpecification.0.ResourceType instance \
            TagSpecification.0.Tag.0.Key "tag_key" TagSpecification.0.Tag.0.Value "tag_value"

c2-ec2 RunInstances LaunchTemplate.LaunchTemplateId lt-12345678 LaunchTemplate.Version 1 MaxCount 1 MinCount 1