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

## Overview

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/integrations/cloud/aws) (role ARN recommended for verify; ambient credentials for tool calls)
* An ELB v2 (ALB or NLB) target group you want OpenSRE to investigate
* IAM permissions for the two ELB describe actions listed below

## Setup

ELB has no separate setup target. Configure the [AWS integration](/docs/integrations/cloud/aws), then ensure alerts resolve sources with target group or load balancer ARNs.

### 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).

## Credentials

ELB uses the same AWS account as the [AWS integration](/docs/integrations/cloud/aws). Tool calls use the ambient boto3 credential chain (environment keys, shared credentials profile, or attached instance/task role). They do **not** assume `AWS_ROLE_ARN` for the API call.

### 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 identity the OpenSRE process runs as (and to the role used by `opensre integrations verify aws` if you use assume-role). If you already use the AWS managed `ReadOnlyAccess` policy, both actions are covered.

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

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

## Troubleshooting

| Symptom                                          | Fix                                                                                               |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Tool never selected**                          | Ensure resolved sources include `target_group_arns`, `target_group_arn`, or `load_balancer_arn`   |
| **Healthy targets look fine but traffic is bad** | Pass the full `target_group_arns` list for multi-TG ALBs — a single ARN can miss unhealthy groups |
| **AccessDenied**                                 | Attach `DescribeTargetGroups` and `DescribeTargetHealth` to the ambient identity OpenSRE runs as  |
| **Wrong region**                                 | Set `AWS_REGION` to the region where the load balancer lives                                      |

## Security

* All ELB API calls are read-only.
* Prefer a least-privilege IAM policy with only the two describe actions above if you do not need broader AWS access.
* Store AWS credentials in `.env` or your secret manager — not in source control.