Launching Instances Using AWS CLI

You can launch one or more fully custom instances in the public Cloud or in a Virtual Private Cloud (VPC) using AWS CLI.

You can define the different characteristics of the instances and launch several instances in the same launch request. These instances are grouped within a same reservation. To modify the characteristics you defined for an instance, see Modifying an Instance Attribute.

When launching an instance using AWS CLI, you specify the OUTSCALE Machine Image (OMI), the instance type, the security groups, a keypair to use, its placement, one or more block device mappings, termination protection, and so on. You can also add user data and tags to instances at launch.

All official OMIs use keypairs as their authentication system. To launch an instance from an official OMI, you must specify a keypair. However, non-official OMIs can use any authentication system. To launch an instance from a non-official OMI, you need to check whether a keypair is required. For more information, see About Keypairs.

To launch one or more instances, use the run-instances command following one of these syntaxes:

Request sample (minimal syntax)
$ aws ec2 run-instances \
   --profile YOUR_PROFILE \
   --image-id ami-12345678 \
   --endpoint https://fcu.eu-west-2.outscale.com
Request sample (full syntax)
$ aws ec2 run-instances \
   --profile YOUR_PROFILE \
   --image-id ami-12345678 \
   --key-name \
   --security-groups \
   --security-group-ids sg-187654321 \
   --user-data YOUR_USER_DATA \
   --instance-type t2.small \
   --placement  \
           "{ \
           \"AvailabilityZone\": \"eu-west-2a\", \
           \"Tenancy\": \"default\", \
           }" \
   --block-device-mappings YOUR_BLOCK_DEVICE_MAPPINGS \
   --subnet-id subnet-12345678 \
   --disable-api-termination \
   --instance-initiated-shutdown-behavior stop \
   --private-ip-address 10.0.1.100 \
   --client-token "" \
   --network-interfaces \
           "{ \
           \"NetworkInterfaceId\": \"eni-12345678\", \
           \"DeviceIndex\": 0, \
           \"SubnetId\": \"subnet-12345678\", \
           \"Description\": \"Network interface description\", \
           \"PrivateIpAddress\": \"10.0.1.100\", \
           \"Groups\": \"sg-187654321\", \
           \"DeleteOnTermination\": false \
           \"PrivateIpAddresses\": [ \
                                    { \
                                     \"PrivateIpAddress\": \"10.0.1.100\", \
                                     \"Primary\": true \
                                    } \
           }" \
   --count 1 \
   [--ebs-optimized NOT_SPECIFIED] \
   --endpoint https://fcu.eu-west-2.outscale.com

This command contains the following attributes that you need to specify:

  • (optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.

  • image-id: The ID of the OMI to use to launch the instance. For more information, see OMIs User Interface or Getting Information About Your OMIs.

  • (optional) key-name: The name of the keypair to use for the instance. For more information, see About Keypairs.

    We strongly recommend to specify a keypair when launching an instance. Otherwise, you cannot connect to the instance until you add a keypair to it. For more information, see Modifying the Keypair Used by an Instance .

  • (optional) security-groups: One or more security group names (only in the public Cloud). If not specified, the Default security group is used.

  • (optional) security-group-ids: One or more security group IDs. If not specified, the Default security group is used.

  • (optional) user-data: User data for the instance. For more information, see Configuring an Instance with User Data and OUTSCALE Tags.

    AWS CLI then encodes this user data to Base64. The maximum size for the Base64-encoded user data is 500 kibibytes (KiB).

  • (optional) instance-type: The instance type. If not specified, a t2.small instance is created. For more information, see Instance Types.

    To function properly, Windows instances require at least a v3 processor generation, 2 vCores, and 4 GiB of memory.

  • (optional) placement: The placement of the instance. This attribute contains the following elements that you need to specify:

    • Availability Zone: The Availability Zone (AZ) in which you want to launch the instance.

      If you do not specify any AZ, the AZ A is used by default.

    • Tenancy: The tenancy of an instance (dedicated | default). For more information, see About Instances > Instance Tenancy and Dedicated Instances.

  • (optional) block-device-mappings: One or more block device mappings for the instance. For more information, see Defining Block Device Mappings.

  • (optional) subnet-id: In a VPC, the ID of the subnet in which you want to launch the instance.

  • (optional) disable-api-termination|enable-api-termination: Disables or enables the ability to terminate the instance (by default, enabled).

  • (optional) instance-initiated-shutdown-behavior: By default or if set to stop, the instance stops when you stop or terminate it. If set to terminate, it stops then terminates. If set to restart, it stops then automatically restarts. For more information, see About Instance Lifecycle > Termination.

  • (optional) private-ip-address: In a VPC, the unique primary IP address.

    The IP address must come from the IP address range of the subnet.

  • (optional) client-token: A unique identifier that enables you to manage the idempotency (if any).

  • (optional) network-interfaces: One or more network interfaces. If you specify this parameter, you must define one network interface as the primary one of the instance with 0 as its device index.
    This attribute contains the following elements that you need to specify:

    • NetworkInterfaceId: The ID of the network interface of the instance.

    • DeviceIndex: The index of the instance device for the network interface (between 0 and 7, both included).

    • SubnetId: The ID of the subnet associated with the network interface, if you are creating a network interface when launching an instance.

    • Description: A description for the network interface.

    • PrivateIpAddress: The private IP address of the network interface.

    • Groups: The ID of one or more security groups to associate with the network interface.

    • DeleteOnTermination: By default or if set to true, the network interface is deleted when the instance is terminated. You can specify this parameter only for a new network interface. To modify this value for an existing network interface, see Modifying an FNI Attribute.

    • PrivateIpAddresses: One or more private IP addresses to assign to the network interface.

      • Primary: If set to true, the IP address is the primary one.

        Only one IP address can be primary.

      • PrivateIpAddress: The private IP address.

  • (optional) count: The number of instances to launch.

    You can specify:

    • A single number, considered as the minimum number of instances to launch (by default, 1)

    • A range in the form min:max. The first number is considered as the minimum number of instances to launch, the second one as the maximum.

  • (optional) ebs-optimized: Whether the instance is BSU-optimized or not.

  • endpoint: The endpoint corresponding to the Region you want to send the request to.

The run-instance command returns the following elements:

  • OwnerId: The account ID of the owner of the instance.

  • Reservation: The ID of the reservation. For more information, see About Instances > General Information About Instances.

  • Groups: Information about the security groups the instance is associated with.

  • Instances: Information about one or more instances. This element contains the following information for each instance:

    • Monitoring: Indicates whether monitoring is enabled for the instance (always disabled).

    • PublicDnsName: The public DNS name for the instance.

    • Platform: No information returned.

    • State: Information about the state of the instance (the state code and its name).

    • EbsOptimized: Whether the instance is BSU-optimized or not.

    • LaunchTime: The time when the instance was launched.

    • PublicIpAddress: In the public Cloud, the public IP address associated with the instance, replaced by the External IP address (EIP), if any. In a VPC, the EIP if any.

    • PrivateIpAddress: The private IP address associated with the instance.

    • ProductCodes: No information returned when using official OMIs.

    • Tags: One or more tags associated with the instance, with their Value and their Key (if any).

    • VpcId: The ID of the VPC in which the instance is.

    • InstanceId: The ID of the instance.

    • ImageId: The ID of the OMI used to launch the instance.

    • PrivateDnsName: The private DNS name for the instance.

    • KeyName: The name of the keypair used for the instance. For more informations, see About Keypairs.

    • SecurityGroups: The security groups the instance is associated with (security group name and security group ID).

    • ClientToken: A unique identifier which enables you to manage the idempotency (if any).

    • InstanceType: The instance type. For more information, see Instance Types.

    • NetworkInterfaces: In a VPC, one or more network interfaces for the instance.

    • Placement: Information about the placement of the instance. This element contains the following information:

    • SourceDestCheck: If true, source/destination check of network traffic is enabled. If false, it is disabled.

    • Hypervisor: The hypervisor type of the instance (always xen).

    • BlockDeviceMappings: One or more block device mappings for the instance. For more information, see Defining Block Device Mappings.

    • Architecture: The architecture of the instance.

    • KernelId: No information returned.

    • RootDeviceName: The device name assigned to the root device of the instance.

    • VirtualizationType: The virtualization type of the instance (always hvm).

    • RootDeviceType: The type of root device for the instance (always ebs).

    • AmiLaunchIndex: The launch index of the instance. For more information, see About Instances > General Information About Instances.

Result sample
{
   "OwnerId": "1234567890000",
   "ReservationId": "r-87654321",
   "Groups": [
       {
           "GroupName": "default",
           "GroupId": "sg-12345678"
       }
   ],
   "Instances": [
       {
           "Monitoring": {
               "State": "disabled"
           },
           "PublicDnsName": "",
           "Platform": "",
           "State": {
               "Code": 0,
               "Name": "pending"
           },
           "EbsOptimized": false,
           "LaunchTime": "2016-04-20T08:26:26.540Z",
           "PrivateIpAddress": "10.10.10.0",
           "ProductCodes": [],
           "VpcId": "vpc-56781234",
           "InstanceId": "i-12345678",
           "ImageId": "ami-87654321",
           "PrivateDnsName": "ip-10-10-10-0.eu-west-2.compute.internal",
           "KeyName": "key name",
           "SecurityGroups": [
               {
                   "GroupName": "default",
                   "GroupId": "sg-12345678"
               }
           ],
           "ClientToken": "",
           "SubnetId": "subnet-56781234",
           "InstanceType": "t2.small",
           "NetworkInterfaces": [
               {
                   "Status": "in-use",
                   "MacAddress": "aa:c0:00:00:00:00",
                   "SourceDestCheck": true,
                   "VpcId": "vpc-56781234",
                   "Description": "Primary network interface",
                   "NetworkInterfaceId": "eni-12345678",
                   "PrivateIpAddresses": [
                       {
                           "PrivateDnsName": "ip-10-10-10-0.eu-west-2.compute.internal",
                           "Primary": true,
                           "PrivateIpAddress": "10.10.10.0"
                       }
                   ],
                   "PrivateDnsName": "ip-10-10-10-0.eu-west-2.compute.internal",
                   "Attachment": {
                       "Status": "attached",
                       "DeviceIndex": 0,
                       "DeleteOnTermination": true,
                       "AttachmentId": "eni-attach-12345678",
                       "AttachTime": "2016-04-20T08:26:26.540Z"
                   },
                   "Groups": [
                       {}
                   ],
                   "SubnetId": "subnet-56781234",
                   "OwnerId": "249064296596",
                   "PrivateIpAddress": "10.10.10.0"
                }
           ],
           "SourceDestCheck": true,
           "Placement": {
               "Tenancy": "default",
               "GroupName": "",
               "AvailabilityZone": "eu-west-2a"
           },
           "Hypervisor": "xen",
           "BlockDeviceMappings": [
               {
                   "DeviceName": "/dev/vda1",
                   "Ebs": {
                       "Status": "attaching",
                       "DeleteOnTermination": true,
                       "VolumeId": "vol-87654321",
                       "AttachTime": "2016-04-20T08:26:26.540Z"
                   }
               }
           ],
           "Architecture": "x86_64",
           "KernelId": "",
           "RootDeviceName": "/dev/vda1",
           "VirtualizationType": "hvm",
           "RootDeviceType": "ebs",
           "AmiLaunchIndex": 0
        }
    ]
}

The instances are launched.

Related Pages

Corresponding API Method

AWS™ and Amazon Web Services™ are trademarks of Amazon Technologies, Inc or its affiliates in the United States and/or other countries.