AWS ELB - OpenSRE Documentation

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 (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, then ensure alerts resolve sources with target group or load balancer ARNs.

Environment variables

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

{
  "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

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.

​Overview

​Prerequisites

​Setup

​Environment variables

​Credentials

​IAM permissions

​Tools

​Use cases

​Gotcha

​Verify

​Troubleshooting

​Security