Skip navigation links

Package software.amazon.awscdk.services.elasticloadbalancingv2

Amazon Elastic Load Balancing V2 Construct Library

See: Description

Package software.amazon.awscdk.services.elasticloadbalancingv2 Description

Amazon Elastic Load Balancing V2 Construct Library

---

cfn-resources: Stable

cdk-constructs: Stable

The @aws-cdk/aws-elasticloadbalancingv2 package provides constructs for configuring application and network load balancers.

For more information, see the AWS documentation for Application Load Balancers and Network Load Balancers.

Defining an Application Load Balancer

You define an application load balancer by creating an instance of ApplicationLoadBalancer, adding a Listener to the load balancer and adding Targets to the Listener: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.aws_ec2;
 import software.amazon.awscdk.aws_elasticloadbalancingv2;
 import aws.cdk.lib.aws.autoscaling.AutoScalingGroup;
 
 
 // ...
 
 Vpc vpc = new Vpc(...);
 
 // Create the load balancer in a VPC. 'internetFacing' is 'false'
 // by default, which creates an internal load balancer.
 ApplicationLoadBalancer lb = new ApplicationLoadBalancer(this, "LB", new ApplicationLoadBalancerProps()
         .vpc(vpc)
         .internetFacing(true));
 
 // Add a listener and open up the load balancer's security group
 // to the world.
 ApplicationListener listener = lb.addListener("Listener", new BaseApplicationListenerProps()
         .port(80)
 
         // 'open: true' is the default, you can leave it out if you want. Set it
         // to 'false' and use `listener.connections` if you want to be selective
         // about who can access the load balancer.
         .open(true));
 
 // Create an AutoScaling group and add it as a load balancing
 // target to the listener.
 AutoScalingGroup asg = new AutoScalingGroup(...);
 listener.addTargets("ApplicationFleet", new AddApplicationTargetsProps()
         .port(8080)
         .targets(asList(asg)));

The security groups of the load balancer and the target are automatically updated to allow the network traffic.

One (or more) security groups can be associated with the load balancer; if a security group isn't provided, one will be automatically created. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object securityGroup1 = SecurityGroup.Builder.create(stack, "SecurityGroup1").vpc(vpc).build();
 Object lb = ApplicationLoadBalancer.Builder.create(this, "LB")
         .vpc(vpc)
         .internetFacing(true)
         .securityGroup(securityGroup1)
         .build();
 
 Object securityGroup2 = SecurityGroup.Builder.create(stack, "SecurityGroup2").vpc(vpc).build();
 lb.addSecurityGroup(securityGroup2);

Conditions

It's possible to route traffic to targets based on conditions in the incoming HTTP request. For example, the following will route requests to the indicated AutoScalingGroup only if the requested host in the request is either for example.com/ok or example.com/path: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 listener.addTargets("Example.Com Fleet", Map.of(
         "priority", 10,
         "conditions", asList(ListenerCondition.hostHeaders(asList("example.com")), ListenerCondition.pathPatterns(asList("/ok", "/path"))),
         "port", 8080,
         "targets", asList(asg)));

A target with a condition contains either pathPatterns or hostHeader, or both. If both are specified, both conditions must be met for the requests to be routed to the given target. priority is a required field when you add targets with conditions. The lowest number wins.

Every listener must have at least one target without conditions, which is where all requests that didn't match any of the conditions will be sent.

Convenience methods and more complex Actions

Routing traffic from a Load Balancer to a Target involves the following steps:

Various methods on the Listener take care of this work for you to a greater or lesser extent:

Using addAction() gives you access to some of the features of an Elastic Load Balancer that the other two convenience methods don't:

Here's an example of serving a fixed response at the /ok URL: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 listener.addAction("Fixed", Map.of(
         "priority", 10,
         "conditions", asList(ListenerCondition.pathPatterns(asList("/ok"))),
         "action", ListenerAction.fixedResponse(200, Map.of(
                 "contentType", elbv2.ContentType.getTEXT_PLAIN(),
                 "messageBody", "OK"))));

Here's an example of using OIDC authentication before forwarding to a TargetGroup: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 listener.addAction("DefaultAction", Map.of(
         "action", ListenerAction.authenticateOidc(Map.of(
                 "authorizationEndpoint", "https://example.com/openid",
                 // Other OIDC properties here
                 // ...
                 "next", ListenerAction.forward(asList(myTargetGroup))))));

If you just want to redirect all incoming traffic on one port to another port, you can use the following code: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 lb.addRedirect(Map.of(
         "sourceProtocol", elbv2.ApplicationProtocol.getHTTPS(),
         "sourcePort", 8443,
         "targetProtocol", elbv2.ApplicationProtocol.getHTTP(),
         "targetPort", 8080));

If you do not provide any options for this method, it redirects HTTP port 80 to HTTPS port 443.

By default all ingress traffic will be allowed on the source port. If you want to be more selective with your ingress rules then set open: false and use the listener's connections object to selectively grant access to the listener.

Defining a Network Load Balancer

Network Load Balancers are defined in a similar way to Application Load Balancers: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.aws_ec2;
 import software.amazon.awscdk.aws_elasticloadbalancingv2;
 import software.amazon.awscdk.aws_autoscaling;
 
 
 // Create the load balancer in a VPC. 'internetFacing' is 'false'
 // by default, which creates an internal load balancer.
 NetworkLoadBalancer lb = new NetworkLoadBalancer(this, "LB", new NetworkLoadBalancerProps()
         .vpc(vpc)
         .internetFacing(true));
 
 // Add a listener on a particular port.
 NetworkListener listener = lb.addListener("Listener", new BaseNetworkListenerProps()
         .port(443));
 
 // Add targets on a particular port.
 listener.addTargets("AppFleet", new AddNetworkTargetsProps()
         .port(443)
         .targets(asList(asg)));

One thing to keep in mind is that network load balancers do not have security groups, and no automatic security group configuration is done for you. You will have to configure the security groups of the target yourself to allow traffic by clients and/or load balancer instances, depending on your target types. See Target Groups for your Network Load Balancers and Register targets with your Target Group for more information.

Targets and Target Groups

Application and Network Load Balancers organize load balancing targets in Target Groups. If you add your balancing targets (such as AutoScalingGroups, ECS services or individual instances) to your listener directly, the appropriate TargetGroup will be automatically created for you.

If you need more control over the Target Groups created, create an instance of ApplicationTargetGroup or NetworkTargetGroup, add the members you desire, and add it to the listener by calling addTargetGroups instead of addTargets.

addTargets() will always return the Target Group it just created for you: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object group = listener.addTargets("AppFleet", Map.of(
         "port", 443,
         "targets", asList(asg1)));
 
 group.addTarget(asg2);

Sticky sessions for your Application Load Balancer

By default, an Application Load Balancer routes each request independently to a registered target based on the chosen load-balancing algorithm. However, you can use the sticky session feature (also known as session affinity) to enable the load balancer to bind a user's session to a specific target. This ensures that all requests from the user during the session are sent to the same target. This feature is useful for servers that maintain state information in order to provide a continuous experience to clients. To use sticky sessions, the client must support cookies.

Application Load Balancers support both duration-based cookies (lb_cookie) and application-based cookies (app_cookie). The key to managing sticky sessions is determining how long your load balancer should consistently route the user's request to the same target. Sticky sessions are enabled at the target group level. You can use a combination of duration-based stickiness, application-based stickiness, and no stickiness across all of your target groups. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 // Target group with duration-based stickiness with load-balancer generated cookie
 Object tg1 = ApplicationTargetGroup.Builder.create(stack, "TG1")
         .targetType(elbv2.TargetType.getINSTANCE())
         .port(80)
         .stickinessCookieDuration(cdk.Duration.minutes(5))
         .vpc(vpc)
         .build();
 
 // Target group with application-based stickiness
 Object tg2 = ApplicationTargetGroup.Builder.create(stack, "TG2")
         .targetType(elbv2.TargetType.getINSTANCE())
         .port(80)
         .stickinessCookieDuration(cdk.Duration.minutes(5))
         .stickinessCookieName("MyDeliciousCookie")
         .vpc(vpc)
         .build();

For more information see: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/sticky-sessions.html#application-based-stickiness

Setting the target group protocol version

By default, Application Load Balancers send requests to targets using HTTP/1.1. You can use the protocol version to send requests to targets using HTTP/2 or gRPC. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object tg = ApplicationTargetGroup.Builder.create(stack, "TG")
         .targetType(elbv2.TargetType.getIP())
         .port(50051)
         .protocol(elbv2.ApplicationProtocol.getHTTP())
         .protocolVersion(elbv2.ApplicationProtocolVersion.getGRPC())
         .healthCheck(Map.of(
                 "enabled", true,
                 "healthyGrpcCodes", "0-99"))
         .vpc(vpc)
         .build();

Using Lambda Targets

To use a Lambda Function as a target, use the integration class in the @aws-cdk/aws-elasticloadbalancingv2-targets package: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.aws_lambda;
 import software.amazon.awscdk.aws_elasticloadbalancingv2;
 import software.amazon.awscdk.aws_elasticloadbalancingv2_targets;
 
 
 Function lambdaFunction = new Function(...);
 ApplicationLoadBalancer lb = new ApplicationLoadBalancer(...);
 
 ApplicationListener listener = lb.addListener("Listener", new BaseApplicationListenerProps().port(80));
 listener.addTargets("Targets", new AddApplicationTargetsProps()
         .targets(asList(new LambdaTarget(lambdaFunction)))
 
         // For Lambda Targets, you need to explicitly enable health checks if you
         // want them.
         .healthCheck(new HealthCheck()
                 .enabled(true)));

Only a single Lambda function can be added to a single listener rule.

Configuring Health Checks

Health checks are configured upon creation of a target group: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 listener.addTargets("AppFleet", Map.of(
         "port", 8080,
         "targets", asList(asg),
         "healthCheck", Map.of(
                 "path", "/ping",
                 "interval", cdk.Duration.minutes(1))));

The health check can also be configured after creation by calling configureHealthCheck() on the created object.

No attempts are made to configure security groups for the port you're configuring a health check for, but if the health check is on the same port you're routing traffic to, the security group already allows the traffic. If not, you will have to configure the security groups appropriately: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 listener.addTargets("AppFleet", Map.of(
         "port", 8080,
         "targets", asList(asg),
         "healthCheck", Map.of(
                 "port", 8088)));
 
 listener.connections.allowFrom(lb, ec2.Port.tcp(8088));

Using a Load Balancer from a different Stack

If you want to put your Load Balancer and the Targets it is load balancing to in different stacks, you may not be able to use the convenience methods loadBalancer.addListener() and listener.addTargets().

The reason is that these methods will create resources in the same Stack as the object they're called on, which may lead to cyclic references between stacks. Instead, you will have to create an ApplicationListener in the target stack, or an empty TargetGroup in the load balancer stack that you attach your service to.

For an example of the alternatives while load balancing to an ECS service, see the ecs/cross-stack-load-balancer example.

Protocol for Load Balancer Targets

Constructs that want to be a load balancer target should implement IApplicationLoadBalancerTarget and/or INetworkLoadBalancerTarget, and provide an implementation for the function attachToXxxTargetGroup(), which can call functions on the load balancer and should return metadata about the load balancing target: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 attachToApplicationTargetGroup(targetGroup, ApplicationTargetGroup);LoadBalancerTargetProps;{
     targetGroup.registerConnectable(...);return Map.of(
             "targetType", TargetType.getInstance() | TargetType.getIp(),
             "targetJson", Map.of("id", , ..., "port", , ...))
 }

targetType should be one of Instance or Ip. If the target can be directly added to the target group, targetJson should contain the id of the target (either instance ID or IP address depending on the type) and optionally a port or availabilityZone override.

Application load balancer targets can call registerConnectable() on the target group to register themselves for addition to the load balancer's security group rules.

If your load balancer target requires that the TargetGroup has been associated with a LoadBalancer before registration can happen (such as is the case for ECS Services for example), take a resource dependency on targetGroup.loadBalancerDependency() as follows: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 // Make sure that the listener has been created, and so the TargetGroup
 // has been associated with the LoadBalancer, before 'resource' is created.
 resourced.addDependency(targetGroup.loadBalancerDependency());

Looking up Load Balancers and Listeners

You may look up load balancers and load balancer listeners by using one of the following lookup methods:

Load Balancer lookup options

You may look up a load balancer by ARN or by associated tags. When you look a load balancer up by ARN, that load balancer will be returned unless CDK detects that the load balancer is of the wrong type. When you look up a load balancer by tags, CDK will return the load balancer matching all specified tags. If more than one load balancer matches, CDK will throw an error requesting that you provide more specific criteria.

Look up a Application Load Balancer by ARN 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object loadBalancer = ApplicationLoadBalancer.fromLookup(stack, "ALB", Map.of(
         "loadBalancerArn", YOUR_ALB_ARN));

Look up an Application Load Balancer by tags 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object loadBalancer = ApplicationLoadBalancer.fromLookup(stack, "ALB", Map.of(
         "loadBalancerTags", Map.of(
                 // Finds a load balancer matching all tags.
                 "some", "tag",
                 "someother", "tag")));

Load Balancer Listener lookup options

You may look up a load balancer listener by the following criteria:

The lookup method will return the matching listener. If more than one listener matches, CDK will throw an error requesting that you specify additional criteria.

Look up a Listener by associated Load Balancer, Port, and Protocol 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object listener = ApplicationListener.fromLookup(stack, "ALBListener", Map.of(
         "loadBalancerArn", YOUR_ALB_ARN,
         "listenerProtocol", ApplicationProtocol.getHTTPS(),
         "listenerPort", 443));

Look up a Listener by associated Load Balancer Tag, Port, and Protocol 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object listener = ApplicationListener.fromLookup(stack, "ALBListener", Map.of(
         "loadBalancerTags", Map.of(
                 "Cluster", "MyClusterName"),
         "listenerProtocol", ApplicationProtocol.getHTTPS(),
         "listenerPort", 443));

Look up a Network Listener by associated Load Balancer Tag, Port, and Protocol 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object listener = NetworkListener.fromLookup(stack, "ALBListener", Map.of(
         "loadBalancerTags", Map.of(
                 "Cluster", "MyClusterName"),
         "listenerProtocol", Protocol.getTCP(),
         "listenerPort", 12345));
Skip navigation links

Copyright © 2021. All rights reserved.