> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS EC2

> Discover EC2 instances by tag, tier, or VPC to map application tiers and investigate non-Kubernetes alerts

OpenSRE uses AWS EC2 to discover virtual machine instances, filter them by tag (such as `tier`), instance IDs, or VPC, and group instances into application tiers (such as web or worker). This helps answer questions like "which application tier(s) plausibly drive load on this RDS?" when investigating non-Kubernetes alerts or bridging load balancers (ELB) and databases (RDS).

All EC2 API calls are read-only and routed through the shared `aws_sdk_client` allowlist, so the integration cannot mutate your EC2 resources.

## Prerequisites

* AWS credentials configured per the [AWS integration](/docs/aws) (role ARN recommended)
* An EC2 environment with tagged instances, explicit instance IDs, or a VPC you want OpenSRE to inspect
* IAM permissions for `ec2:DescribeInstances`

## Setup

### Environment variables

```bash theme={null}
AWS_REGION=us-east-1
```

| Variable     | Default     | Description                           |
| ------------ | ----------- | ------------------------------------- |
| `AWS_REGION` | `us-east-1` | AWS region the EC2 instances live in. |

The tool accepts parameter hints from the resolved `ec2` source:

* `tiers`: List of tier names in the resolved `ec2` source (e.g. `["web"]` or `["web", "worker"]`). The parameter extractor maps a single item to the singular `tier` tool argument, or leaves `tier` empty when multiple tiers are in scope so instances across all tiers are enumerated and returned grouped in `by_tier`.
* `instance_ids`: List of explicit EC2 instance IDs.
* `vpc_id`: VPC ID filter to limit discovery to a specific network.
* `region`: AWS region override (defaults to `AWS_REGION` or `us-east-1`).

## IAM permissions

The integration only needs read-only EC2 describe permissions:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances"
      ],
      "Resource": "*"
    }
  ]
}
```

Attach this policy to the same IAM role or user already configured for the [AWS integration](/docs/aws). If you are already using the AWS managed `ReadOnlyAccess` policy, `ec2:DescribeInstances` is already included.

## Verify

```bash theme={null}
opensre integrations verify aws
```

EC2 shares the AWS integration's credential check — there is no separate `ec2` verify target. A successful AWS verify confirms your AWS credentials are valid; the EC2 tool becomes available whenever `tiers`, `instance_ids`, `vpc_id`, or `_backend` is present in the resolved `ec2` source.

Expected output:

```
Service: aws
Status: passed
Detail: Authenticated via assume-role in us-east-1 as arn:aws:iam::123456789012:role/OpenSREReadOnly (account 123456789012)
```

## Tools

| Tool                   | AWS API call            | What it returns                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ec2_instances_by_tag` | `ec2:DescribeInstances` | Active EC2 instances filtered by `tier` tag, instance IDs, or `vpc_id`. Returns per-instance metadata (ID, tier, ASG, private IP, VPC, subnet, AZ, state, instance type, security groups), a `by_tier` mapping of tier name to instance IDs, `tiers_detected`, and a precomputed summary (counts by tier, total active instances, primary tier, VPCs in scope, AZs in scope). |

The tool becomes available to the planner whenever `tiers`, `instance_ids`, `vpc_id`, or `_backend` is present in the resolved `ec2` sources.

### Use cases

* Discovering EC2 application tiers when investigating a non-Kubernetes alert
* Mapping a tier name (`web`, `worker`, etc.) to its active instance IDs
* Bridging EC2 → RDS when answering "which application tier drives database load"

## Gotcha

Terminated or stopped EC2 instances (`terminated`, `stopped`, `stopping`, `shutting-down`) are automatically excluded from the tool's results so they do not distort load-attribution or topology analysis. If an expected instance does not appear in the returned list, verify that the instance is in the `running` state and properly tagged with `tier` or `Tier`. Additionally, at least one filter (`tier`, `instance_ids`, or `vpc_id`) must be provided in the tool call or resolved sources, or the tool will return an unavailable status.