listeners

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

Overview

Name	listeners
Type	Resource
Id	aws.globalaccelerator.listeners

Fields

The following fields are returned by SELECT queries:

describe_listener

Name	Datatype	Description
client_affinity	string	Client affinity lets you direct all requests from a user to the same endpoint, if you have stateful applications, regardless of the port and protocol of the client request. Client affinity gives you control over whether to always route each client to the same specific endpoint. Global Accelerator uses a consistent-flow hashing algorithm to choose the optimal endpoint for a connection. If client affinity is NONE, Global Accelerator uses the "five-tuple" (5-tuple) properties—source IP address, source port, destination IP address, destination port, and protocol—to select the hash value, and then chooses the best endpoint. However, with this setting, if someone uses different ports to connect to Global Accelerator, their connections might not be always routed to the same endpoint because the hash value changes. If you want a given client to always be routed to the same endpoint, set client affinity to SOURCE_IP instead. When you use the SOURCE_IP setting, Global Accelerator uses the "two-tuple" (2-tuple) properties— source (client) IP address and destination IP address—to select the hash value. The default value is NONE. (NONE, SOURCE_IP)
listener_arn	string	The Amazon Resource Name (ARN) of the listener.
port_ranges	array	The list of port ranges for the connections from clients to the accelerator.
protocol	string	The protocol for the connections from clients to the accelerator. (TCP, UDP)

list_listeners

Name	Datatype	Description
client_affinity	string	Client affinity lets you direct all requests from a user to the same endpoint, if you have stateful applications, regardless of the port and protocol of the client request. Client affinity gives you control over whether to always route each client to the same specific endpoint. Global Accelerator uses a consistent-flow hashing algorithm to choose the optimal endpoint for a connection. If client affinity is NONE, Global Accelerator uses the "five-tuple" (5-tuple) properties—source IP address, source port, destination IP address, destination port, and protocol—to select the hash value, and then chooses the best endpoint. However, with this setting, if someone uses different ports to connect to Global Accelerator, their connections might not be always routed to the same endpoint because the hash value changes. If you want a given client to always be routed to the same endpoint, set client affinity to SOURCE_IP instead. When you use the SOURCE_IP setting, Global Accelerator uses the "two-tuple" (2-tuple) properties— source (client) IP address and destination IP address—to select the hash value. The default value is NONE. (NONE, SOURCE_IP)
listener_arn	string	The Amazon Resource Name (ARN) of the listener.
port_ranges	array	The list of port ranges for the connections from clients to the accelerator.
protocol	string	The protocol for the connections from clients to the accelerator. (TCP, UDP)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_listener	select	region		Describe a listener.
list_listeners	select	region		List the listeners for an accelerator.
create_listener	insert	region, AcceleratorArn, PortRanges, IdempotencyToken		Create a listener to process inbound connections from clients to an accelerator. Connections arrive to assigned static IP addresses on a port, port range, or list of port ranges that you specify.
update_listener	update	region, ListenerArn		Update a listener.
delete_listener	delete	region		Delete a listener from an accelerator.

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
region	string	AWS region (default: us-east-1)

SELECT examples

describe_listener

Describe a listener.

SELECT
client_affinity,
listener_arn,
port_ranges,
protocol
FROM aws.globalaccelerator.listeners
WHERE region = '{{ region }}' -- required
;

list_listeners

List the listeners for an accelerator.

SELECT
client_affinity,
listener_arn,
port_ranges,
protocol
FROM aws.globalaccelerator.listeners
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_listener

Create a listener to process inbound connections from clients to an accelerator. Connections arrive to assigned static IP addresses on a port, port range, or list of port ranges that you specify.

INSERT INTO aws.globalaccelerator.listeners (
AcceleratorArn,
PortRanges,
Protocol,
ClientAffinity,
IdempotencyToken,
region
)
SELECT 
'{{ AcceleratorArn }}' /* required */,
'{{ PortRanges }}' /* required */,
'{{ Protocol }}',
'{{ ClientAffinity }}',
'{{ IdempotencyToken }}' /* required */,
'{{ region }}'
RETURNING
listener
;

Manifest

# Description fields are for documentation purposes
- name: listeners
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the listeners resource.
  - name: AcceleratorArn
    value: "{{ AcceleratorArn }}"
    description: |
      The Amazon Resource Name (ARN) of your accelerator.
  - name: PortRanges
    description: |
      The list of port ranges to support for connections from clients to your accelerator.
    value:
      - FromPort: {{ FromPort }}
        ToPort: {{ ToPort }}
  - name: Protocol
    value: "{{ Protocol }}"
    description: |
      The protocol for connections from clients to your accelerator.
    valid_values: ['TCP', 'UDP']
  - name: ClientAffinity
    value: "{{ ClientAffinity }}"
    description: |
      Client affinity lets you direct all requests from a user to the same endpoint, if you have stateful applications, regardless of the port and protocol of the client request. Client affinity gives you control over whether to always route each client to the same specific endpoint. Global Accelerator uses a consistent-flow hashing algorithm to choose the optimal endpoint for a connection. If client affinity is NONE, Global Accelerator uses the "five-tuple" (5-tuple) properties—source IP address, source port, destination IP address, destination port, and protocol—to select the hash value, and then chooses the best endpoint. However, with this setting, if someone uses different ports to connect to Global Accelerator, their connections might not be always routed to the same endpoint because the hash value changes. If you want a given client to always be routed to the same endpoint, set client affinity to SOURCE_IP instead. When you use the SOURCE_IP setting, Global Accelerator uses the "two-tuple" (2-tuple) properties— source (client) IP address and destination IP address—to select the hash value. The default value is NONE.
    valid_values: ['NONE', 'SOURCE_IP']
  - name: IdempotencyToken
    value: "{{ IdempotencyToken }}"
    description: |
      A unique, case-sensitive identifier that you provide to ensure the idempotency—that is, the uniqueness—of the request.

UPDATE examples

update_listener

Update a listener.

UPDATE aws.globalaccelerator.listeners
SET 
ListenerArn = '{{ ListenerArn }}',
PortRanges = '{{ PortRanges }}',
Protocol = '{{ Protocol }}',
ClientAffinity = '{{ ClientAffinity }}'
WHERE 
region = '{{ region }}' --required
AND ListenerArn = '{{ ListenerArn }}' --required
RETURNING
listener;

DELETE examples

delete_listener

Delete a listener from an accelerator.

DELETE FROM aws.globalaccelerator.listeners
WHERE region = '{{ region }}' --required
;