listeners

Creates, updates, deletes, gets or lists a listeners resource.

Overview

Name	listeners
Type	Resource
Id	aws.elbv2.listeners

Fields

The following fields are returned by SELECT queries:

describe_listeners

Name	Datatype	Description
alpn_policy	string	[TLS listener] The name of the Application-Layer Protocol Negotiation (ALPN) policy.
certificates	string	[HTTPS or TLS listener] The default certificate for the listener.
default_actions	string	The default actions for the listener.
listener_arn	string	The Amazon Resource Name (ARN) of the listener.
load_balancer_arn	string	The Amazon Resource Name (ARN) of the load balancer.
mutual_authentication	string	The mutual authentication configuration information.
port	integer	The port on which the load balancer is listening.
protocol	string	The protocol for connections from clients to the load balancer.
ssl_policy	string	[HTTPS or TLS listener] The security policy that defines which protocols and ciphers are supported.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_listeners	select	region	LoadBalancerArn, ListenerArns, Marker, PageSize	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.
create_listener	insert	LoadBalancerArn, DefaultActions, region	Protocol, Port, SslPolicy, Certificates, AlpnPolicy, Tags, MutualAuthentication	Creates a listener for the specified Application Load Balancer, Network Load Balancer, or Gateway Load Balancer. For more information, see the following: Listeners for your Application Load Balancers Listeners for your Network Load Balancers Listeners for your Gateway Load Balancers 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.
modify_listener	update	ListenerArn, region	Port, Protocol, SslPolicy, Certificates, DefaultActions, AlpnPolicy, MutualAuthentication	Replaces the specified properties of the specified listener. Any properties that you do not specify remain unchanged. Changing the protocol from HTTPS to HTTP, or from TLS to TCP, removes the security policy and default certificate properties. If you change the protocol from HTTP to HTTPS, or from TCP to TLS, you must add the security policy and default certificate properties. To add an item to a list, remove an item from a list, or update an item in a list, you must provide the entire list. For example, to add an action, specify a list with the current actions plus the new action.
delete_listener	delete	ListenerArn, region		Deletes the specified listener. Alternatively, your listener is deleted when you delete the load balancer to which it is attached.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
DefaultActions	array	The actions for the default rule.
ListenerArn	string	The Amazon Resource Name (ARN) of the listener.
LoadBalancerArn	string	The Amazon Resource Name (ARN) of the load balancer.
region	string	AWS region (default: us-east-1)
AlpnPolicy	array	[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	array	[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.
DefaultActions	array	The actions for the default rule.
ListenerArns	array	The Amazon Resource Names (ARN) of the listeners.
LoadBalancerArn	string	The Amazon Resource Name (ARN) of the load balancer.
Marker	string	The marker for the next set of results. (You received this marker from a previous call.)
MutualAuthentication	object	[HTTPS listeners] The mutual authentication configuration information.
PageSize	integer	The maximum number of results to return with this call.
Port	integer	The port for connections from clients to the load balancer. You can't specify a port for a Gateway Load Balancer.
Protocol	string	The protocol for connections from clients to the load balancer. Application Load Balancers support the HTTP and HTTPS protocols. Network Load Balancers support the TCP, TLS, UDP, TCP_UDP, QUIC, and TCP_QUIC protocols. You can’t change the protocol to UDP, TCP_UDP, QUIC, or TCP_QUIC if dual-stack mode is enabled. You can't specify a protocol for a Gateway Load Balancer.
SslPolicy	string	[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 or Security policies in the Network Load Balancers Guide.
Tags	array	The tags to assign to the listener.

SELECT examples

describe_listeners

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.

SELECT
alpn_policy,
certificates,
default_actions,
listener_arn,
load_balancer_arn,
mutual_authentication,
port,
protocol,
ssl_policy
FROM aws.elbv2.listeners
WHERE region = '{{ region }}' -- required
AND LoadBalancerArn = '{{ LoadBalancerArn }}'
AND ListenerArns = '{{ ListenerArns }}'
AND Marker = '{{ Marker }}'
AND PageSize = '{{ PageSize }}'
;

INSERT examples

create_listener

Creates a listener for the specified Application Load Balancer, Network Load Balancer, or Gateway Load Balancer. For more information, see the following: Listeners for your Application Load Balancers Listeners for your Network Load Balancers Listeners for your Gateway Load Balancers 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.

INSERT INTO aws.elbv2.listeners (
LoadBalancerArn,
DefaultActions,
region,
Protocol,
Port,
SslPolicy,
Certificates,
AlpnPolicy,
Tags,
MutualAuthentication
)
SELECT 
'{{ LoadBalancerArn }}',
'{{ DefaultActions }}',
'{{ region }}',
'{{ Protocol }}',
'{{ Port }}',
'{{ SslPolicy }}',
'{{ Certificates }}',
'{{ AlpnPolicy }}',
'{{ Tags }}',
'{{ MutualAuthentication }}'
RETURNING
line_items
;

Manifest

# Description fields are for documentation purposes
- name: listeners
props:
  - name: LoadBalancerArn
    value: "{{ LoadBalancerArn }}"
    description: Required parameter for the listeners resource.
  - name: DefaultActions
    value: "{{ DefaultActions }}"
    description: Required parameter for the listeners resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the listeners resource.
  - name: Protocol
    value: "{{ Protocol }}"
    description: 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, TCP_UDP, QUIC, and TCP_QUIC. You can’t specify the UDP, TCP_UDP, QUIC, or TCP_QUIC protocol if dual-stack mode is enabled. You can't specify a protocol for a Gateway Load Balancer.
    description: 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, TCP_UDP, QUIC, and TCP_QUIC. You can’t specify the UDP, TCP_UDP, QUIC, or TCP_QUIC protocol if dual-stack mode is enabled. You can't specify a protocol for a Gateway Load Balancer.
  - name: Port
    value: {{ Port }}
    description: The port on which the load balancer is listening. You can't specify a port for a Gateway Load Balancer.
    description: The port on which the load balancer is listening. You can't specify a port for a Gateway Load Balancer.
  - name: SslPolicy
    value: "{{ SslPolicy }}"
    description: [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.
    description: [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.
  - name: Certificates
    value: "{{ Certificates }}"
    description: [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.
    description: [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.
  - name: AlpnPolicy
    value: "{{ AlpnPolicy }}"
    description: [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.
    description: [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.
  - name: Tags
    value: "{{ Tags }}"
    description: The tags to assign to the listener.
    description: The tags to assign to the listener.
  - name: MutualAuthentication
    value: "{{ MutualAuthentication }}"
    description: [HTTPS listeners] The mutual authentication configuration information.
    description: [HTTPS listeners] The mutual authentication configuration information.

UPDATE examples

modify_listener

Replaces the specified properties of the specified listener. Any properties that you do not specify remain unchanged. Changing the protocol from HTTPS to HTTP, or from TLS to TCP, removes the security policy and default certificate properties. If you change the protocol from HTTP to HTTPS, or from TCP to TLS, you must add the security policy and default certificate properties. To add an item to a list, remove an item from a list, or update an item in a list, you must provide the entire list. For example, to add an action, specify a list with the current actions plus the new action.

UPDATE aws.elbv2.listeners
SET 
-- No updatable properties
WHERE 
ListenerArn = '{{ ListenerArn }}' --required
AND region = '{{ region }}' --required
AND Port = '{{ Port}}'
AND Protocol = '{{ Protocol}}'
AND SslPolicy = '{{ SslPolicy}}'
AND Certificates = '{{ Certificates}}'
AND DefaultActions = '{{ DefaultActions}}'
AND AlpnPolicy = '{{ AlpnPolicy}}'
AND MutualAuthentication = '{{ MutualAuthentication}}'
RETURNING
line_items;

DELETE examples

delete_listener

Deletes the specified listener. Alternatively, your listener is deleted when you delete the load balancer to which it is attached.

DELETE FROM aws.elbv2.listeners
WHERE ListenerArn = '{{ ListenerArn }}' --required
AND region = '{{ region }}' --required
;