class ApplicationLoadBalancer (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.ElasticLoadBalancingV2.ApplicationLoadBalancer`
Go	`github.com/aws/aws-cdk-go/awscdk/v2/awselasticloadbalancingv2#ApplicationLoadBalancer`
Java	`software.amazon.awscdk.services.elasticloadbalancingv2.ApplicationLoadBalancer`
Python	`aws_cdk.aws_elasticloadbalancingv2.ApplicationLoadBalancer`
TypeScript (source)	`aws-cdk-lib` » `aws_elasticloadbalancingv2` » `ApplicationLoadBalancer`

Implements IConstruct, IDependable, IResource, IApplicationLoadBalancer, ILoadBalancerV2, IConnectable

Define an Application Load Balancer.

Example

import { AutoScalingGroup } from 'aws-cdk-lib/aws-autoscaling';
declare const asg: AutoScalingGroup;
declare const vpc: ec2.Vpc;

// Create the load balancer in a VPC. 'internetFacing' is 'false'
// by default, which creates an internal load balancer.
const lb = new elbv2.ApplicationLoadBalancer(this, 'LB', {
  vpc,
  internetFacing: true
});

// Add a listener and open up the load balancer's security group
// to the world.
const listener = lb.addListener('Listener', {
  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.
listener.addTargets('ApplicationFleet', {
  port: 8080,
  targets: [asg]
});

Initializer

new ApplicationLoadBalancer(scope: Construct, id: string, props: ApplicationLoadBalancerProps)

Parameters

scope Construct
id string
props ApplicationLoadBalancerProps

Construct Props

Name	Type	Description
vpc	`IVpc`	The VPC network to place the load balancer in.
clientKeepAlive?	`Duration`	The client keep alive duration.
crossZoneEnabled?	`boolean`	Indicates whether cross-zone load balancing is enabled.
deletionProtection?	`boolean`	Indicates whether deletion protection is enabled.
denyAllIgwTraffic?	`boolean`	Indicates whether the load balancer blocks traffic through the Internet Gateway (IGW).
desyncMitigationMode?	`DesyncMitigationMode`	Determines how the load balancer handles requests that might pose a security risk to your application.
dropInvalidHeaderFields?	`boolean`	Indicates whether HTTP headers with invalid header fields are removed by the load balancer (true) or routed to targets (false).
http2Enabled?	`boolean`	Indicates whether HTTP/2 is enabled.
idleTimeout?	`Duration`	The load balancer idle timeout, in seconds.
internetFacing?	`boolean`	Whether the load balancer has an internet-routable address.
ipAddressType?	`IpAddressType`	The type of IP addresses to use.
loadBalancerName?	`string`	Name of the load balancer.
preserveHostHeader?	`boolean`	Indicates whether the Application Load Balancer should preserve the host header in the HTTP request and send it to the target without any change.
preserveXffClientPort?	`boolean`	Indicates whether the X-Forwarded-For header should preserve the source port that the client used to connect to the load balancer.
securityGroup?	`ISecurityGroup`	Security group to associate with this load balancer.
vpcSubnets?	`SubnetSelection`	Which subnets place the load balancer in.
wafFailOpen?	`boolean`	Indicates whether to allow a WAF-enabled load balancer to route requests to targets if it is unable to forward the request to AWS WAF.
xAmznTlsVersionAndCipherSuiteHeaders?	`boolean`	Indicates whether the two headers (x-amzn-tls-version and x-amzn-tls-cipher-suite), which contain information about the negotiated TLS version and cipher suite, are added to the client request before sending it to the target.
xffHeaderProcessingMode?	`XffHeaderProcessingMode`	Enables you to modify, preserve, or remove the X-Forwarded-For header in the HTTP request before the Application Load Balancer sends the request to the target.

vpc

Type: IVpc

The VPC network to place the load balancer in.

clientKeepAlive?

Type: Duration (optional, default: Duration.seconds(3600))

The client keep alive duration.

The valid range is 60 to 604800 seconds (1 minute to 7 days).

crossZoneEnabled?

Type: boolean (optional, default: false for Network Load Balancers and true for Application Load Balancers. This can not be false for Application Load Balancers.)

Indicates whether cross-zone load balancing is enabled.

deletionProtection?

Type: boolean (optional, default: false)

Indicates whether deletion protection is enabled.

denyAllIgwTraffic?

Type: boolean (optional, default: false for internet-facing load balancers and true for internal load balancers)

Indicates whether the load balancer blocks traffic through the Internet Gateway (IGW).

desyncMitigationMode?

Type: DesyncMitigationMode (optional, default: DesyncMitigationMode.DEFENSIVE)

Determines how the load balancer handles requests that might pose a security risk to your application.

dropInvalidHeaderFields?

Type: boolean (optional, default: false)

Indicates whether HTTP headers with invalid header fields are removed by the load balancer (true) or routed to targets (false).

http2Enabled?

Type: boolean (optional, default: true)

Indicates whether HTTP/2 is enabled.

idleTimeout?

Type: Duration (optional, default: 60)

The load balancer idle timeout, in seconds.

internetFacing?

Type: boolean (optional, default: false)

Whether the load balancer has an internet-routable address.

ipAddressType?

Type: IpAddressType (optional, default: IpAddressType.IPV4)

The type of IP addresses to use.

loadBalancerName?

Type: string (optional, default: Automatically generated name.)

Name of the load balancer.

preserveHostHeader?

Type: boolean (optional, default: false)

Indicates whether the Application Load Balancer should preserve the host header in the HTTP request and send it to the target without any change.

preserveXffClientPort?

Type: boolean (optional, default: false)

Indicates whether the X-Forwarded-For header should preserve the source port that the client used to connect to the load balancer.

securityGroup?

Type: ISecurityGroup (optional, default: A security group is created)

Security group to associate with this load balancer.

vpcSubnets?

Type: SubnetSelection (optional, default: the Vpc default strategy.)

Which subnets place the load balancer in.

wafFailOpen?

Type: boolean (optional, default: false)

Indicates whether to allow a WAF-enabled load balancer to route requests to targets if it is unable to forward the request to AWS WAF.

xAmznTlsVersionAndCipherSuiteHeaders?

Type: boolean (optional, default: false)

Indicates whether the two headers (x-amzn-tls-version and x-amzn-tls-cipher-suite), which contain information about the negotiated TLS version and cipher suite, are added to the client request before sending it to the target.

The x-amzn-tls-version header has information about the TLS protocol version negotiated with the client, and the x-amzn-tls-cipher-suite header has information about the cipher suite negotiated with the client.

Both headers are in OpenSSL format.

xffHeaderProcessingMode?

Type: XffHeaderProcessingMode (optional, default: XffHeaderProcessingMode.APPEND)

Enables you to modify, preserve, or remove the X-Forwarded-For header in the HTTP request before the Application Load Balancer sends the request to the target.

Properties

Name	Type	Description
connections	`Connections`	The network connections associated with this resource.
env	`ResourceEnvironment`	The environment this resource belongs to.
listeners	`ApplicationListener[]`	A list of listeners that have been added to the load balancer.
loadBalancerArn	`string`	The ARN of this load balancer.
loadBalancerCanonicalHostedZoneId	`string`	The canonical hosted zone ID of this load balancer.
loadBalancerDnsName	`string`	The DNS name of this load balancer.
loadBalancerFullName	`string`	The full name of this load balancer.
loadBalancerName	`string`	The name of this load balancer.
loadBalancerSecurityGroups	`string[]`
metrics	`IApplicationLoadBalancerMetrics`	All metrics available for this load balancer.
node	`Node`	The tree node.
stack	`Stack`	The stack in which this resource is defined.
ipAddressType?	`IpAddressType`	The IP Address Type for this load balancer.
vpc?	`IVpc`	The VPC this load balancer has been created in.

connections

Type: Connections

The network connections associated with this resource.

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

listeners

Type: ApplicationListener[]

A list of listeners that have been added to the load balancer.

This list is only valid for owned constructs.

loadBalancerArn

Type: string

The ARN of this load balancer.

Example value: arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-internal-load-balancer/50dc6c495c0c9188

loadBalancerCanonicalHostedZoneId

Type: string

The canonical hosted zone ID of this load balancer.

Example value: Z2P70J7EXAMPLE

loadBalancerDnsName

Type: string

The DNS name of this load balancer.

Example value: my-load-balancer-424835706.us-west-2.elb.amazonaws.com

loadBalancerFullName

Type: string

The full name of this load balancer.

Example value: app/my-load-balancer/50dc6c495c0c9188

loadBalancerName

Type: string

The name of this load balancer.

Example value: my-load-balancer

loadBalancerSecurityGroups

Type: string[]

metrics

Type: IApplicationLoadBalancerMetrics

All metrics available for this load balancer.

node

Type: Node

The tree node.

stack

Type: Stack

The stack in which this resource is defined.

ipAddressType?

Type: IpAddressType (optional)

The IP Address Type for this load balancer.

vpc?

Type: IVpc (optional)

The VPC this load balancer has been created in.

This property is always defined (not null or undefined) for sub-classes of BaseLoadBalancer.

Methods

Name	Description
addListener(id, props)	Add a new listener to this load balancer.
addRedirect(props?)	Add a redirection listener to this load balancer.
addSecurityGroup(securityGroup)	Add a security group to this load balancer.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
logAccessLogs(bucket, prefix?)	Enable access logging for this load balancer.
logConnectionLogs(bucket, prefix?)	Enable connection logging for this load balancer.
metric(metricName, props?)⚠️	Return the given named metric for this Application Load Balancer.
metricActiveConnectionCount(props?)⚠️	The total number of concurrent TCP connections active from clients to the load balancer and from the load balancer to targets.
metricClientTlsNegotiationErrorCount(props?)⚠️	The number of TLS connections initiated by the client that did not establish a session with the load balancer.
metricConsumedLCUs(props?)⚠️	The number of load balancer capacity units (LCU) used by your load balancer.
metricElbAuthError(props?)⚠️	The number of user authentications that could not be completed.
metricElbAuthFailure(props?)⚠️	The number of user authentications that could not be completed because the IdP denied access to the user or an authorization code was used more than once.
metricElbAuthLatency(props?)⚠️	The time elapsed, in milliseconds, to query the IdP for the ID token and user info.
metricElbAuthSuccess(props?)⚠️	The number of authenticate actions that were successful.
metricHttpCodeElb(code, props?)⚠️	The number of HTTP 3xx/4xx/5xx codes that originate from the load balancer.
metricHttpCodeTarget(code, props?)⚠️	The number of HTTP 2xx/3xx/4xx/5xx response codes generated by all targets in the load balancer.
metricHttpFixedResponseCount(props?)⚠️	The number of fixed-response actions that were successful.
metricHttpRedirectCount(props?)⚠️	The number of redirect actions that were successful.
metricHttpRedirectUrlLimitExceededCount(props?)⚠️	The number of redirect actions that couldn't be completed because the URL in the response location header is larger than 8K.
metricIpv6ProcessedBytes(props?)⚠️	The total number of bytes processed by the load balancer over IPv6.
metricIpv6RequestCount(props?)⚠️	The number of IPv6 requests received by the load balancer.
metricNewConnectionCount(props?)⚠️	The total number of new TCP connections established from clients to the load balancer and from the load balancer to targets.
metricProcessedBytes(props?)⚠️	The total number of bytes processed by the load balancer over IPv4 and IPv6.
metricRejectedConnectionCount(props?)⚠️	The number of connections that were rejected because the load balancer had reached its maximum number of connections.
metricRequestCount(props?)⚠️	The number of requests processed over IPv4 and IPv6.
metricRuleEvaluations(props?)⚠️	The number of rules processed by the load balancer given a request rate averaged over an hour.
metricTargetConnectionErrorCount(props?)⚠️	The number of connections that were not successfully established between the load balancer and target.
metricTargetResponseTime(props?)⚠️	The time elapsed, in seconds, after the request leaves the load balancer until a response from the target is received.
metricTargetTLSNegotiationErrorCount(props?)⚠️	The number of TLS connections initiated by the load balancer that did not establish a session with the target.
removeAttribute(key)	Remove an attribute from the load balancer.
setAttribute(key, value?)	Set a non-standard attribute on the load balancer.
toString()	Returns a string representation of this construct.
static fromApplicationLoadBalancerAttributes(scope, id, attrs)	Import an existing Application Load Balancer.
static fromLookup(scope, id, options)	Look up an application load balancer.

addListener(id, props)

public addListener(id: string, props: BaseApplicationListenerProps): ApplicationListener

Parameters

id string
props BaseApplicationListenerProps

Returns

ApplicationListener

Add a new listener to this load balancer.

addRedirect(props?)

public addRedirect(props?: ApplicationLoadBalancerRedirectConfig): ApplicationListener

Parameters

props ApplicationLoadBalancerRedirectConfig

Returns

ApplicationListener

Add a redirection listener to this load balancer.

addSecurityGroup(securityGroup)

public addSecurityGroup(securityGroup: ISecurityGroup): void

Parameters

securityGroup ISecurityGroup

Add a security group to this load balancer.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

logAccessLogs(bucket, prefix?)

public logAccessLogs(bucket: IBucket, prefix?: string): void

Parameters

bucket IBucket
prefix string

Enable access logging for this load balancer.

A region must be specified on the stack containing the load balancer; you cannot enable logging on environment-agnostic stacks. See https://docs.aws.amazon.com/cdk/latest/guide/environments.html

logConnectionLogs(bucket, prefix?)

public logConnectionLogs(bucket: IBucket, prefix?: string): void

Parameters

bucket IBucket
prefix string

Enable connection logging for this load balancer.

A region must be specified on the stack containing the load balancer; you cannot enable logging on environment-agnostic stacks.

metric(metricName, props?)⚠️

public metric(metricName: string, props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.custom instead

Parameters

metricName string
props MetricOptions

Returns

Metric

Return the given named metric for this Application Load Balancer.

metricActiveConnectionCount(props?)⚠️

public metricActiveConnectionCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.activeConnectionCount instead

Parameters

props MetricOptions

Returns

Metric

The total number of concurrent TCP connections active from clients to the load balancer and from the load balancer to targets.

metricClientTlsNegotiationErrorCount(props?)⚠️

public metricClientTlsNegotiationErrorCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.clientTlsNegotiationErrorCount instead

Parameters

props MetricOptions

Returns

Metric

The number of TLS connections initiated by the client that did not establish a session with the load balancer.

Possible causes include a mismatch of ciphers or protocols.

metricConsumedLCUs(props?)⚠️

public metricConsumedLCUs(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.consumedLCUs instead

Parameters

props MetricOptions

Returns

Metric

The number of load balancer capacity units (LCU) used by your load balancer.

metricElbAuthError(props?)⚠️

public metricElbAuthError(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.elbAuthError instead

Parameters

props MetricOptions

Returns

Metric

The number of user authentications that could not be completed.

Because an authenticate action was misconfigured, the load balancer couldn't establish a connection with the IdP, or the load balancer couldn't complete the authentication flow due to an internal error.

metricElbAuthFailure(props?)⚠️

public metricElbAuthFailure(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.elbAuthFailure instead

Parameters

props MetricOptions

Returns

Metric

The number of user authentications that could not be completed because the IdP denied access to the user or an authorization code was used more than once.

metricElbAuthLatency(props?)⚠️

public metricElbAuthLatency(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.elbAuthLatency instead

Parameters

props MetricOptions

Returns

Metric

The time elapsed, in milliseconds, to query the IdP for the ID token and user info.

If one or more of these operations fail, this is the time to failure.

metricElbAuthSuccess(props?)⚠️

public metricElbAuthSuccess(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.elbAuthSuccess instead

Parameters

props MetricOptions

Returns

Metric

The number of authenticate actions that were successful.

This metric is incremented at the end of the authentication workflow, after the load balancer has retrieved the user claims from the IdP.

metricHttpCodeElb(code, props?)⚠️

public metricHttpCodeElb(code: HttpCodeElb, props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.httpCodeElb instead

Parameters

code HttpCodeElb
props MetricOptions

Returns

Metric

The number of HTTP 3xx/4xx/5xx codes that originate from the load balancer.

This does not include any response codes generated by the targets.

metricHttpCodeTarget(code, props?)⚠️

public metricHttpCodeTarget(code: HttpCodeTarget, props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.httpCodeTarget instead

Parameters

code HttpCodeTarget
props MetricOptions

Returns

Metric

The number of HTTP 2xx/3xx/4xx/5xx response codes generated by all targets in the load balancer.

This does not include any response codes generated by the load balancer.

metricHttpFixedResponseCount(props?)⚠️

public metricHttpFixedResponseCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.httpFixedResponseCount instead

Parameters

props MetricOptions

Returns

Metric

The number of fixed-response actions that were successful.

metricHttpRedirectCount(props?)⚠️

public metricHttpRedirectCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.httpRedirectCount instead

Parameters

props MetricOptions

Returns

Metric

The number of redirect actions that were successful.

metricHttpRedirectUrlLimitExceededCount(props?)⚠️

public metricHttpRedirectUrlLimitExceededCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.httpRedirectUrlLimitExceededCount instead

Parameters

props MetricOptions

Returns

Metric

The number of redirect actions that couldn't be completed because the URL in the response location header is larger than 8K.

metricIpv6ProcessedBytes(props?)⚠️

public metricIpv6ProcessedBytes(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.ipv6ProcessedBytes instead

Parameters

props MetricOptions

Returns

Metric

The total number of bytes processed by the load balancer over IPv6.

metricIpv6RequestCount(props?)⚠️

public metricIpv6RequestCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.ipv6RequestCount instead

Parameters

props MetricOptions

Returns

Metric

The number of IPv6 requests received by the load balancer.

metricNewConnectionCount(props?)⚠️

public metricNewConnectionCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.newConnectionCount instead

Parameters

props MetricOptions

Returns

Metric

The total number of new TCP connections established from clients to the load balancer and from the load balancer to targets.

metricProcessedBytes(props?)⚠️

public metricProcessedBytes(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.processedBytes instead

Parameters

props MetricOptions

Returns

Metric

The total number of bytes processed by the load balancer over IPv4 and IPv6.

metricRejectedConnectionCount(props?)⚠️

public metricRejectedConnectionCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.rejectedConnectionCount instead

Parameters

props MetricOptions

Returns

Metric

The number of connections that were rejected because the load balancer had reached its maximum number of connections.

metricRequestCount(props?)⚠️

public metricRequestCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.requestCount instead

Parameters

props MetricOptions

Returns

Metric

The number of requests processed over IPv4 and IPv6.

This count includes only the requests with a response generated by a target of the load balancer.

metricRuleEvaluations(props?)⚠️

public metricRuleEvaluations(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.ruleEvaluations instead

Parameters

props MetricOptions

Returns

Metric

The number of rules processed by the load balancer given a request rate averaged over an hour.

metricTargetConnectionErrorCount(props?)⚠️

public metricTargetConnectionErrorCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.targetConnectionErrorCount instead

Parameters

props MetricOptions

Returns

Metric

The number of connections that were not successfully established between the load balancer and target.

metricTargetResponseTime(props?)⚠️

public metricTargetResponseTime(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.targetResponseTime instead

Parameters

props MetricOptions

Returns

Metric

The time elapsed, in seconds, after the request leaves the load balancer until a response from the target is received.

metricTargetTLSNegotiationErrorCount(props?)⚠️

public metricTargetTLSNegotiationErrorCount(props?: MetricOptions): Metric

⚠️ Deprecated: Use ApplicationLoadBalancer.metrics.targetTLSNegotiationErrorCount instead

Parameters

props MetricOptions

Returns

Metric

The number of TLS connections initiated by the load balancer that did not establish a session with the target.

Possible causes include a mismatch of ciphers or protocols.

removeAttribute(key)

public removeAttribute(key: string): void

Parameters

key string

Remove an attribute from the load balancer.

setAttribute(key, value?)

public setAttribute(key: string, value?: string): void

Parameters

key string
value string

Set a non-standard attribute on the load balancer.

toString()

public toString(): string

Returns

string

Returns a string representation of this construct.

static fromApplicationLoadBalancerAttributes(scope, id, attrs)

public static fromApplicationLoadBalancerAttributes(scope: Construct, id: string, attrs: ApplicationLoadBalancerAttributes): IApplicationLoadBalancer

Parameters

scope Construct
id string
attrs ApplicationLoadBalancerAttributes

Returns

IApplicationLoadBalancer

Import an existing Application Load Balancer.

static fromLookup(scope, id, options)

public static fromLookup(scope: Construct, id: string, options: ApplicationLoadBalancerLookupOptions): IApplicationLoadBalancer

Parameters

scope Construct
id string
options ApplicationLoadBalancerLookupOptions

Returns

IApplicationLoadBalancer

Look up an application load balancer.