> ## 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 ELB

> Map a load balancer to its EC2 targets and surface unhealthy targets during incidents

OpenSRE uses AWS Elastic Load Balancing (ELB v2 — ALB/NLB) to bridge a public-facing alert (DNS/LB) down to the EC2 instances behind it. It maps target groups to registered targets and flags unhealthy or draining targets, pairing with the EC2 tools to identify which application tier is driving load on a downstream dependency.

All ELB API calls are read-only and routed through the shared `aws_sdk_client` allowlist, so the integration cannot mutate your load balancers or target groups.

## Prerequisites

* AWS credentials configured per the [AWS integration](/docs/aws) (role ARN recommended)
* An ELB v2 (ALB or NLB) target group you want OpenSRE to investigate
* IAM permissions for the two ELB describe actions listed below

## Setup

### Environment variables

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

| Variable     | Default     | Description                                             |
| ------------ | ----------- | ------------------------------------------------------- |
| `AWS_REGION` | `us-east-1` | AWS region the load balancer and target groups live in. |

The tool accepts `target_group_arns` (canonical), the singular `target_group_arn` alias, and `load_balancer_arn` as parameters.

When invoked via resolved sources, it reads `target_group_arns` and `load_balancer_arns` from the resolved `ec2` source (using the first load balancer ARN).

## IAM permissions

The integration only needs two read-only ELB v2 actions:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticloadbalancing:DescribeTargetGroups",
        "elasticloadbalancing:DescribeTargetHealth"
      ],
      "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, both actions are already covered.

## Verify

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

ELB shares the AWS integration's connection check — there is no separate `elb` verify target. A successful AWS verify confirms credentials are valid; the ELB tool itself becomes available once a target group ARN or load balancer ARN is present in the resolved sources.

## Tools

| Tool                    | AWS API calls                                                                            | What it returns                                                                                                                                                                                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_elb_target_health` | `elasticloadbalancing:DescribeTargetGroups`, `elasticloadbalancing:DescribeTargetHealth` | Target groups in scope, healthy targets, unhealthy/draining targets, deduplicated EC2 instance IDs behind the load balancer, and a precomputed summary (total targets, healthy/unhealthy counts, healthy ratio %, unhealthy states, target group count). |

The tool becomes available to the planner whenever `target_group_arns`, `target_group_arn`, or `load_balancer_arn` is present in the resolved `ec2` sources.

### Use cases

* Mapping a target group ARN or load balancer ARN to the EC2 instance IDs serving traffic
* Identifying unhealthy or draining targets correlated with a request-path alert
* Bridging DNS → LB → EC2 when investigating a non-Kubernetes topology

## Gotcha

Multi-target-group ALBs are common — a single ALB can front several listener rules, each pointing at a different target group. Pass the full `target_group_arns` list rather than a single `target_group_arn` if the load balancer has more than one target group, otherwise the tool only reports health for the one target group you named and unhealthy targets on the other groups will be silently missed.