describe_listeners
(**kwargs)¶Describes the specified listeners or the listeners for the specified Application Load Balancer, Network Load Balancer, or Gateway Load Balancer. You must specify either a load balancer or one or more listeners.
See also: AWS API Documentation
Request Syntax
response = client.describe_listeners(
LoadBalancerArn='string',
ListenerArns=[
'string',
],
Marker='string',
PageSize=123
)
The Amazon Resource Names (ARN) of the listeners.
dict
Response Syntax
{
'Listeners': [
{
'ListenerArn': 'string',
'LoadBalancerArn': 'string',
'Port': 123,
'Protocol': 'HTTP'|'HTTPS'|'TCP'|'TLS'|'UDP'|'TCP_UDP'|'GENEVE',
'Certificates': [
{
'CertificateArn': 'string',
'IsDefault': True|False
},
],
'SslPolicy': 'string',
'DefaultActions': [
{
'Type': 'forward'|'authenticate-oidc'|'authenticate-cognito'|'redirect'|'fixed-response',
'TargetGroupArn': 'string',
'AuthenticateOidcConfig': {
'Issuer': 'string',
'AuthorizationEndpoint': 'string',
'TokenEndpoint': 'string',
'UserInfoEndpoint': 'string',
'ClientId': 'string',
'ClientSecret': 'string',
'SessionCookieName': 'string',
'Scope': 'string',
'SessionTimeout': 123,
'AuthenticationRequestExtraParams': {
'string': 'string'
},
'OnUnauthenticatedRequest': 'deny'|'allow'|'authenticate',
'UseExistingClientSecret': True|False
},
'AuthenticateCognitoConfig': {
'UserPoolArn': 'string',
'UserPoolClientId': 'string',
'UserPoolDomain': 'string',
'SessionCookieName': 'string',
'Scope': 'string',
'SessionTimeout': 123,
'AuthenticationRequestExtraParams': {
'string': 'string'
},
'OnUnauthenticatedRequest': 'deny'|'allow'|'authenticate'
},
'Order': 123,
'RedirectConfig': {
'Protocol': 'string',
'Port': 'string',
'Host': 'string',
'Path': 'string',
'Query': 'string',
'StatusCode': 'HTTP_301'|'HTTP_302'
},
'FixedResponseConfig': {
'MessageBody': 'string',
'StatusCode': 'string',
'ContentType': 'string'
},
'ForwardConfig': {
'TargetGroups': [
{
'TargetGroupArn': 'string',
'Weight': 123
},
],
'TargetGroupStickinessConfig': {
'Enabled': True|False,
'DurationSeconds': 123
}
}
},
],
'AlpnPolicy': [
'string',
]
},
],
'NextMarker': 'string'
}
Response Structure
(dict) --
Listeners (list) --
Information about the listeners.
(dict) --
Information about a listener.
ListenerArn (string) --
The Amazon Resource Name (ARN) of the listener.
LoadBalancerArn (string) --
The Amazon Resource Name (ARN) of the load balancer.
Port (integer) --
The port on which the load balancer is listening.
Protocol (string) --
The protocol for connections from clients to the load balancer.
Certificates (list) --
[HTTPS or TLS listener] The default certificate for the listener.
(dict) --
Information about an SSL server certificate.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
IsDefault (boolean) --
Indicates whether the certificate is the default certificate. Do not set this value when specifying a certificate as an input. This value is not included in the output when describing a listener, but is included when describing listener certificates.
SslPolicy (string) --
[HTTPS or TLS listener] The security policy that defines which protocols and ciphers are supported.
DefaultActions (list) --
The default actions for the listener.
(dict) --
Information about an action.
Each rule must include exactly one of the following types of actions: forward
, fixed-response
, or redirect
, and it must be the last action to be performed.
Type (string) --
The type of action.
TargetGroupArn (string) --
The Amazon Resource Name (ARN) of the target group. Specify only when Type
is forward
and you want to route to a single target group. To route to one or more target groups, use ForwardConfig
instead.
AuthenticateOidcConfig (dict) --
[HTTPS listeners] Information about an identity provider that is compliant with OpenID Connect (OIDC). Specify only when Type
is authenticate-oidc
.
Issuer (string) --
The OIDC issuer identifier of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.
AuthorizationEndpoint (string) --
The authorization endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.
TokenEndpoint (string) --
The token endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.
UserInfoEndpoint (string) --
The user info endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.
ClientId (string) --
The OAuth 2.0 client identifier.
ClientSecret (string) --
The OAuth 2.0 client secret. This parameter is required if you are creating a rule. If you are modifying a rule, you can omit this parameter if you set UseExistingClientSecret
to true.
SessionCookieName (string) --
The name of the cookie used to maintain session information. The default is AWSELBAuthSessionCookie.
Scope (string) --
The set of user claims to be requested from the IdP. The default is openid
.
To verify which scope values your IdP supports and how to separate multiple values, see the documentation for your IdP.
SessionTimeout (integer) --
The maximum duration of the authentication session, in seconds. The default is 604800 seconds (7 days).
AuthenticationRequestExtraParams (dict) --
The query parameters (up to 10) to include in the redirect request to the authorization endpoint.
OnUnauthenticatedRequest (string) --
The behavior if the user is not authenticated. The following are possible values:
UseExistingClientSecret (boolean) --
Indicates whether to use the existing client secret when modifying a rule. If you are creating a rule, you can omit this parameter or set it to false.
AuthenticateCognitoConfig (dict) --
[HTTPS listeners] Information for using Amazon Cognito to authenticate users. Specify only when Type
is authenticate-cognito
.
UserPoolArn (string) --
The Amazon Resource Name (ARN) of the Amazon Cognito user pool.
UserPoolClientId (string) --
The ID of the Amazon Cognito user pool client.
UserPoolDomain (string) --
The domain prefix or fully-qualified domain name of the Amazon Cognito user pool.
SessionCookieName (string) --
The name of the cookie used to maintain session information. The default is AWSELBAuthSessionCookie.
Scope (string) --
The set of user claims to be requested from the IdP. The default is openid
.
To verify which scope values your IdP supports and how to separate multiple values, see the documentation for your IdP.
SessionTimeout (integer) --
The maximum duration of the authentication session, in seconds. The default is 604800 seconds (7 days).
AuthenticationRequestExtraParams (dict) --
The query parameters (up to 10) to include in the redirect request to the authorization endpoint.
OnUnauthenticatedRequest (string) --
The behavior if the user is not authenticated. The following are possible values:
Order (integer) --
The order for the action. This value is required for rules with multiple actions. The action with the lowest value for order is performed first.
RedirectConfig (dict) --
[Application Load Balancer] Information for creating a redirect action. Specify only when Type
is redirect
.
Protocol (string) --
The protocol. You can specify HTTP, HTTPS, or #{protocol}. You can redirect HTTP to HTTP, HTTP to HTTPS, and HTTPS to HTTPS. You cannot redirect HTTPS to HTTP.
Port (string) --
The port. You can specify a value from 1 to 65535 or #{port}.
Host (string) --
The hostname. This component is not percent-encoded. The hostname can contain #{host}.
Path (string) --
The absolute path, starting with the leading "/". This component is not percent-encoded. The path can contain #{host}, #{path}, and #{port}.
Query (string) --
The query parameters, URL-encoded when necessary, but not percent-encoded. Do not include the leading "?", as it is automatically added. You can specify any of the reserved keywords.
StatusCode (string) --
The HTTP redirect code. The redirect is either permanent (HTTP 301) or temporary (HTTP 302).
FixedResponseConfig (dict) --
[Application Load Balancer] Information for creating an action that returns a custom HTTP response. Specify only when Type
is fixed-response
.
MessageBody (string) --
The message.
StatusCode (string) --
The HTTP response code (2XX, 4XX, or 5XX).
ContentType (string) --
The content type.
Valid Values: text/plain | text/css | text/html | application/javascript | application/json
ForwardConfig (dict) --
Information for creating an action that distributes requests among one or more target groups. For Network Load Balancers, you can specify a single target group. Specify only when Type
is forward
. If you specify both ForwardConfig
and TargetGroupArn
, you can specify only one target group using ForwardConfig
and it must be the same target group specified in TargetGroupArn
.
TargetGroups (list) --
The target groups. For Network Load Balancers, you can specify a single target group.
(dict) --
Information about how traffic will be distributed between multiple target groups in a forward rule.
TargetGroupArn (string) --
The Amazon Resource Name (ARN) of the target group.
Weight (integer) --
The weight. The range is 0 to 999.
TargetGroupStickinessConfig (dict) --
The target group stickiness for the rule.
Enabled (boolean) --
Indicates whether target group stickiness is enabled.
DurationSeconds (integer) --
The time period, in seconds, during which requests from a client should be routed to the same target group. The range is 1-604800 seconds (7 days).
AlpnPolicy (list) --
[TLS listener] The name of the Application-Layer Protocol Negotiation (ALPN) policy.
NextMarker (string) --
If there are additional results, this is the marker for the next set of results. Otherwise, this is null.
Exceptions
ElasticLoadBalancingv2.Client.exceptions.ListenerNotFoundException
ElasticLoadBalancingv2.Client.exceptions.LoadBalancerNotFoundException
ElasticLoadBalancingv2.Client.exceptions.UnsupportedProtocolException
Examples
This example describes the specified listener.
response = client.describe_listeners(
ListenerArns=[
'arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2',
],
)
print(response)
Expected Output:
{
'Listeners': [
{
'DefaultActions': [
{
'TargetGroupArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067',
'Type': 'forward',
},
],
'ListenerArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2',
'LoadBalancerArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/50dc6c495c0c9188',
'Port': 80,
'Protocol': 'HTTP',
},
],
'ResponseMetadata': {
'...': '...',
},
}