Application Load Balancer (ALB)

[GarrettBeatty]

Application Load Balancer (ALB) Support for Lambda Annotations

#2269

Overview

This PR adds a new [ALBApi] attribute to the Lambda Annotations framework, enabling developers to configure Lambda functions as targets behind an Application Load Balancer using the same declarative, attribute-driven approach already available for API Gateway ([HttpApi], [RestApi]) and SQS ([SQSEvent]).

User Experience

Developers can now wire a Lambda function to an ALB listener with a single attribute:

[LambdaFunction(ResourceName = "ALBHello", MemorySize = 256, Timeout = 15)]
[ALBApi("@MyListener", "/hello", 1)]
public ApplicationLoadBalancerResponse Hello(ApplicationLoadBalancerRequest request, ILambdaContext context)
{
    return new ApplicationLoadBalancerResponse
    {
        StatusCode = 200,
        Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } },
        Body = "{\"message\": \"Hello from ALB Lambda!\"}"
    };
}

The source generator automatically creates the necessary CloudFormation resources — AWS::Lambda::Permission, AWS::ElasticLoadBalancingV2::TargetGroup, and AWS::ElasticLoadBalancingV2::ListenerRule — and keeps them in sync with the code.

ALBApi Attribute Properties

Property	Required	Description
ListenerArn	✅	ALB listener ARN or @ResourceName template reference
PathPattern	✅	Path pattern for routing (e.g., "/api/orders/*")
Priority	✅	Listener rule priority (1–50000)
MultiValueHeaders		Enable multi-value headers on the target group
HostHeader		Host header condition for the listener rule
HttpMethod		HTTP method condition (e.g., "GET", "POST")
ResourceName		Custom CloudFormation resource name prefix

Key Design Decisions

• Standalone CloudFormation resources — Unlike API Gateway events which map to SAM event types under the function's Events property, ALB integration requires generating separate top-level CloudFormation resources (TargetGroup, ListenerRule, Permission). This is because AWS SAM does not have a built-in ALB event type.
• Existing listener required — The attribute references an ALB listener that must already exist (either in the same template or via ARN). It does not create the ALB/VPC infrastructure.
• @ResourceName pattern — Follows the same convention as other annotations attributes for referencing CloudFormation resources using Ref.

Testing

• 60 ALB-related unit tests passing (attribute validation, model, writer, snapshot)
• Integration test project deploys successfully to AWS with VPC, ALB, listener, and Lambda targets

[Copilot]

Pull request overview

Adds first-class Application Load Balancer (ALB) support to the Lambda Annotations source generator, including documentation, generator logic, and both unit + integration test coverage.

Changes:

• Introduces ALBApiAttribute and updates the source generator to emit ALB-related CloudFormation resources (TargetGroup, ListenerRule, Lambda Permission).
• Adds source-generator unit tests and snapshots for ALB generation.
• Adds a new ALB test serverless app plus integration tests and deployment assets.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
Libraries/test/TestServerlessApp/ALBEventExamples/ValidALBEvents.cs.txt	Adds ALB-valid sample inputs used by source generator verification tests.
Libraries/test/TestServerlessApp.ALB/TestServerlessApp.ALB.csproj	New ALB test Lambda project referencing annotations + ALB events libraries.
Libraries/test/TestServerlessApp.ALB/serverless.template	New integration-test template defining VPC/ALB infra and generated Lambda resources.
Libraries/test/TestServerlessApp.ALB/aws-lambda-tools-defaults.json	Adds defaults used by dotnet lambda deploy-serverless for ALB test deployment.
Libraries/test/TestServerlessApp.ALB/AssemblyAttributes.cs	Sets Lambda serializer for the ALB test app.
Libraries/test/TestServerlessApp.ALB/ALBFunctions.cs	Implements hello + health endpoints annotated with ALBApi.
Libraries/test/TestServerlessApp.ALB.IntegrationTests/TestServerlessApp.ALB.IntegrationTests.csproj	New xUnit integration test project for ALB scenario.
Libraries/test/TestServerlessApp.ALB.IntegrationTests/DeploymentScript.ps1	Deploys the ALB test stack (bucket + serverless deploy).
Libraries/test/TestServerlessApp.ALB.IntegrationTests/ALBTargetTests.cs	Exercises ALB endpoints and basic target-group existence checks.
Libraries/test/TestServerlessApp.ALB.IntegrationTests/ALBIntegrationTestContextFixtureCollection.cs	xUnit collection wiring for shared ALB fixture.
Libraries/test/TestServerlessApp.ALB.IntegrationTests/ALBIntegrationTestContextFixture.cs	Provisions/tears down ALB stack and exposes ALB DNS + clients.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/WriterTests/ALBEventsTests.cs	Adds CloudFormation writer tests for ALB resources and options.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/SourceGeneratorTests.cs	Adds Verify-based generator test for ALB events.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/Snapshots/ServerlessTemplates/albEvents.template	Snapshot of expected ALB CloudFormation output.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/Snapshots/ALB/ValidALBEvents_Hello_Generated.g.cs	Snapshot of generated handler for ALB hello method.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/Snapshots/ALB/ValidALBEvents_HandleRequest_Generated.g.cs	Snapshot of generated handler for ALB async method.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/CSharpSourceGeneratorVerifier.cs	Adds ALB events assembly reference to the Roslyn test harness.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/Amazon.Lambda.Annotations.SourceGenerators.Tests.csproj	Adds project reference for Amazon.Lambda.ApplicationLoadBalancerEvents.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/ALBApiModelTests.cs	Tests for TypeFullNames/EventType additions and ALB return-type detection.
Libraries/test/Amazon.Lambda.Annotations.SourceGenerators.Tests/ALBApiAttributeTests.cs	Unit tests for ALBApiAttribute defaults and validation.
Libraries/src/Amazon.Lambda.Annotations/README.md	Documents the new ALBApi attribute and generated resources.
Libraries/src/Amazon.Lambda.Annotations/ALB/ALBApiAttribute.cs	Introduces the ALB method attribute + validation logic.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Writers/CloudFormationWriter.cs	Generates ALB Permission/TargetGroup/ListenerRule resources in templates.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Validation/LambdaFunctionValidator.cs	Adds dependency validation for ALB events assembly.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/TypeFullNames.cs	Adds ALB-related type constants and includes ALBApi in event set.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/SyntaxReceiver.cs	Recognizes ALBApiAttribute as an event attribute for discovery.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/LambdaMethodModel.cs	Adds helper for detecting ALB response return types.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/GeneratedMethodModelBuilder.cs	Ensures ALB functions are modeled as returning ALB response types.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/EventTypeBuilder.cs	Adds ALB event type detection.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/EventType.cs	Adds EventType.ALB.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/Attributes/AttributeModelBuilder.cs	Builds ALBApi attribute models during analysis.
Libraries/src/Amazon.Lambda.Annotations.SourceGenerator/Models/Attributes/ALBApiAttributeBuilder.cs	Parses constructor + named args into ALBApiAttribute instances.
Libraries/Libraries.sln	Adds new ALB test projects to the solution.
Libraries/Amazon.Lambda.Annotations.slnf	Adds ALB-related projects to the solution filter.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[GarrettBeatty]

The reason we specify the listener instead of the actual ALB is because an ALB can have multiple listeners, and the listener is the one that has all of the configuration values

[normj]

The ALB attributes should act like the API Gateway attributes supporting all of the FromX attributes and by supporting that the customer function can have any number of parameters. Althought a difference I see is ALB does not support the idea of resource path templates like API Gateway does. So you might have to exclude that and if there are any parameters not mapping to something that should cause a diagnostic error.

[GarrettBeatty]

updated to add support for fromX and other attributes. but one issue is that all of these attributes are in api gateway namespace.

so in the users code they would need to import that (like this 3c2c696) which seems weird.

Should i create duplicate attributes or wondering if we can make breaking change to make it in some common namespace?

[GarrettBeatty]

i duplicated the attributes in 311bcd6 as per slack thread

[normj]

My understanding besides host-header you should be able to setup a role for any arbitrary header like the following:

      {
        "Field": "http-header",
        "HttpHeaderConfig": {
          "HttpHeaderName": "X-Environment",
          "Values": ["dev"]
        }
      }

I don't see an property on the attribute for setting that up.

[GarrettBeatty]

http header d4d45db

query string and source ip b297018

[philasmar]

missing the license header

[philasmar]

missing the license header

[philasmar]

missing the license header

[philasmar]

missing the license header

[philasmar]

not sure if we add a license header for the tt

[philasmar]

missing the license header

[philasmar]

missing the license header

[philasmar]

missing the license header

[philasmar]

nit: make this dotnet8

[philasmar]

nit: make this 512