Creating VMs

You can create one or more fully custom virtual machines (VMs) in the public Cloud or in a Net.

You can define the different characteristics of the VMs and create several VMs in the same creation request. These VMs are grouped within a same reservation. To modify the characteristics you defined for a VM, see Modifying a VM Attribute.

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

Creating VMs Using Cockpit v2

Using Cockpit v2 enables you to create several VMs in the same creation request. These VMs are grouped within a same reservation.

Open the Create VMs Window

In the VMs dashboard, click IconAddFull Create VMs.
The CREATE VMs - EXPERT MODE window appears.

Configure Your VM

Choose a Name, Tenancy Option, and Shutdown Behavior

  1. (optional) In the VM name field, type a name for your VMs.

    This name must contain between 1 and 255 ASCII printable characters.

    This name is used as a tag associated with your VM.

  2. (optional) Check the Dedicated box to create dedicated VMs.
    For more information, see About VMs.

  3. (optional) Select one of the following values from the Shutdown behavior option list:

    • Stop: When you initiate shutdown, the VMs stop.

    • Terminate: When you initiate shutdown, the VMs stop and are terminated.

    • Restart: When you initiate shutdown, the VMs stop then automatically restart.

  4. Click Next.
    The Image selection screen appears.

Choose an Image

  1. Select an image for your VMs.

  2. Click Next.
    The VM Type selection screen appears.

Choose a VM Type and the Number of VMs

  1. Specify the following attributes for your VMs:

    • CPU generation: The processor generation.

    • Performance: The performance flag.

      • Highest: Maximum compute capacity on all the cores of the VM. This option is ideal for intensive compute applications that require stable performances during the VM lifecycle.

      • High: High compute capacity on all the cores of the VM. This option offers small performance variability and applies to most cases.

      • Medium: Performance with significant variability on all the cores of the VM. This option does not guarantee consistent performance, but is ideal for machines with low CPU demand.

    • Core(s): The number of vCores, up to 78.

    • Memory (GiB): The amount of memory, up to 1039 GiB.

    For more information about VM types, see VM Types.

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

  2. Specify the number of VMs you want to create.

    You can create up to 20 instances at a time.

  3. Click Next.
    The Net screen appears.

Choose the Public Cloud or a Net and a Subregion

  1. If you want to create VMs in the public Cloud:

    1. Leave the Public Cloud switch on.

    2. Select the Subregion where you want to create your VMs.

      When creating VMs in the public Cloud, you cannot define the private IP of the VMs.

  2. If you want to create VMs in a Net:

    1. Switch off Public Cloud.

    2. Select one of your Subnets in the Subnet list.

    3. (optional) In the Private IP field, if you are creating one VM only, type the private IP for the VM, within the IP range of the subnet.

      When you create VMs in a Net using the Expert mode:

      • Only the Subregion of the chosen subnet is listed.

      • Network interface cards (NICs) are automatically created and attached to the VMs.

  3. Click Next.
    The Root Volume screen appears.

Choose a Root Volume

  1. If you want your VMs to use a default root volume:

    1. Select Proceed with a default root volume.

    2. (optional) In the Volume Name field, type a name for your root volume.

  2. If you want to customize the root volume of your VMs:

    1. Select Customize the root volume.

    2. (optional) In the Volume Name field, type a name for your root volume.

    3. Select one of the following values from the Volume Type option list:

      • standard for a Magnetic volume

      • gp2 for a Performance volume

      • io1 for an Enterprise volume

        If you select io1, you have to set the number of IOPS you need.

        For more information, see About Volumes > Volume Types and IOPS.

    4. In the Volume Size field, specify the size of the volume (in GiB).

  3. Click Next.
    The Security group screen appears.

Choose Security Groups

  1. If you want to assign a new security group to your VMs, select Create a new security group:

    1. In the Name field, type a name for the security group.

    2. In the Description field, type its description.

      • The name must be unique in your account for the public Cloud or for each Net.

      • The name of the security group must not start with sg-.

      • Each name and description can contain between 1 and 255 characters. Allowed characters are a-z, A-Z, 0-9, spaces, and _.-:/()#,@[]+=&;\{}!$*.

  2. If you want to assign one or more existing security groups to your VMs, select Select one or more existing security groups and select them from the list that appears.

    This list depends on the choice you made in the Public Cloud/Net screen. If you chose a Net, only the security groups of the chosen Net are listed.

  3. If you want to assign a default security group to your VMs, select Proceed with a default security group.

  4. Click Next.
    The Keypair screen appears.

Choose a Keypair

  1. If you want to assign an existing keypair to your VMs, select it from the list.

    Only RSA keypairs can decrypt the password of a Windows VM.

  2. If you want to create a new keypair to assign to your VMs, select Create a new keypair:

    1. In the Keypair name field, type a name for the keypair.

    2. Click Create and download keypair.

      Once you have downloaded the file containing the private key of the keypair, save it carefully, as it is required to connect to your VMs. 3DS OUTSCALE cannot provide any copy in case of loss.

  3. If you do not want to assign a keypair to your VMs, select Proceed without a keypair.

    In Expert Mode, you can create a VM without assigning any keypair to it. However, all official images use keypairs as their authentication system. Therefore, if you want to be able to access a VM created from an official image, you need to assign it a keypair either during this step or later. To assign a keypair later, see Modifying a VM Attribute.

  4. Click Next.
    The User Data / Cloud-init screen appears.

Specify User Data

  1. (optional) Type user data for the VMs in the Outscale section field.
    For more information, see Configuring a VM with User Data and OUTSCALE Tags.

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

  2. (optional) Type user data for the VMs in the Free section / Cloud-init field. For more information, see Using cloud-init with User Data.

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

  3. Click Next.
    The Summary screen appears.

Confirm the Creation

  1. Review the settings you have specified for the VMs.

  2. Click Create VMs.
    The VMs are created.

Creating VMs Using OSC CLI

The CreateVms command creates virtual machines (VMs), and then launches them.
This action enables you to create a specified number of VMs using an OUTSCALE machine image (OMI) that you are allowed to use, and then to automatically launch them.
The VMs remain in the pending state until they are created and ready to be used. Once automatically launched, they are in the running state.
To check the state of your VMs, call the ReadVms method.
If not specified, the security group used by the service is the default one.
The metadata server enables you to get the public key provided when the VM is launched. Official OMIs contain a script to get this public key and put it inside the VM to provide secure access without password.

For more information, see About VMs.

Request sample: Creating a VM (minimal syntax)
$ osc-cli api CreateVms --profile "default" \
    --ImageId "ami-12345678"
Request sample: Creating a VM in a Net
$ osc-cli api CreateVms --profile "default" \
    --ImageId "ami-12345678" \
    --VmType "tinav5.c1r1p2" \
    --KeypairName "keypair-example" \
    --SecurityGroupIds '["sg-12345678"]' \
    --SubnetId "subnet-12345678" \
    --UserData "$(base64 -i user_data.txt)"
Request sample: Creating a VM with block device mappings
$ osc-cli api CreateVms --profile "default" \
    --ImageId "ami-12345678" \
    --VmType "tinav5.c1r1p2" \
    --KeypairName "keypair-example" \
    --SecurityGroupIds '["sg-12345678"]' \
    --SubnetId "subnet-12345678" \
    --UserData "$(base64 -i user_data.txt)" \
    --BlockDeviceMappings '[
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {"VolumeSize": 15, "VolumeType": "gp2"},
        },
        {
          "DeviceName": "/dev/sdb",
          "Bsu": {"SnapshotId": "snap-12345678", "VolumeSize": 22, "VolumeType": "io1", "Iops": 150},
        },
      ]'
Request sample: Creating a VM with a NIC
$ osc-cli api CreateVms --profile "default" \
    --ImageId "ami-12345678" \
    --VmType "tinav5.c1r1p2" \
    --KeypairName "keypair-example" \
    --UserData "$(base64 -i user_data.txt)" \
    --Nics '[
        {
          "DeviceNumber": 0,
          "NicId": "eni-12345678",
        },
      ]'

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

  • BlockDeviceMappings: (optional) One or more block device mappings.

  • BootOnCreation: (optional) By default or if true, the VM is started on creation. If false, the VM is stopped on creation.

  • BsuOptimized: (optional) This parameter is not available. It is present in our API for the sake of historical compatibility with AWS.

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

  • DeletionProtection: (optional) If true, you cannot delete the VM unless you change this parameter back to false.

  • DryRun: (optional) If true, checks whether you have the required permissions to perform the action.

  • ImageId: The ID of the OMI used to create the VM. You can find the list of OMIs by calling the ReadImages method.

  • KeypairName: (optional) The name of the keypair.

  • MaxVmsCount: (optional) The maximum number of VMs you want to create. If all the VMs cannot be created, the largest possible number of VMs above MinVmsCount is created.

  • MinVmsCount: (optional) The minimum number of VMs you want to create. If this number of VMs cannot be created, no VMs are created.

  • NestedVirtualization: (optional) (dedicated tenancy only) If true, nested virtualization is enabled. If false, it is disabled.

  • Nics: (optional) One or more NICs. If you specify this parameter, you must not specify the SubnetId and SubregionName parameters. You also must define one NIC as the primary network interface of the VM with 0 as its device number.

  • Performance: (optional) The performance of the VM (medium | high | highest). By default, high. This parameter is ignored if you specify a performance flag directly in the VmType parameter.

  • Placement: (optional) Information about the placement of the VM.

  • PrivateIps: (optional) One or more private IPs of the VM.

  • SecurityGroupIds: (optional) One or more IDs of security group for the VMs.

  • SecurityGroups: (optional) One or more names of security groups for the VMs.

  • SubnetId: (optional) The ID of the Subnet in which you want to create the VM. If you specify this parameter, you must not specify the Nics parameter.

  • UserData: (optional) Data or script used to add a specific configuration to the VM. It must be Base64-encoded and is limited to 500 kibibytes (KiB).

  • VmInitiatedShutdownBehavior: (optional) The VM behavior when you stop it. By default or if set to stop, the VM stops. If set to restart, the VM stops then automatically restarts. If set to terminate, the VM stops and is terminated.

  • VmType: (optional) The type of VM. You can specify a TINA type (in the tinavW.cXrYpZ or tinavW.cXrY format), or an AWS type (for example, t2.small, which is the default value).
    If you specify an AWS type, it is converted in the background to its corresponding TINA type, but the AWS type is still returned. If the specified or converted TINA type includes a performance flag, this performance flag is applied regardless of the value you may have provided in the Performance parameter. For more information, see VM Types.

The CreateVms command returns the following elements:

  • ResponseContext: Information about the context of the response.

  • Vms: Information about one or more created VMs.

Result sample: Creating a VM (minimal syntax)
{
  "Vms": [
    {
      "VmType": "t2.small",
      "VmInitiatedShutdownBehavior": "stop",
      "State": "pending",
      "StateReason": "",
      "RootDeviceType": "ebs",
      "RootDeviceName": "/dev/sda1",
      "IsSourceDestChecked": true,
      "ImageId": "ami-12345678",
      "DeletionProtection": false,
      "Architecture": "x86_64",
      "NestedVirtualization": false,
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeId": "vol-12345678",
            "State": "attaching",
            "LinkDate": "2010-10-01T12:34:56.789Z",
            "DeleteOnVmDeletion": true
          }
        }
      ],
      "VmId": "i-12345678",
      "ReservationId": "r-12345678",
      "Hypervisor": "xen",
      "Placement": {
        "Tenancy": "default",
        "SubregionName": "eu-west-2a"
      },
      "ProductCodes": [
        "0001"
      ],
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "UserData": "...",
      "PrivateIp": "10.0.0.4",
      "SecurityGroups": [
        {
          "SecurityGroupName": "default",
          "SecurityGroupId": "sg-12345678"
        }
      ],
      "BsuOptimized": false,
      "LaunchNumber": 0,
      "Performance": "medium",
      "Tags": [],
      "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal"
    }
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
}
Result sample: Creating a VM in a Net
{
  "Vms": [
    {
      "VmType": "tinav5.c1r1p2",
      "VmInitiatedShutdownBehavior": "stop",
      "State": "pending",
      "StateReason": "",
      "RootDeviceType": "ebs",
      "RootDeviceName": "/dev/sda1",
      "IsSourceDestChecked": true,
      "KeypairName": "keypair-example",
      "ImageId": "ami-12345678",
      "DeletionProtection": false,
      "Architecture": "x86_64",
      "NestedVirtualization": false,
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeId": "vol-12345678",
            "State": "attaching",
            "LinkDate": "2010-10-01T12:34:56.789Z",
            "DeleteOnVmDeletion": true
          }
        }
      ],
      "VmId": "i-12345678",
      "ReservationId": "r-12345678",
      "Hypervisor": "xen",
      "Placement": {
        "Tenancy": "default",
        "SubregionName": "eu-west-2a"
      },
      "ProductCodes": [
        "0001"
      ],
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "UserData": "...",
      "SubnetId": "subnet-12345678",
      "PrivateIp": "10.0.0.4",
      "SecurityGroups": [
        {
          "SecurityGroupName": "security-group-example",
          "SecurityGroupId": "sg-12345678"
        }
      ],
      "BsuOptimized": false,
      "LaunchNumber": 0,
      "NetId": "vpc-12345678",
      "Nics": [
        {
          "SubnetId": "subnet-12345678",
          "State": "in-use",
          "LinkNic": {
            "State": "attached",
            "DeviceNumber": 0,
            "LinkNicId": "eni-attach-12345678",
            "DeleteOnVmDeletion": true
          },
          "IsSourceDestChecked": true,
          "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal",
          "Description": "Primary network interface",
          "AccountId": "123456789012",
          "SecurityGroups": [
            {
              "SecurityGroupName": "security-group-example",
              "SecurityGroupId": "sg-12345678"
            }
          ],
          "MacAddress": "A1:B2:C3:D4:E5:F6",
          "NetId": "vpc-12345678",
          "NicId": "eni-12345678",
          "PrivateIps": [
            {
              "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal",
              "PrivateIp": "10.0.0.4",
              "IsPrimary": true
            }
          ]
        }
      ],
      "Performance": "high",
      "Tags": [],
      "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal"
    }
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
}
Result sample: Creating a VM with block device mappings
{
  "Vms": [
    {
      "VmType": "tinav5.c1r1p2",
      "VmInitiatedShutdownBehavior": "stop",
      "State": "pending",
      "StateReason": "",
      "RootDeviceType": "ebs",
      "RootDeviceName": "/dev/sda1",
      "IsSourceDestChecked": true,
      "KeypairName": "keypair-example",
      "ImageId": "ami-12345678",
      "DeletionProtection": false,
      "Architecture": "x86_64",
      "NestedVirtualization": false,
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeId": "vol-12345678",
            "State": "attaching",
            "LinkDate": "2010-10-01T12:34:56.789Z",
            "DeleteOnVmDeletion": true
          }
        },
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeId": "vol-87654321",
            "State": "attaching",
            "LinkDate": "2010-10-01T12:34:56.789Z",
            "DeleteOnVmDeletion": true
          }
        }
      ],
      "VmId": "i-12345678",
      "ReservationId": "r-12345678",
      "Hypervisor": "xen",
      "Placement": {
        "Tenancy": "default",
        "SubregionName": "eu-west-2a"
      },
      "ProductCodes": [
        "0001"
      ],
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "UserData": "...",
      "SubnetId": "subnet-12345678",
      "PrivateIp": "10.0.0.4",
      "SecurityGroups": [
        {
          "SecurityGroupName": "security-group-example",
          "SecurityGroupId": "sg-12345678"
        }
      ],
      "BsuOptimized": false,
      "LaunchNumber": 0,
      "NetId": "vpc-12345678",
      "Nics": [
        {
          "SubnetId": "subnet-12345678",
          "State": "in-use",
          "LinkNic": {
            "State": "attached",
            "DeviceNumber": 0,
            "LinkNicId": "eni-attach-12345678",
            "DeleteOnVmDeletion": true
          },
          "IsSourceDestChecked": true,
          "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal",
          "Description": "Primary network interface",
          "AccountId": "123456789012",
          "SecurityGroups": [
            {
              "SecurityGroupName": "security-group-example",
              "SecurityGroupId": "sg-12345678"
            }
          ],
          "MacAddress": "A1:B2:C3:D4:E5:F6",
          "NetId": "vpc-12345678",
          "NicId": "eni-12345678",
          "PrivateIps": [
            {
              "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal",
              "PrivateIp": "10.0.0.4",
              "IsPrimary": true
            }
          ]
        }
      ],
      "Performance": "high",
      "Tags": [],
      "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal"
    }
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
}
Result sample: Creating a VM with a NIC
{
  "Vms": [
    {
      "VmType": "tinav5.c1r1p2",
      "VmInitiatedShutdownBehavior": "stop",
      "State": "pending",
      "StateReason": "",
      "RootDeviceType": "ebs",
      "RootDeviceName": "/dev/sda1",
      "IsSourceDestChecked": true,
      "KeypairName": "keypair-example",
      "ImageId": "ami-12345678",
      "DeletionProtection": false,
      "Architecture": "x86_64",
      "NestedVirtualization": false,
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeId": "vol-12345678",
            "State": "attaching",
            "LinkDate": "2010-10-01T12:34:56.789Z",
            "DeleteOnVmDeletion": true
          }
        }
      ],
      "VmId": "i-12345678",
      "ReservationId": "r-12345678",
      "Hypervisor": "xen",
      "Placement": {
        "Tenancy": "default",
        "SubregionName": "eu-west-2a"
      },
      "ProductCodes": [
        "0001"
      ],
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "UserData": "...",
      "SubnetId": "subnet-12345678",
      "PrivateIp": "10.0.0.4",
      "SecurityGroups": [
        {
          "SecurityGroupName": "security-group-example",
          "SecurityGroupId": "sg-12345678"
        }
      ],
      "BsuOptimized": false,
      "LaunchNumber": 0,
      "NetId": "vpc-12345678",
      "Nics": [
        {
          "SubnetId": "subnet-12345678",
          "State": "in-use",
          "LinkNic": {
            "State": "attached",
            "DeviceNumber": 0,
            "LinkNicId": "eni-attach-12345678",
            "DeleteOnVmDeletion": true
          },
          "IsSourceDestChecked": true,
          "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal",
          "Description": "Example NIC",
          "AccountId": "123456789012",
          "SecurityGroups": [
            {
              "SecurityGroupName": "security-group-example",
              "SecurityGroupId": "sg-12345678"
            }
          ],
          "MacAddress": "A1:B2:C3:D4:E5:F6",
          "NetId": "vpc-12345678",
          "NicId": "eni-12345678",
          "PrivateIps": [
            {
              "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal",
              "PrivateIp": "10.0.0.4",
              "IsPrimary": true
            }
          ]
        }
      ],
      "Performance": "high",
      "Tags": [],
      "PrivateDnsName": "ip-10-0-0-4.eu-west-2.compute.internal"
    }
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
}

Launching Instances Using AWS CLI

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 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 of a VM .

  • (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 a VM 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 VM Types.

    To function properly, Windows VMs 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:

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

      If you do not specify any Subregion, the Subregion 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.

    The IP must come from the IP 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 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 a NIC Attribute.

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

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

        Only one IP can be primary.

      • PrivateIpAddress: The private IP.

  • (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 associated with the instance, replaced by the External IP (EIP), if any. In a VPC, the EIP if any.

    • PrivateIpAddress: The private IP 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 information, 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 VM 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 Methods

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

Export to PDF