EC2 Deep Dive Basics

Seven short examples that go past "launch an instance" into the operations you actually run every day: describing, filtering, paginating, and tagging.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3), so the mechanics translate one to one.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-ec2 (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role with ec2:Describe* and ec2:CreateTags.
Most examples are read-only; the tagging examples make small, reversible changes.

Basic Examples

1. Describe All Instances (and Flatten the Shape)

DescribeInstances groups instances under Reservations, so you almost always flatten it.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_instances()
for reservation in resp["Reservations"]:
    for inst in reservation["Instances"]:
        print(inst["InstanceId"], inst["State"]["Name"])

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeInstancesCommand({}));
for (const r of resp.Reservations ?? []) {
  for (const inst of r.Instances ?? []) {
    console.log(inst.InstanceId, inst.State?.Name);
  }
}

Instances are nested Reservations[].Instances[], not a flat list.
A reservation groups instances launched by a single RunInstances call.
With no arguments this returns every instance in the region, including terminated ones for a short window.
Flatten with a nested loop or a comprehension before working with the data.

2. Filter Server-Side by State

Push the filter to AWS with Filters instead of downloading everything and filtering locally.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_instances(
    Filters=[{"Name": "instance-state-name", "Values": ["running"]}],
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeInstancesCommand({
  Filters: [{ Name: "instance-state-name", Values: ["running"] }],
}));

Filtering server-side returns less data and is faster and cheaper than client-side filtering.
Values is a list, so ["running", "stopped"] matches either.
Multiple filter objects are combined with AND; values within one filter are OR.
Filter names are documented per API and use hyphenated keys like instance-state-name.

3. Filter by Tag

Select a subset of your fleet using the special tag:Key filter name.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_instances(
    Filters=[{"Name": "tag:Environment", "Values": ["production"]}],
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeInstancesCommand({
  Filters: [{ Name: "tag:Environment", Values: ["production"] }],
}));

tag:<Key> matches instances whose tag Key has one of the given values.
Use tag-key to match on the presence of a key regardless of value.
Tag filtering is how most fleet automation scopes itself to the right instances.
Tag keys are case-sensitive, so Environment and environment are different.

Related: EC2 via SDK Best Practices - a consistent tagging scheme to filter against.

4. Read Common Instance Fields

The instance object carries far more than an id; here are the fields you reach for most.

# --- Python (boto3) ---
inst = resp["Reservations"][0]["Instances"][0]
print(inst["InstanceType"])        # e.g. t3.micro
print(inst["PrivateIpAddress"])
print(inst.get("PublicIpAddress")) # may be absent
print(inst["Placement"]["AvailabilityZone"])

// --- TypeScript (AWS SDK v3) ---
const inst = resp.Reservations?.[0].Instances?.[0];
console.log(inst?.InstanceType);        // e.g. t3.micro
console.log(inst?.PrivateIpAddress);
console.log(inst?.PublicIpAddress);     // may be undefined
console.log(inst?.Placement?.AvailabilityZone);

PublicIpAddress is absent for instances without a public IP, so guard for it.
Placement.AvailabilityZone tells you which AZ the instance runs in.
Tags is a list of {Key, Value} objects, not a map, so convert it if you want lookups.
LaunchTime is a timezone-aware timestamp useful for age-based cleanup.

Intermediate Examples

5. Paginate a Large Fleet

Beyond a page size, results are paged; use a paginator or a NextToken loop.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
paginator = ec2.get_paginator("describe_instances")
for page in paginator.paginate():
    for r in page["Reservations"]:
        for inst in r["Instances"]:
            print(inst["InstanceId"])

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
let token: string | undefined;
do {
  const page = await ec2.send(new DescribeInstancesCommand({ NextToken: token }));
  for (const r of page.Reservations ?? []) {
    for (const inst of r.Instances ?? []) console.log(inst.InstanceId);
  }
  token = page.NextToken;
} while (token);

boto3 paginators hide the token loop entirely - always prefer them.
SDK v3 also ships paginateDescribeInstances if you want the same convenience.
Never assume one call returns everything; a busy account will page.
Pagination is per API and each has its own MaxResults ceiling.

6. Add Tags to an Instance

CreateTags attaches or overwrites tags on one or more resources.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
ec2.create_tags(
    Resources=["i-0abc123"],
    Tags=[{"Key": "Environment", "Value": "production"},
          {"Key": "Owner", "Value": "checkout-team"}],
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, CreateTagsCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
await ec2.send(new CreateTagsCommand({
  Resources: ["i-0abc123"],
  Tags: [{ Key: "Environment", Value: "production" },
         { Key: "Owner", Value: "checkout-team" }],
}));

CreateTags is idempotent per key: setting an existing key overwrites its value.
Resources accepts many ids, so you can tag a batch in one call.
Prefer tagging at launch (TagSpecifications on RunInstances) so no instance is ever untagged.
Tags are the backbone of cost allocation, access control, and cleanup.

7. Remove Tags

DeleteTags removes tags; omit Value to delete a key regardless of its value.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
ec2.delete_tags(
    Resources=["i-0abc123"],
    Tags=[{"Key": "Owner"}],   # no Value: delete regardless of value
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DeleteTagsCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
await ec2.send(new DeleteTagsCommand({
  Resources: ["i-0abc123"],
  Tags: [{ Key: "Owner" }],   // no Value: delete regardless of value
}));

Omitting Value deletes the key whatever its value; supplying Value deletes only if it matches.
DeleteTags is safe on a key that does not exist - it simply does nothing.
Like CreateTags, it accepts multiple resource ids at once.
There is no "rename tag" call; delete the old key and create the new one.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3), so the mechanics translate one to one.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-ec2 (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role with ec2:Describe* and ec2:CreateTags.
Most examples are read-only; the tagging examples make small, reversible changes.

Basic Examples

1. Describe All Instances (and Flatten the Shape)

DescribeInstances groups instances under Reservations, so you almost always flatten it.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_instances()
for reservation in resp["Reservations"]:
    for inst in reservation["Instances"]:
        print(inst["InstanceId"], inst["State"]["Name"])

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeInstancesCommand({}));
for (const r of resp.Reservations ?? []) {
  for (const inst of r.Instances ?? []) {
    console.log(inst.InstanceId, inst.State?.Name);
  }
}

Instances are nested Reservations[].Instances[], not a flat list.
A reservation groups instances launched by a single RunInstances call.
With no arguments this returns every instance in the region, including terminated ones for a short window.
Flatten with a nested loop or a comprehension before working with the data.

2. Filter Server-Side by State

Push the filter to AWS with Filters instead of downloading everything and filtering locally.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_instances(
    Filters=[{"Name": "instance-state-name", "Values": ["running"]}],
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeInstancesCommand({
  Filters: [{ Name: "instance-state-name", Values: ["running"] }],
}));

Filtering server-side returns less data and is faster and cheaper than client-side filtering.
Values is a list, so ["running", "stopped"] matches either.
Multiple filter objects are combined with AND; values within one filter are OR.
Filter names are documented per API and use hyphenated keys like instance-state-name.

3. Filter by Tag

Select a subset of your fleet using the special tag:Key filter name.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_instances(
    Filters=[{"Name": "tag:Environment", "Values": ["production"]}],
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeInstancesCommand({
  Filters: [{ Name: "tag:Environment", Values: ["production"] }],
}));

tag:<Key> matches instances whose tag Key has one of the given values.
Use tag-key to match on the presence of a key regardless of value.
Tag filtering is how most fleet automation scopes itself to the right instances.
Tag keys are case-sensitive, so Environment and environment are different.

Related: EC2 via SDK Best Practices - a consistent tagging scheme to filter against.

4. Read Common Instance Fields

The instance object carries far more than an id; here are the fields you reach for most.

# --- Python (boto3) ---
inst = resp["Reservations"][0]["Instances"][0]
print(inst["InstanceType"])        # e.g. t3.micro
print(inst["PrivateIpAddress"])
print(inst.get("PublicIpAddress")) # may be absent
print(inst["Placement"]["AvailabilityZone"])

// --- TypeScript (AWS SDK v3) ---
const inst = resp.Reservations?.[0].Instances?.[0];
console.log(inst?.InstanceType);        // e.g. t3.micro
console.log(inst?.PrivateIpAddress);
console.log(inst?.PublicIpAddress);     // may be undefined
console.log(inst?.Placement?.AvailabilityZone);

PublicIpAddress is absent for instances without a public IP, so guard for it.
Placement.AvailabilityZone tells you which AZ the instance runs in.
Tags is a list of {Key, Value} objects, not a map, so convert it if you want lookups.
LaunchTime is a timezone-aware timestamp useful for age-based cleanup.

Intermediate Examples

5. Paginate a Large Fleet

Beyond a page size, results are paged; use a paginator or a NextToken loop.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
paginator = ec2.get_paginator("describe_instances")
for page in paginator.paginate():
    for r in page["Reservations"]:
        for inst in r["Instances"]:
            print(inst["InstanceId"])

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
let token: string | undefined;
do {
  const page = await ec2.send(new DescribeInstancesCommand({ NextToken: token }));
  for (const r of page.Reservations ?? []) {
    for (const inst of r.Instances ?? []) console.log(inst.InstanceId);
  }
  token = page.NextToken;
} while (token);

boto3 paginators hide the token loop entirely - always prefer them.
SDK v3 also ships paginateDescribeInstances if you want the same convenience.
Never assume one call returns everything; a busy account will page.
Pagination is per API and each has its own MaxResults ceiling.

6. Add Tags to an Instance

CreateTags attaches or overwrites tags on one or more resources.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
ec2.create_tags(
    Resources=["i-0abc123"],
    Tags=[{"Key": "Environment", "Value": "production"},
          {"Key": "Owner", "Value": "checkout-team"}],
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, CreateTagsCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
await ec2.send(new CreateTagsCommand({
  Resources: ["i-0abc123"],
  Tags: [{ Key: "Environment", Value: "production" },
         { Key: "Owner", Value: "checkout-team" }],
}));

CreateTags is idempotent per key: setting an existing key overwrites its value.
Resources accepts many ids, so you can tag a batch in one call.
Prefer tagging at launch (TagSpecifications on RunInstances) so no instance is ever untagged.
Tags are the backbone of cost allocation, access control, and cleanup.

7. Remove Tags

DeleteTags removes tags; omit Value to delete a key regardless of its value.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
ec2.delete_tags(
    Resources=["i-0abc123"],
    Tags=[{"Key": "Owner"}],   # no Value: delete regardless of value
)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DeleteTagsCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
await ec2.send(new DeleteTagsCommand({
  Resources: ["i-0abc123"],
  Tags: [{ Key: "Owner" }],   // no Value: delete regardless of value
}));

Omitting Value deletes the key whatever its value; supplying Value deletes only if it matches.
DeleteTags is safe on a key that does not exist - it simply does nothing.
Like CreateTags, it accepts multiple resource ids at once.
There is no "rename tag" call; delete the old key and create the new one.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

EC2 Deep Dive Basics

Buscar na documentação

EC2 Deep Dive Basics