CreateListenerCommand

Suggest an Edit

Creates a listener for the specified Application Load Balancer, Network Load Balancer, or Gateway Load Balancer.

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.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { ElasticLoadBalancingV2Client, CreateListenerCommand } from "@aws-sdk/client-elastic-load-balancing-v2"; // ES Modules import
// const { ElasticLoadBalancingV2Client, CreateListenerCommand } = require("@aws-sdk/client-elastic-load-balancing-v2"); // CommonJS import
const client = new ElasticLoadBalancingV2Client(config);
const input = { // CreateListenerInput
  LoadBalancerArn: "STRING_VALUE", // required
  Protocol: "HTTP" || "HTTPS" || "TCP" || "TLS" || "UDP" || "TCP_UDP" || "GENEVE",
  Port: Number("int"),
  SslPolicy: "STRING_VALUE",
  Certificates: [ // CertificateList
    { // Certificate
      CertificateArn: "STRING_VALUE",
      IsDefault: true || false,
    },
  ],
  DefaultActions: [ // Actions // required
    { // Action
      Type: "forward" || "authenticate-oidc" || "authenticate-cognito" || "redirect" || "fixed-response", // required
      TargetGroupArn: "STRING_VALUE",
      AuthenticateOidcConfig: { // AuthenticateOidcActionConfig
        Issuer: "STRING_VALUE", // required
        AuthorizationEndpoint: "STRING_VALUE", // required
        TokenEndpoint: "STRING_VALUE", // required
        UserInfoEndpoint: "STRING_VALUE", // required
        ClientId: "STRING_VALUE", // required
        ClientSecret: "STRING_VALUE",
        SessionCookieName: "STRING_VALUE",
        Scope: "STRING_VALUE",
        SessionTimeout: Number("long"),
        AuthenticationRequestExtraParams: { // AuthenticateOidcActionAuthenticationRequestExtraParams
          "<keys>": "STRING_VALUE",
        },
        OnUnauthenticatedRequest: "deny" || "allow" || "authenticate",
        UseExistingClientSecret: true || false,
      },
      AuthenticateCognitoConfig: { // AuthenticateCognitoActionConfig
        UserPoolArn: "STRING_VALUE", // required
        UserPoolClientId: "STRING_VALUE", // required
        UserPoolDomain: "STRING_VALUE", // required
        SessionCookieName: "STRING_VALUE",
        Scope: "STRING_VALUE",
        SessionTimeout: Number("long"),
        AuthenticationRequestExtraParams: { // AuthenticateCognitoActionAuthenticationRequestExtraParams
          "<keys>": "STRING_VALUE",
        },
        OnUnauthenticatedRequest: "deny" || "allow" || "authenticate",
      },
      Order: Number("int"),
      RedirectConfig: { // RedirectActionConfig
        Protocol: "STRING_VALUE",
        Port: "STRING_VALUE",
        Host: "STRING_VALUE",
        Path: "STRING_VALUE",
        Query: "STRING_VALUE",
        StatusCode: "HTTP_301" || "HTTP_302", // required
      },
      FixedResponseConfig: { // FixedResponseActionConfig
        MessageBody: "STRING_VALUE",
        StatusCode: "STRING_VALUE", // required
        ContentType: "STRING_VALUE",
      },
      ForwardConfig: { // ForwardActionConfig
        TargetGroups: [ // TargetGroupList
          { // TargetGroupTuple
            TargetGroupArn: "STRING_VALUE",
            Weight: Number("int"),
          },
        ],
        TargetGroupStickinessConfig: { // TargetGroupStickinessConfig
          Enabled: true || false,
          DurationSeconds: Number("int"),
        },
      },
    },
  ],
  AlpnPolicy: [ // AlpnPolicyName
    "STRING_VALUE",
  ],
  Tags: [ // TagList
    { // Tag
      Key: "STRING_VALUE", // required
      Value: "STRING_VALUE",
    },
  ],
  MutualAuthentication: { // MutualAuthenticationAttributes
    Mode: "STRING_VALUE",
    TrustStoreArn: "STRING_VALUE",
    IgnoreClientCertificateExpiry: true || false,
    TrustStoreAssociationStatus: "active" || "removed",
    AdvertiseTrustStoreCaNames: "on" || "off",
  },
};
const command = new CreateListenerCommand(input);
const response = await client.send(command);
// { // CreateListenerOutput
//   Listeners: [ // Listeners
//     { // Listener
//       ListenerArn: "STRING_VALUE",
//       LoadBalancerArn: "STRING_VALUE",
//       Port: Number("int"),
//       Protocol: "HTTP" || "HTTPS" || "TCP" || "TLS" || "UDP" || "TCP_UDP" || "GENEVE",
//       Certificates: [ // CertificateList
//         { // Certificate
//           CertificateArn: "STRING_VALUE",
//           IsDefault: true || false,
//         },
//       ],
//       SslPolicy: "STRING_VALUE",
//       DefaultActions: [ // Actions
//         { // Action
//           Type: "forward" || "authenticate-oidc" || "authenticate-cognito" || "redirect" || "fixed-response", // required
//           TargetGroupArn: "STRING_VALUE",
//           AuthenticateOidcConfig: { // AuthenticateOidcActionConfig
//             Issuer: "STRING_VALUE", // required
//             AuthorizationEndpoint: "STRING_VALUE", // required
//             TokenEndpoint: "STRING_VALUE", // required
//             UserInfoEndpoint: "STRING_VALUE", // required
//             ClientId: "STRING_VALUE", // required
//             ClientSecret: "STRING_VALUE",
//             SessionCookieName: "STRING_VALUE",
//             Scope: "STRING_VALUE",
//             SessionTimeout: Number("long"),
//             AuthenticationRequestExtraParams: { // AuthenticateOidcActionAuthenticationRequestExtraParams
//               "<keys>": "STRING_VALUE",
//             },
//             OnUnauthenticatedRequest: "deny" || "allow" || "authenticate",
//             UseExistingClientSecret: true || false,
//           },
//           AuthenticateCognitoConfig: { // AuthenticateCognitoActionConfig
//             UserPoolArn: "STRING_VALUE", // required
//             UserPoolClientId: "STRING_VALUE", // required
//             UserPoolDomain: "STRING_VALUE", // required
//             SessionCookieName: "STRING_VALUE",
//             Scope: "STRING_VALUE",
//             SessionTimeout: Number("long"),
//             AuthenticationRequestExtraParams: { // AuthenticateCognitoActionAuthenticationRequestExtraParams
//               "<keys>": "STRING_VALUE",
//             },
//             OnUnauthenticatedRequest: "deny" || "allow" || "authenticate",
//           },
//           Order: Number("int"),
//           RedirectConfig: { // RedirectActionConfig
//             Protocol: "STRING_VALUE",
//             Port: "STRING_VALUE",
//             Host: "STRING_VALUE",
//             Path: "STRING_VALUE",
//             Query: "STRING_VALUE",
//             StatusCode: "HTTP_301" || "HTTP_302", // required
//           },
//           FixedResponseConfig: { // FixedResponseActionConfig
//             MessageBody: "STRING_VALUE",
//             StatusCode: "STRING_VALUE", // required
//             ContentType: "STRING_VALUE",
//           },
//           ForwardConfig: { // ForwardActionConfig
//             TargetGroups: [ // TargetGroupList
//               { // TargetGroupTuple
//                 TargetGroupArn: "STRING_VALUE",
//                 Weight: Number("int"),
//               },
//             ],
//             TargetGroupStickinessConfig: { // TargetGroupStickinessConfig
//               Enabled: true || false,
//               DurationSeconds: Number("int"),
//             },
//           },
//         },
//       ],
//       AlpnPolicy: [ // AlpnPolicyName
//         "STRING_VALUE",
//       ],
//       MutualAuthentication: { // MutualAuthenticationAttributes
//         Mode: "STRING_VALUE",
//         TrustStoreArn: "STRING_VALUE",
//         IgnoreClientCertificateExpiry: true || false,
//         TrustStoreAssociationStatus: "active" || "removed",
//         AdvertiseTrustStoreCaNames: "on" || "off",
//       },
//     },
//   ],
// };

Example Usage

 Loading code editorLoading code editor

CreateListenerCommand Input

See CreateListenerCommandInput for more details

Parameter
Type
Description
DefaultActions
Required
Action[] | undefined

The actions for the default rule.

LoadBalancerArn
Required
string | undefined

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

AlpnPolicy
string[] | undefined

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

Certificates
Certificate[] | undefined

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

MutualAuthentication
MutualAuthenticationAttributes | undefined

The mutual authentication configuration information.

Port
number | undefined

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

Protocol
ProtocolEnum | undefined

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.

SslPolicy
string | undefined

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

Tags
Tag[] | undefined

The tags to assign to the listener.

CreateListenerCommand Output

See CreateListenerCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
Listeners
Listener[] | undefined

Information about the listener.

Throws

Name
Fault
Details
ALPNPolicyNotSupportedException
client

The specified ALPN policy is not supported.

CertificateNotFoundException
client

The specified certificate does not exist.

DuplicateListenerException
client

A listener with the specified port already exists.

IncompatibleProtocolsException
client

The specified configuration is not valid with this protocol.

InvalidConfigurationRequestException
client

The requested configuration is not valid.

InvalidLoadBalancerActionException
client

The requested action is not valid.

LoadBalancerNotFoundException
client

The specified load balancer does not exist.

SSLPolicyNotFoundException
client

The specified SSL policy does not exist.

TargetGroupAssociationLimitException
client

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

TargetGroupNotFoundException
client

The specified target group does not exist.

TooManyActionsException
client

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

TooManyCertificatesException
client

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

TooManyListenersException
client

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

TooManyRegistrationsForTargetIdException
client

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

TooManyTagsException
client

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

TooManyTargetsException
client

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

TooManyUniqueTargetGroupsPerLoadBalancerException
client

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.

TrustStoreNotFoundException
client

The specified trust store does not exist.

TrustStoreNotReadyException
client

The specified trust store is not active.

UnsupportedProtocolException
client

The specified protocol is not supported.

ElasticLoadBalancingV2ServiceException
Base exception class for all service exceptions from ElasticLoadBalancingV2 service.