listeners

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

Overview

Name	listeners
Type	Resource
Id	aws.vpc_lattice.listeners

Fields

The following fields are returned by SELECT queries:

get_listener

Name	Datatype	Description
id	string	The ID of the listener. (pattern: <code>listener-[0-9a-z]{17}</code>)
name	string	The name of the listener. (pattern: <code>(?!listener-)(?![-])(?!.[-]$)(?!.[-]{2})[a-z0-9-]+</code>)
arn	string	The Amazon Resource Name (ARN) of the listener. (pattern: <code>arn:[a-z0-9-]+:vpc-lattice:[a-zA-Z0-9-]+:\d{12}:service/svc-[0-9a-z]{17}/listener/listener-[0-9a-z]{17}</code>)
created_at	string (date-time)	The date and time that the listener was created, in ISO-8601 format.
default_action	object	Describes the action for a rule.
last_updated_at	string (date-time)	The date and time that the listener was last updated, in ISO-8601 format.
port	integer	The listener port.
protocol	string	The listener protocol. (HTTP, HTTPS, TLS_PASSTHROUGH)
service_arn	string	The Amazon Resource Name (ARN) of the service. (pattern: <code>arn:[a-z0-9-]+:vpc-lattice:[a-zA-Z0-9-]+:\d{12}:service/svc-[0-9a-z]{17}</code>)
service_id	string	The ID of the service. (pattern: <code>svc-[0-9a-z]{17}</code>)

list_listeners

Name	Datatype	Description
id	string	The ID of the listener. (pattern: <code>listener-[0-9a-z]{17}</code>)
name	string	The name of the listener. (pattern: <code>(?!listener-)(?![-])(?!.[-]$)(?!.[-]{2})[a-z0-9-]+</code>)
arn	string	The Amazon Resource Name (ARN) of the listener. (pattern: <code>arn:[a-z0-9-]+:vpc-lattice:[a-zA-Z0-9-]+:\d{12}:service/svc-[0-9a-z]{17}/listener/listener-[0-9a-z]{17}</code>)
created_at	string (date-time)	The date and time that the listener was created, in ISO-8601 format.
last_updated_at	string (date-time)	The date and time that the listener was last updated, in ISO-8601 format.
port	integer	The listener port.
protocol	string	The listener protocol. (HTTP, HTTPS, TLS_PASSTHROUGH)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_listener	select	service_identifier, listener_identifier, region		Retrieves information about the specified listener for the specified service.
list_listeners	select	service_identifier, region	maxResults, nextToken	Lists the listeners for the specified service.
create_listener	insert	service_identifier, region, name, protocol, defaultAction		Creates a listener for a service. Before you start using your Amazon VPC Lattice service, you must add one or more listeners. A listener is a process that checks for connection requests to your services. For more information, see Listeners in the Amazon VPC Lattice User Guide.
update_listener	update	service_identifier, listener_identifier, region, defaultAction		Updates the specified listener for the specified service.
delete_listener	delete	service_identifier, listener_identifier, region		Deletes the specified listener.
batch_update_rule	exec	service_identifier, listener_identifier, region, rules		Updates the listener rules in a batch. You can use this operation to change the priority of listener rules. This can be useful when bulk updating or swapping rule priority. Required permissions: vpc-lattice:UpdateRule For more information, see How Amazon VPC Lattice works with IAM in the Amazon VPC Lattice User Guide.

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
listener_identifier	string	The ID or ARN of the listener.
region	string	AWS region (default: us-east-1)
service_identifier	string	The ID or ARN of the service.
maxResults	integer	The maximum number of results to return.
nextToken	string	A pagination token for the next page of results.

SELECT examples

get_listener

Retrieves information about the specified listener for the specified service.

SELECT
id,
name,
arn,
created_at,
default_action,
last_updated_at,
port,
protocol,
service_arn,
service_id
FROM aws.vpc_lattice.listeners
WHERE service_identifier = '{{ service_identifier }}' -- required
AND listener_identifier = '{{ listener_identifier }}' -- required
AND region = '{{ region }}' -- required
;

list_listeners

Lists the listeners for the specified service.

SELECT
id,
name,
arn,
created_at,
last_updated_at,
port,
protocol
FROM aws.vpc_lattice.listeners
WHERE service_identifier = '{{ service_identifier }}' -- required
AND region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

INSERT examples

create_listener

Creates a listener for a service. Before you start using your Amazon VPC Lattice service, you must add one or more listeners. A listener is a process that checks for connection requests to your services. For more information, see Listeners in the Amazon VPC Lattice User Guide.

INSERT INTO aws.vpc_lattice.listeners (
name,
protocol,
port,
defaultAction,
clientToken,
tags,
service_identifier,
region
)
SELECT 
'{{ name }}' /* required */,
'{{ protocol }}' /* required */,
{{ port }},
'{{ defaultAction }}' /* required */,
'{{ clientToken }}',
'{{ tags }}',
'{{ service_identifier }}',
'{{ region }}'
RETURNING
id,
name,
arn,
default_action,
port,
protocol,
service_arn,
service_id
;

Manifest

# Description fields are for documentation purposes
- name: listeners
props:
  - name: service_identifier
    value: "{{ service_identifier }}"
    description: Required parameter for the listeners resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the listeners resource.
  - name: name
    value: "{{ name }}"
  - name: protocol
    value: "{{ protocol }}"
    valid_values: ['HTTP', 'HTTPS', 'TLS_PASSTHROUGH']
  - name: port
    value: {{ port }}
  - name: defaultAction
    description: |
      Describes the action for a rule.
    value:
      forward:
        targetGroups:
          - targetGroupIdentifier: "{{ targetGroupIdentifier }}"
            weight: {{ weight }}
      fixedResponse:
        statusCode: {{ statusCode }}
  - name: clientToken
    value: "{{ clientToken }}"
  - name: tags
    value: "{{ tags }}"

UPDATE examples

update_listener

Updates the specified listener for the specified service.

UPDATE aws.vpc_lattice.listeners
SET 
defaultAction = '{{ defaultAction }}'
WHERE 
service_identifier = '{{ service_identifier }}' --required
AND listener_identifier = '{{ listener_identifier }}' --required
AND region = '{{ region }}' --required
AND defaultAction = '{{ defaultAction }}' --required
RETURNING
id,
name,
arn,
default_action,
port,
protocol,
service_arn,
service_id;

DELETE examples

delete_listener

Deletes the specified listener.

DELETE FROM aws.vpc_lattice.listeners
WHERE service_identifier = '{{ service_identifier }}' --required
AND listener_identifier = '{{ listener_identifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

batch_update_rule

Updates the listener rules in a batch. You can use this operation to change the priority of listener rules. This can be useful when bulk updating or swapping rule priority. Required permissions: vpc-lattice:UpdateRule For more information, see How Amazon VPC Lattice works with IAM in the Amazon VPC Lattice User Guide.

EXEC aws.vpc_lattice.listeners.batch_update_rule 
@service_identifier='{{ service_identifier }}' --required, 
@listener_identifier='{{ listener_identifier }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"rules": "{{ rules }}"
}'
;