**To launch an instance in EC2-Classic**

This example launches a single instance of type ``t1.micro``.

The key pair and security group, named ``MyKeyPair`` and ``MySecurityGroup``, must exist.

Command::

  aws ec2 run-instances --image-id ami-1a2b3c4d --count 1 --instance-type t1.micro --key-name MyKeyPair --security-groups MySecurityGroup

Output::

  {
      "OwnerId": "123456789012",
      "ReservationId": "r-5875ca20",
      "Groups": [
          {
              "GroupName": "MySecurityGroup",
              "GroupId": "sg-903004f8"
          }
      ],
      "Instances": [
          {
              "Monitoring": {
                  "State": "disabled"
              },
              "PublicDnsName": null,
              "RootDeviceType": "ebs",
              "State": {
                  "Code": 0,
                  "Name": "pending"
              },
              "EbsOptimized": false,
              "LaunchTime": "2013-07-19T02:42:39.000Z",
              "ProductCodes": [],
              "StateTransitionReason": null, 
              "InstanceId": "i-123abc45",
              "ImageId": "ami-1a2b3c4d",
              "PrivateDnsName": null,
              "KeyName": "MyKeyPair",
              "SecurityGroups": [
                  {
                      "GroupName": "MySecurityGroup",
                      "GroupId": "sg-903004f8"
                  }
              ],
              "ClientToken": null,
              "InstanceType": "t1.micro",
              "NetworkInterfaces": [],
              "Placement": {
                  "Tenancy": "default",
                  "GroupName": null,
                  "AvailabilityZone": "us-east-1b"
              },
              "Hypervisor": "xen",
              "BlockDeviceMappings": [],
              "Architecture": "x86_64",
              "StateReason": {
                  "Message": "pending",
                  "Code": "pending"
              },
              "RootDeviceName": "/dev/sda1",
              "VirtualizationType": "hvm",
              "AmiLaunchIndex": 0
          }
      ]
  }

**To launch an instance in EC2-VPC**

This example launches a single instance of type ``t2.micro`` into the specified subnet.

The key pair named ``MyKeyPair`` and the security group sg-903004f8 must exist.

Command::

  aws ec2 run-instances --image-id ami-abc12345 --count 1 --instance-type t2.micro --key-name MyKeyPair --security-group-ids sg-903004f8 --subnet-id subnet-6e7f829e

Output::

  {
      "OwnerId": "123456789012",
      "ReservationId": "r-5875ca20",
      "Groups": [],
      "Instances": [
          {
              "Monitoring": {
                  "State": "disabled"
              },
              "PublicDnsName": null,
              "RootDeviceType": "ebs",
              "State": {
                  "Code": 0,
                  "Name": "pending"
              },
              "EbsOptimized": false,
              "LaunchTime": "2013-07-19T02:42:39.000Z",
              "PrivateIpAddress": "10.0.1.114",
              "ProductCodes": [],
              "VpcId": "vpc-1a2b3c4d",
              "InstanceId": "i-5203422c",
              "ImageId": "ami-abc12345",
              "PrivateDnsName": "ip-10-0-1-114.ec2.internal",
              "KeyName": "MyKeyPair",
              "SecurityGroups": [
                  {
                      "GroupName": "MySecurityGroup",
                      "GroupId": "sg-903004f8"
                  }
              ],
              "ClientToken": null,
              "SubnetId": "subnet-6e7f829e",
              "InstanceType": "t2.micro",
              "NetworkInterfaces": [
                  {
                      "Status": "in-use",
                      "MacAddress": "0e:ad:05:3b:60:52",
                      "SourceDestCheck": true,
                      "VpcId": "vpc-1a2b3c4d",
                      "Description": "null",
                      "NetworkInterfaceId": "eni-a7edb1c9",
                      "PrivateIpAddresses": [
                          {
                              "PrivateDnsName": "ip-10-0-1-114.ec2.internal",
                              "Primary": true,
                              "PrivateIpAddress": "10.0.1.114"
                          }
                      ],
                      "PrivateDnsName": "ip-10-0-1-114.ec2.internal",
                      "Attachment": {
                          "Status": "attached",
                          "DeviceIndex": 0,
                          "DeleteOnTermination": true,
                          "AttachmentId": "eni-attach-52193138",
                          "AttachTime": "2013-07-19T02:42:39.000Z"
                      },
                      "Groups": [
                          {
                              "GroupName": "MySecurityGroup",
                              "GroupId": "sg-903004f8"
                          }
                      ],
                      "SubnetId": "subnet-6e7f829e",
                      "OwnerId": "123456789012",
                      "PrivateIpAddress": "10.0.1.114"
                  }
              ],
              "SourceDestCheck": true,
              "Placement": {
                  "Tenancy": "default",
                  "GroupName": null,
                  "AvailabilityZone": "us-east-1b"
              },
              "Hypervisor": "xen",
              "BlockDeviceMappings": [],
              "Architecture": "x86_64",
              "StateReason": {
                  "Message": "pending",
                  "Code": "pending"
              },
              "RootDeviceName": "/dev/sda1",
              "VirtualizationType": "hvm",
              "AmiLaunchIndex": 0
          }
      ]
  }

The following example requests a public IP address for an instance that you're launching into a nondefault subnet:

Command::

  aws ec2 run-instances --image-id ami-c3b8d6aa --count 1 --instance-type t1.micro --key-name MyKeyPair --security-group-ids sg-903004f8 --subnet-id subnet-6e7f829e --associate-public-ip-address

**To launch an instance using a block device mapping**

Add the following parameter to your ``run-instances`` command to add an Amazon EBS volume with the device name ``/dev/sdh`` and a volume size of 100.

Command::

  --block-device-mappings "[{\"DeviceName\": \"/dev/sdh\",\"Ebs\":{\"VolumeSize\":100}}]"

Add the following parameter to your ``run-instances`` command to add ``ephemeral1`` as an instance store volume with the device name ``/dev/sdc``.

Command::

  --block-device-mappings "[{\"DeviceName\": \"/dev/sdc\",\"VirtualName\":\"ephemeral1\"}]"

Add the following parameter to your ``run-instances`` command to omit a device specified by the AMI used to launch the instance (for example, ``/dev/sdf``).

Command::

  --block-device-mappings "[{\"DeviceName\": \"/dev/sdf\",\"NoDevice\":\"\"}]"

You can view only the Amazon EBS volumes in your block device mapping using the console or the ``describe-instances`` command. To view all volumes, including the instance store volumes, use the following command.

Command::

  GET http://169.254.169.254/latest/meta-data/block-device-mapping

Output::

  ami
  ephemeral1

Note that ``ami`` represents the root volume. To get details about the instance store volume ``ephemeral1``, use the following command.

Command::

  GET http://169.254.169.254/latest/meta-data/block-device-mapping/ephemeral1

Output::

  sdc

**To launch an instance with a modified block device mapping**

You can change individual characteristics of existing AMI block device mappings to suit your needs. Perhaps you want to use an existing AMI, but you want a larger root volume than the usual 8 GiB. Or, you would like to use a General Purpose (SSD) volume for an AMI that currently uses a Magnetic volume.

Use the ``describe-images`` command with the image ID of the AMI you want to use to find its existing block device mapping. You should see a block device mapping in the output.

Output::

  {
    "DeviceName": "/dev/sda1",
    "Ebs": {
      "DeleteOnTermination": true,
      "SnapshotId": "snap-b047276d",
      "VolumeSize": 8,
      "VolumeType": "standard",
      "Encrypted": false
    }
  }

You can modify the above mapping by changing the individual parameters. For example, to launch an instance with a modified block device mapping, add the following parameter to your ``run-instances`` command to change the above mapping's volume size and type.

Command::

  --block-device-mappings "[{\"DeviceName\":\"/dev/sda1\",\"Ebs\":{\"DeleteOnTermination\":true,\"SnapshotId\":\"snap-b047276d\",\"VolumeSize\":100,\"VolumeType\":\"gp2\"}}]"

For more information about launching instances, see `Using Amazon EC2 Instances`_ in the *AWS Command Line Interface User Guide*.

.. _`Using Amazon EC2 Instances`: http://docs.aws.amazon.com/cli/latest/userguide/cli-ec2-launch.html

