Run Instances operation for the Amazon EC2 REST adapter - Documentation for BMC Atrium Orchestrator Content 20.14.02
Mia Walsh
Published Apr 07, 2026
The Run Instances operation enables you to launch a specified number of instances of an Amazon Machine Image (AMI) for which you have permissions.
If Amazon EC2 cannot launch the specified minimum number of AMIs, no instances are launched. If there is insufficient capacity to launch the specified maximum number of AMIs, Amazon EC2 launches the minimum number of instances for each AMI and later allocates the remaining available instances.
The following figure shows a sample <items> XML element for the Run Instances operation.
Sample <items> XML element for the Run Instances operations
<items> <item> <parameters> <image-id></image-id> <min-count></min-count> <max-count></max-count> <!-Optional:-> <key-name></key-name> <group-set> <!-Zero or more repetition-> <item> <group-id></group-id> </item> </group-set> <!-Optional:-> <additional-info></additional-info> <!-Optional:-> <user-data> <!-Optional:-> <data></data> </user-data> <!-Optional:-> <instance-type></instance-type> <!-Optional:-> <placement> <!-Optional:-> <availability-zone></availability-zone> </placement> <!-Optional:-> <kernel-id></kernel-id> <!-Optional:-> <ramdisk-id></ramdisk-id> <!-Optional: -> <block-device-mapping> <!-Zero or more repetitions:-> <item> <device-name></device-name> <virtual-name></virtual-name> <ebs> <!-Optional:-> <snapshot-id></snapshot-id> <!-Optional:-> <volume-size></volume-size> <!-Optional:-> <volume-type></volume-type> <!-Optional:-> <iops></iops> <!-Optional:-> <delete-on-termination></delete-on-termination> </ebs> <no-device/> </item> </block-device-mapping> <!-Optional:-> <monitoring> <!-Optional:-> <enabled></enabled> </monitoring> <!-Optional:-> <subnet-id></subnet-id> <!-Optional:-> <instance-initiated-shutdown-behavior/> <private-ip-address></private-ip-address> </parameters> </item>
</items>The following table describes the elements for this adapter request.
Adapter request elements for the Run Instances operation
Element | Definition | Required |
|---|---|---|
<access-key> | Specifies the Amazon Web Services (AWS) access key You need to generate the AWS access key by going to the Security Credentials tab in the AWS console. | Conditional;
|
<secret-key> | Specifies the AWS secret access key You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console. | Conditional;
|
<region> | Specifies the region with which you want the adapter to communicate Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions. Valid values:
| No |
| Contains the name of the operation: run-instances | Yes |
| Specifies the unique ID for the Amazon Machine Image (AMI) | Yes |
| Specifies the minimum number of instances to launch If Amazon EC2 cannot launch the value specified in the Valid values: Any value between 1 and the maximum number of instances allowed for your Amazon EC2 account Default value: 20 | Yes |
| Specifies the maximum number of instances to launch If Amazon EC2 cannot launch the value specified in the Valid values: Any value between 1 and the maximum number of instances allowed for your Amazon EC2 account Default value: 20 | Yes |
| Specifies the name of the key pair | No |
| Specifies the type of the instance Valid values:
| No |
| Specifies how the block devices are exposed to the instance Each mapping comprises a virtual-name and a device-name. The
| No |
| Contains the device name (For example, /dev/sdh) | No |
| Specifies the parameters used to automatically setup Amazon EBS volumes when the instance is launched | Conditional; You can specify only one of the |
| Specifies the ID for the snapshot of the Amazon EBS volume | No |
| Specifies the size of the Amazon EBS volume | No |
<volume-type> | Specifies the type of the volume. Valid Values: io1 (To create a Provisioned IOPS volume), standard (default) Note: If the volume type is io1, you can also provision the number of IOPS that the volume supports. | No |
<iops> | Specifies the number of IOPS that a volume of type io1 supports | No |
| Specifies whether the Amazon EBS volume must be deleted when the instances is terminated | No |
| Specifies whether the device name is suppressed while launching the instance | Conditional; You can specify only one of the |
<virtual-name> | Specifies an instance store volume to be mapped to the device For example, ephemeral0. | Conditional; You can specify only one of the <ebs>, <no-device>, or the <virtual-name> elements within the <block-device-mapping> element. |
| Specifies whether to enable monitoring for the instance | No |
| Specifies the subnet ID for the Amazon Virtual Private Cloud within which to launch the instance or instances | No |
| Specifies whether the Amazon EBS volumes used by the instance are terminated when the instance is shut down | No |
| Specifies the private IP address in a virtual private cloud (VPC instance) | No |
The following figure shows a sample adapter request for the Run Instances operation.
Sample adapter request for the Run Instances operation
<amazon-ec2-rest-request> <operation-name>run-instances</operation-name> <parameters> <image-id>ami-b8f69f88</image-id> <min-count>1</min-count> <max-count>2</max-count> <key-name>test01</key-name> <group-set> <item> <group-id /> </item> </group-set> <additional-info>Additional Test data</additional-info> <user-data> <data>Users test data</data> </user-data> <instance-type>t1.micro</instance-type> <placement> <availability-zone>us-west-2b</availability-zone> </placement> <monitoring> <enabled>false</enabled> </monitoring> </parameters> </amazon-ec2-rest-request>The following figure shows the response for the sample Run Instances operation.
Sample adapter response for the Run Instances operation
<amazon-ec2-rest-response> <metadata> <status>success</status> </metadata> <RunInstancesResponse> <reservationId>r-d6254bdf</reservationId> <ownerId>246495073671</ownerId> <groupSet> <item> <groupId>sg-39067c09</groupId> <groupName>default</groupName> </item> </groupSet> <instancesSet> <item> <instanceId>i-a0094ea9</instanceId> <imageId>ami-b8f69f88</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName></privateDnsName> <dnsName></dnsName> <securityGroupSet> <item> <groupId>sg-39067c09</groupId> <groupName>default</groupName> </item> </securityGroupSet> <stateReason> <code>pending</code> <message>pending</message> </stateReason> <keyName>test01</keyName> <amiLaunchIndex>1</amiLaunchIndex> <productCodes /> <instanceType>t1.micro</instanceType> <launchTime>Tue Apr 01 11:36:07 IST 2014</launchTime> <placement> <availabilityZone>us-west-2b</availabilityZone> <groupName></groupName> <tenancy>default</tenancy> </placement> <kernelId>aki-fc8f11cc</kernelId> <ramdiskId /> <monitoring> <state>disabled</state> </monitoring> <privateIpAddress /> <ipAddress /> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping /> </item> <item> <instanceId>i-a3094eaa</instanceId> <imageId>ami-b8f69f88</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName></privateDnsName> <dnsName></dnsName> <securityGroupSet> <item> <groupId>sg-39067c09</groupId> <groupName>default</groupName> </item> </securityGroupSet> <stateReason> <code>pending</code> <message>pending</message> </stateReason> <keyName>test01</keyName> <amiLaunchIndex>0</amiLaunchIndex> <productCodes /> <instanceType>t1.micro</instanceType> <launchTime>Tue Apr 01 11:36:07 IST 2014</launchTime> <placement> <availabilityZone>us-west-2b</availabilityZone> <groupName></groupName> <tenancy>default</tenancy> </placement> <kernelId>aki-fc8f11cc</kernelId> <ramdiskId /> <monitoring> <state>disabled</state> </monitoring> <privateIpAddress /> <ipAddress /> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping /> </item> </instancesSet> </RunInstancesResponse>
</amazon-ec2-rest-response>The following figure shows a sample adapter request for the Run Instances operation with the <block-device mapping> element.
Sample adapter request for the Run Instances operation with the <block-device mapping> element
<amazon-ec2-rest-request> <operation-name>run-instances</operation-name> <parameters> <image-id>ami-b8cea688</image-id> <min-count>1</min-count> <max-count>2</max-count> <key-name>test01</key-name> <group-set> <item> <group-id /> </item> </group-set> <additional-info>Additional Test data</additional-info> <user-data> <data>Users test data</data> </user-data> <instance-type>t1.micro</instance-type> <placement> <availability-zone>us-west-2b</availability-zone> </placement> <block-device-mapping> <item> <device-name>/dev/sdb</device-name> <virtual-name /> <ebs> <snapshot-id>snap-167a24e6</snapshot-id> <volume-size>8</volume-size> <volume-type>standard</volume-type> <iops /> <delete-on-termination>true</delete-on-termination> </ebs> <no-device /> </item> </block-device-mapping> <monitoring> <enabled>false</enabled> </monitoring> </parameters> </amazon-ec2-rest-request>The following figure shows the response for the sample Run Instances operation with the <block-device mapping> element.
Sample adapter response for the Run Instances operation with the <block-device mapping> element
<amazon-ec2-rest-response> <metadata> <status>success</status> </metadata> <RunInstancesResponse> <reservationId>r-050c650c</reservationId> <ownerId>246495073671</ownerId> <groupSet> <item> <groupId>sg-39067c09</groupId> <groupName>default</groupName> </item> </groupSet> <instancesSet> <item> <instanceId>i-c77137ce</instanceId> <imageId>ami-b8cea688</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName></privateDnsName> <dnsName></dnsName> <securityGroupSet> <item> <groupId>sg-39067c09</groupId> <groupName>default</groupName> </item> </securityGroupSet> <stateReason> <code>pending</code> <message>pending</message> </stateReason> <keyName>test01</keyName> <amiLaunchIndex>1</amiLaunchIndex> <productCodes /> <instanceType>t1.micro</instanceType> <launchTime>Wed Apr 02 11:35:56 IST 2014</launchTime> <placement> <availabilityZone>us-west-2b</availabilityZone> <groupName></groupName> <tenancy>default</tenancy> </placement> <kernelId>aki-fc8f11cc</kernelId> <ramdiskId /> <monitoring> <state>disabled</state> </monitoring> <privateIpAddress /> <ipAddress /> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping /> </item> <item> <instanceId>i-c67137cf</instanceId> <imageId>ami-b8cea688</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName></privateDnsName> <dnsName></dnsName> <securityGroupSet> <item> <groupId>sg-39067c09</groupId> <groupName>default</groupName> </item> </securityGroupSet> <stateReason> <code>pending</code> <message>pending</message> </stateReason> <keyName>test01</keyName> <amiLaunchIndex>0</amiLaunchIndex> <productCodes /> <instanceType>t1.micro</instanceType> <launchTime>Wed Apr 02 11:35:56 IST 2014</launchTime> <placement> <availabilityZone>us-west-2b</availabilityZone> <groupName></groupName> <tenancy>default</tenancy> </placement> <kernelId>aki-fc8f11cc</kernelId> <ramdiskId /> <monitoring> <state>disabled</state> </monitoring> <privateIpAddress /> <ipAddress /> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping /> </item> </instancesSet> </RunInstancesResponse>
</amazon-ec2-rest-response>
