Menu
Elastic Load Balancing
API Reference (API Version 2015-12-01)

CreateListener

Creates a listener for the specified Application Load Balancer.

You can create up to 10 listeners per load balancer.

To update a listener, use ModifyListener. When you are finished with a listener, you can delete it using DeleteListener. If you are finished with both the listener and the load balancer, you can delete them both using DeleteLoadBalancer.

For more information, see Listeners for Your Application Load Balancers in the Application Load Balancers Guide.

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

Certificates.member.N

The SSL server certificate. You must provide exactly one certificate if the protocol is HTTPS.

Type: Array of Certificate objects

Required: No

DefaultActions.member.N

The default action for the listener.

Type: Array of Action objects

Required: Yes

LoadBalancerArn

The Amazon Resource Name (ARN) of the load balancer.

Type: String

Required: Yes

Port

The port on which the load balancer is listening.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 65535.

Required: Yes

Protocol

The protocol for connections from clients to the load balancer.

Type: String

Valid Values: HTTP | HTTPS

Required: Yes

SslPolicy

The security policy that defines which ciphers and protocols are supported. The default is the current predefined security policy.

Type: String

Required: No

Response Elements

The following element is returned by the service.

Listeners.member.N

Information about the listener.

Type: Array of Listener objects

Errors

For information about the errors that are common to all actions, see Common Errors.

CertificateNotFound

The specified certificate does not exist.

HTTP Status Code: 400

DuplicateListener

A listener with the specified port already exists.

HTTP Status Code: 400

IncompatibleProtocols

The specified configuration is not valid with this protocol.

HTTP Status Code: 400

InvalidConfigurationRequest

The requested configuration is not valid.

HTTP Status Code: 400

LoadBalancerNotFound

The specified load balancer does not exist.

HTTP Status Code: 400

SSLPolicyNotFound

The specified SSL policy does not exist.

HTTP Status Code: 400

TargetGroupAssociationLimit

You've reached the limit on the number of load balancers per target group.

HTTP Status Code: 400

TargetGroupNotFound

The specified target group does not exist.

HTTP Status Code: 400

TooManyCertificates

You've reached the limit on the number of certificates per listener.

HTTP Status Code: 400

TooManyListeners

You've reached the limit on the number of listeners per load balancer.

HTTP Status Code: 400

TooManyRegistrationsForTargetId

You've reached the limit on the number of times a target can be registered with a load balancer.

HTTP Status Code: 400

UnsupportedProtocol

The specified protocol is not supported.

HTTP Status Code: 400

Examples

Create an HTTP listener

This example creates an HTTP listener for the specified load balancer that forwards requests to the specified target group.

Sample Request

Copy
https://elasticloadbalancing.amazonaws.com/?Action=CreateListener &LoadBalancerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/50dc6c495c0c9188 &Protocol=HTTP &Port=80 &DefaultActions.member.1.Type=forward &DefaultActions.member.1.TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067 &Version=2015-12-01 &AUTHPARAMS

Sample Response

Copy
<CreateListenerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2015-12-01/"> <CreateListenerResult> <Listeners> <member> <LoadBalancerArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/50dc6c495c0c9188</LoadBalancerArn> <Protocol>HTTP</Protocol> <Port>80</Port> <ListenerArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2</ListenerArn> <DefaultActions> <member> <Type>forward</Type> <TargetGroupArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067</TargetGroupArn> </member> </DefaultActions> </member> </Listeners> </CreateListenerResult> <ResponseMetadata> <RequestId>883c84bb-f387-11e5-ae48-cff02092876b</RequestId> </ResponseMetadata> </CreateListenerResponse>

Create an HTTPS listener

This example creates an HTTPS listener for the specified load balancer that forwards requests to the specified target group. Note that you must specify an SSL certificate for an HTTPS listener. You can create and manage certificates using AWS Certificate Manager (ACM). Alternatively, you can create a certificate using SSL/TLS tools, get the certificate signed by a certificate authority (CA), and upload the certificate to AWS Identity and Access Management (IAM).

Sample Request

Copy
https://elasticloadbalancing.amazonaws.com/?Action=CreateListener &LoadBalancerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/50dc6c495c0c9188 &Protocol=HTTPS &Port=443 &Certificates.member.1.CertificateArn=arn:aws:iam::123456789012:server-certificate/my-server-cert &SslPolicy=ELBSecurityPolicy-2016-08 &DefaultActions.member.1.Type=forward &DefaultActions.member.1.TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067 &Version=2015-12-01 &AUTHPARAMS

Sample Response

Copy
<CreateListenerResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2015-12-01/"> <CreateListenerResult> <Listeners> <member> <LoadBalancerArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/50dc6c495c0c9188</LoadBalancerArn> <Protocol>HTTPS</Protocol> <Certificates> <member> <CertificateArn>arn:aws:iam::123456789012:server-certificate/my-server-cert</CertificateArn> </member> </Certificates> <Port>443</Port> <SslPolicy>ELBSecurityPolicy-2016-08</SslPolicy> <ListenerArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2</ListenerArn> <DefaultActions> <member> <Type>forward</Type> <TargetGroupArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067</TargetGroupArn> </member> </DefaultActions> </member> </Listeners> </CreateListenerResult> <ResponseMetadata> <RequestId>97f1bb38-f390-11e5-b95d-3b2c1831fc26</RequestId> </ResponseMetadata> </CreateListenerResponse>

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: