CreateListener - Elastic Load Balancing
Request SyntaxRequest ParametersResponse SyntaxResponse ElementsErrorsExamplesSee Also

CreateListener

Creates a listener for the specified Application Load Balancer, Network Load Balancer, or Gateway 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 the following:

This operation is idempotent, which means that it completes at most one time. If you attempt to create multiple listeners with the same settings, each call succeeds.

Request Syntax

{
   "AlpnPolicy": [ "string" ],
   "Certificates": [ 
      { 
         "CertificateArn": "string",
         "IsDefault": boolean
      }
   ],
   "DefaultActions": [ 
      { 
         "AuthenticateCognitoConfig": { 
            "AuthenticationRequestExtraParams": { 
               "string" : "string" 
            },
            "OnUnauthenticatedRequest": "string",
            "Scope": "string",
            "SessionCookieName": "string",
            "SessionTimeout": number,
            "UserPoolArn": "string",
            "UserPoolClientId": "string",
            "UserPoolDomain": "string"
         },
         "AuthenticateOidcConfig": { 
            "AuthenticationRequestExtraParams": { 
               "string" : "string" 
            },
            "AuthorizationEndpoint": "string",
            "ClientId": "string",
            "ClientSecret": "string",
            "Issuer": "string",
            "OnUnauthenticatedRequest": "string",
            "Scope": "string",
            "SessionCookieName": "string",
            "SessionTimeout": number,
            "TokenEndpoint": "string",
            "UseExistingClientSecret": boolean,
            "UserInfoEndpoint": "string"
         },
         "FixedResponseConfig": { 
            "ContentType": "string",
            "MessageBody": "string",
            "StatusCode": "string"
         },
         "ForwardConfig": { 
            "TargetGroups": [ 
               { 
                  "TargetGroupArn": "string",
                  "Weight": number
               }
            ],
            "TargetGroupStickinessConfig": { 
               "DurationSeconds": number,
               "Enabled": boolean
            }
         },
         "Order": number,
         "RedirectConfig": { 
            "Host": "string",
            "Path": "string",
            "Port": "string",
            "Protocol": "string",
            "Query": "string",
            "StatusCode": "string"
         },
         "TargetGroupArn": "string",
         "Type": "string"
      }
   ],
   "LoadBalancerArn": "string",
   "MutualAuthentication": { 
      "AdvertiseTrustStoreCaNames": "string",
      "IgnoreClientCertificateExpiry": boolean,
      "Mode": "string",
      "TrustStoreArn": "string",
      "TrustStoreAssociationStatus": "string"
   },
   "Port": number,
   "Protocol": "string",
   "SslPolicy": "string",
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ]
}

Request Parameters

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

The request accepts the following data in JSON format.

AlpnPolicy

[TLS listeners] The name of the Application-Layer Protocol Negotiation (ALPN) policy. You can specify one policy name. The following are the possible values:

  • HTTP1Only

  • HTTP2Only

  • HTTP2Optional

  • HTTP2Preferred

  • None

For more information, see ALPN policies in the Network Load Balancers Guide.

Type: Array of strings

Required: No

Certificates

[HTTPS and TLS listeners] The default certificate for the listener. You must provide exactly one certificate. Set CertificateArn to the certificate ARN but do not set IsDefault.

To create a certificate list for the listener, use AddListenerCertificates.

Type: Array of Certificate objects

Required: No

DefaultActions

The actions for the default rule.

Type: Array of Action objects

Required: Yes

LoadBalancerArn

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

Type: String

Required: Yes

MutualAuthentication

The mutual authentication configuration information.

Type: MutualAuthenticationAttributes object

Required: No

Port

The port on which the load balancer is listening. You can't specify a port for a Gateway Load Balancer.

Type: Integer

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

Required: No

Protocol

The protocol for connections from clients to the load balancer. For Application Load Balancers, the supported protocols are HTTP and HTTPS. For Network Load Balancers, the supported protocols are TCP, TLS, UDP, and TCP_UDP. You can’t specify the UDP or TCP_UDP protocol if dual-stack mode is enabled. You can't specify a protocol for a Gateway Load Balancer.

Type: String

Valid Values: HTTP | HTTPS | TCP | TLS | UDP | TCP_UDP | GENEVE

Required: No

SslPolicy

[HTTPS and TLS listeners] The security policy that defines which protocols and ciphers are supported.

For more information, see Security policies in the Application Load Balancers Guide and Security policies in the Network Load Balancers Guide.

Type: String

Required: No

Tags

The tags to assign to the listener.

Type: Array of Tag objects

Array Members: Minimum number of 1 item.

Required: No

Response Syntax

{
   "Listeners": [ 
      { 
         "AlpnPolicy": [ "string" ],
         "Certificates": [ 
            { 
               "CertificateArn": "string",
               "IsDefault": boolean
            }
         ],
         "DefaultActions": [ 
            { 
               "AuthenticateCognitoConfig": { 
                  "AuthenticationRequestExtraParams": { 
                     "string" : "string" 
                  },
                  "OnUnauthenticatedRequest": "string",
                  "Scope": "string",
                  "SessionCookieName": "string",
                  "SessionTimeout": number,
                  "UserPoolArn": "string",
                  "UserPoolClientId": "string",
                  "UserPoolDomain": "string"
               },
               "AuthenticateOidcConfig": { 
                  "AuthenticationRequestExtraParams": { 
                     "string" : "string" 
                  },
                  "AuthorizationEndpoint": "string",
                  "ClientId": "string",
                  "ClientSecret": "string",
                  "Issuer": "string",
                  "OnUnauthenticatedRequest": "string",
                  "Scope": "string",
                  "SessionCookieName": "string",
                  "SessionTimeout": number,
                  "TokenEndpoint": "string",
                  "UseExistingClientSecret": boolean,
                  "UserInfoEndpoint": "string"
               },
               "FixedResponseConfig": { 
                  "ContentType": "string",
                  "MessageBody": "string",
                  "StatusCode": "string"
               },
               "ForwardConfig": { 
                  "TargetGroups": [ 
                     { 
                        "TargetGroupArn": "string",
                        "Weight": number
                     }
                  ],
                  "TargetGroupStickinessConfig": { 
                     "DurationSeconds": number,
                     "Enabled": boolean
                  }
               },
               "Order": number,
               "RedirectConfig": { 
                  "Host": "string",
                  "Path": "string",
                  "Port": "string",
                  "Protocol": "string",
                  "Query": "string",
                  "StatusCode": "string"
               },
               "TargetGroupArn": "string",
               "Type": "string"
            }
         ],
         "ListenerArn": "string",
         "LoadBalancerArn": "string",
         "MutualAuthentication": { 
            "AdvertiseTrustStoreCaNames": "string",
            "IgnoreClientCertificateExpiry": boolean,
            "Mode": "string",
            "TrustStoreArn": "string",
            "TrustStoreAssociationStatus": "string"
         },
         "Port": number,
         "Protocol": "string",
         "SslPolicy": "string"
      }
   ]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Listeners

Information about the listener.

Type: Array of Listener objects

Errors

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

ALPNPolicyNotSupportedException

The specified ALPN policy is not supported.

HTTP Status Code: 400

CertificateNotFoundException

The specified certificate does not exist.

HTTP Status Code: 400

DuplicateListenerException

A listener with the specified port already exists.

HTTP Status Code: 400

IncompatibleProtocolsException

The specified configuration is not valid with this protocol.

HTTP Status Code: 400

InvalidConfigurationRequestException

The requested configuration is not valid.

HTTP Status Code: 400

InvalidLoadBalancerActionException

The requested action is not valid.

HTTP Status Code: 400

LoadBalancerNotFoundException

The specified load balancer does not exist.

HTTP Status Code: 400

SSLPolicyNotFoundException

The specified SSL policy does not exist.

HTTP Status Code: 400

TargetGroupAssociationLimitException

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

HTTP Status Code: 400

TargetGroupNotFoundException

The specified target group does not exist.

HTTP Status Code: 400

TooManyActionsException

You've reached the limit on the number of actions per rule.

HTTP Status Code: 400

TooManyCertificatesException

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

HTTP Status Code: 400

TooManyListenersException

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

HTTP Status Code: 400

TooManyRegistrationsForTargetIdException

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

HTTP Status Code: 400

TooManyTagsException

You've reached the limit on the number of tags for this resource.

HTTP Status Code: 400

TooManyTargetsException

You've reached the limit on the number of targets.

HTTP Status Code: 400

TooManyUniqueTargetGroupsPerLoadBalancerException

You've reached the limit on the number of unique target groups per load balancer across all listeners. If a target group is used by multiple actions for a load balancer, it is counted as only one use.

HTTP Status Code: 400

TrustStoreNotFoundException

The specified trust store does not exist.

HTTP Status Code: 400

TrustStoreNotReadyException

The specified trust store is not active.

HTTP Status Code: 400

UnsupportedProtocolException

The specified protocol is not supported.

HTTP Status Code: 400

Examples

Create an HTTP listener

This example creates an HTTP listener for the specified Application Load Balancer that forwards requests to the specified target group.

Sample Request

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

<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 Application Load Balancer that forwards requests to the specified target group. Note that you must specify a default certificate for an HTTPS listener. You can create and manage your 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

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

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

Create a TCP listener

This example creates a TCP listener for the specified Network Load Balancer that forwards requests to the specified target group.

https://elasticloadbalancing.amazonaws.com/?Action=CreateListener
&LoadBalancerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/net/my-network-load-balancer/2d7b630a7815dda2
&Protocol=TCP
&Port=80
&DefaultActions.member.1.Type=forward
&DefaultActions.member.1.TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-tcp-targets/b7fce90c666d892a
&Version=2015-12-01
&AUTHPARAMS

Create a TLS listener

This example creates a TLS listener for the specified Network Load Balancer that forwards requests to the specified target group.

https://elasticloadbalancing.amazonaws.com/?Action=CreateListener
&LoadBalancerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/net/my-network-load-balancer/2d7b630a7815dda2
&Protocol=TLS
&Port=443
&Certificates.member.1.CertificateArn=arn:aws:acm::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-tls-targets/b7fce90c666d892a
&Version=2015-12-01
&AUTHPARAMS

Create a UDP listener

This example creates a UDP listener for the specified Network Load Balancer that forwards requests to the specified target group.

https://elasticloadbalancing.amazonaws.com/?Action=CreateListener
&LoadBalancerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/net/my-network-load-balancer/2d7b630a7815dda2
&Protocol=UDP
&Port=53
&DefaultActions.member.1.Type=forward
&DefaultActions.member.1.TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-udp-targets/b7fce90c666d892a
&Version=2015-12-01
&AUTHPARAMS

Create a TCP_UDP listener

This example creates a TCP_UDP listener for the specified Network Load Balancer that forwards requests to the specified target group. The target group must use the TCP_UDP protocol.

https://elasticloadbalancing.amazonaws.com/?Action=CreateListener
&LoadBalancerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/net/my-network-load-balancer/2d7b630a7815dda2
&Protocol=TCP_UDP
&Port=80
&DefaultActions.member.1.Type=forward
&DefaultActions.member.1.TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-tcp-udp-targets/b7fce90c666d892a
&Version=2015-12-01
&AUTHPARAMS

Create a listener for your Gateway Load Balancer

This example creates a listener for the specified Gateway Load Balancer that forwards requests to the specified target group. You can't specify a port or protocol.

https://elasticloadbalancing.amazonaws.com/?Action=CreateListener
&LoadBalancerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/gwy/my-gateway-load-balancer/2d7b630a7815dda2
&DefaultActions.member.1.Type=forward
&DefaultActions.member.1.TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-appliance-targets/b7fce90c666d892a
&Version=2015-12-01
&AUTHPARAMS

See Also

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