Working with the AWS CLI for EC2

1. Introduction

In this short tutorial, we’re going to take a look at the AWS Command Line Interface for EC2 services.

Before going further, please remember to configure our AWS CLI access.

2. List EC2 Instances

First, let’s see how we can list our EC2 instances:

$ aws ec2 describe-instances

The output will contain all necessary data about our instances in JSON format. A few of the most useful properties are:

{
  "InstanceId": "instance_id",
  "InstanceType": "t2.small",
  "KeyName": "ssh_key_name",
  "LaunchTime": "2020-01-31T15:48:22.000Z",
  "Monitoring": {
    "State": "disabled"
  },
  "Placement": {
    "AvailabilityZone": "eu-central-1c"
  },
  "PublicIpAddress": "1.123.123.12",
  "State": {
    "Code": 80,
    "Name": "stopped"
  },
  "Tags": [
    {
      "Key": "Creator",
      "Value": "Baeldung"
    }
  ]
}

We can also use the CLI to filter our instances by a given property. To do so we need to add an extra –filters parameter.

For example, we can search for instances with a given type:

$ aws ec2 describe-instances --filters Name=instance-type,Values=t2.medium

or a tag key:

$ aws ec2 describe-instances --filters "Name=tag-key,Values=Baeldung"

This will return only the instances that match our filters.

To get detail about specific EC2 instances we need to pass the –instance-ids parameter followed by a list of instance ids:

$ aws ec2 describe-instances --instance-ids instance_id instance_id_2

3. Create a New Key Pair for EC2 Instances

Before launching a new EC2 instance we’ll need an SSH key pair that we’ll use to connect to it.

The AWS CLI gives as an easy way for generating keys:

$ aws ec2 create-key-pair --key-name BaeldungKey --output text > BaeldungKey.pem

The above command will create a new key in the AWS named BaeldungKey and pipe the secret key directly to the location we specify, in this case, BaeldungKey.pem.

The resulting file will look similar to the following:

-----BEGIN RSA PRIVATE KEY-----
EXAMPLEKEYKCAQEAy7WZhaDsrA1W3mRlQtvhwyO
...
-----END RSA PRIVATE KEY-----

It can be now used while creating a new EC2 instance.

4. Launch New EC2 Instances

The AWS CLI gives us an easy way to launch new EC2 instances. As a prerequisite, we need to prepare the pem key pair and choose the desired Amazon Machine Image (AMI) and instance type.

The AMI provides the operating system, application server, and applications for the instance. The instance type though defines hardware properties like CPU and RAM.

As an example we’ll create t2.micro instance running Ubuntu 18.04 image with id ami-0b418580298265d5c:

$ aws ec2 run-instances --image-id ami-0b418580298265d5c --instance-type t2.micro --key-name BaeldungKey

The output will contain all the data about our new instance in JSON format. A few more important ones include:

{
  "Instances": [
    {
      "PrivateDns": "ip-10-31-39-158.eu-central-1.compute.internal",
      "Status": "booting",
      "InstanceId": "9b137a0d-2f5d-4cc0-9704-13da4b31fdcb",
      "SshKeyName": "EU-Central-1",
      "InstanceType": "t2.micro",
      "CreatedAt": "2020-02-07T11:00:00+00:00",
      "PublicDns": "ec2-192-0-2-1.eu-central-1.compute.amazonaws.com",
      "SecurityGroupIds": [
        "sg-b022add5"
      ],
      "Architecture": "x86_64",
      "RootDeviceType": "ebs",
      "Os": "Server Ubuntu 18.04",
      "AvailabilityZone": "eu-central-1c",
      "PrivateIp": "10.31.39.158",
      "PublicIp": "192.0.2.0"
    }
  ]
}

After launching, the new instance, it’s ready for use. To connect to it, we can use either it’s IP address from the PublicIp property or a host from the PublicDns property.

Beware, there might be a short time before we can connect to it. This can be monitored by instance state found in describe-instances command output.

First, the instance state is pending:

{
  ...
  "State": {
    "Code": 0,
    "Name": "pending"
  },
  ...
}

When the state is running, the instance is fully booted and ready to connect to:

{
  ...
  "State": {
    "Code": 16,
    "Name": "running"
  },
  ...
}

While creating a new instance, we can specify a security group that will be attached to it by adding the –security-group-ids security_group_id parameter. If we don’t specify it, the default one will be used. For more information, see the AWS Security Groups documentation.

We can specify the subnet id as well by just adding –subnet-id subnet_id. If we don’t specify it, the default one will be used.

To learn about more options that can be used while launching EC2 instances see the AWS official documentation for run-instance command.

5. Stop and Start an EC2 Instance

Any on-demand EC2 instance in a running state can be stopped:

$ aws ec2 stop-instances --instance-ids instance_id

And started again:

$ aws ec2 start-instances --instance-ids instance_id

Notice, that the instance will retain its instance id after startup but will be given a different public IP address.

6. Terminate an Instance

If we want to remove the instance completely, then we can terminate the instance:

$ aws ec2 terminate-instances --instance-ids instance_id

Beware, that when we terminate an instance it won’t be possible to start it again like with a stopped instance. For more information about the differences between stopping and terminating instances, see Instance Lifecycle Documentation.

Terminated instances remain visible after termination (for approximately one hour).

7. Conclusion

In this tutorial, we’ve learned how to list and create new EC2 instances, how to start, stop or terminate them and how to generate an ssh access key for EC2 instances.