VPCLattice / Client / create_listener

create_listener#

VPCLattice.Client.create_listener(**kwargs)#

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.

Request Syntax

response = client.create_listener(
    clientToken='string',
    defaultAction={
        'fixedResponse': {
            'statusCode': 123
        },
        'forward': {
            'targetGroups': [
                {
                    'targetGroupIdentifier': 'string',
                    'weight': 123
                },
            ]
        }
    },
    name='string',
    port=123,
    protocol='HTTP'|'HTTPS',
    serviceIdentifier='string',
    tags={
        'string': 'string'
    }
)

Parameters:

clientToken (string) –
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. If you retry a request that completed successfully using the same client token and parameters, the retry succeeds without performing any actions. If the parameters aren’t identical, the retry fails.

This field is autopopulated if not provided.
defaultAction (dict) –
[REQUIRED]

The action for the default rule. Each listener has a default rule. Each rule consists of a priority, one or more actions, and one or more conditions. The default rule is the rule that’s used if no other rules match. Each rule must include exactly one of the following types of actions: forward ``or ``fixed-response, and it must be the last action to be performed.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: fixedResponse, forward.
- fixedResponse (dict) –
  
  Describes the rule action that returns a custom HTTP response.
  - statusCode (integer) – [REQUIRED]
    
    The HTTP response code.
- forward (dict) –
  
  The forward action. Traffic that matches the rule is forwarded to the specified target groups.
  - targetGroups (list) – [REQUIRED]
    
    The target groups. Traffic matching the rule is forwarded to the specified target groups. With forward actions, you can assign a weight that controls the prioritization and selection of each target group. This means that requests are distributed to individual target groups based on their weights. For example, if two target groups have the same weight, each target group receives half of the traffic.
    
    The default value is 1. This means that if only one target group is provided, there is no need to set the weight; 100% of traffic will go to that target group.
    - (dict) –
      
      Describes the weight of a target group.
      - targetGroupIdentifier (string) – [REQUIRED]
        
        The ID or Amazon Resource Name (ARN) of the target group.
      - weight (integer) –
        
        Only required if you specify multiple target groups for a forward action. The “weight” determines how requests are distributed to the target group. For example, if you specify two target groups, each with a weight of 10, each target group receives half the requests. If you specify two target groups, one with a weight of 10 and the other with a weight of 20, the target group with a weight of 20 receives twice as many requests as the other target group. If there’s only one target group specified, then the default value is 100.
name (string) –
[REQUIRED]

The name of the listener. A listener name must be unique within a service. The valid characters are a-z, 0-9, and hyphens (-). You can’t use a hyphen as the first or last character, or immediately after another hyphen.
port (integer) – The listener port. You can specify a value from 1 to 65535. For HTTP, the default is 80. For HTTPS, the default is 443.
protocol (string) –
[REQUIRED]

The listener protocol HTTP or HTTPS.
serviceIdentifier (string) –
[REQUIRED]

The ID or Amazon Resource Name (ARN) of the service.
tags (dict) –
The tags for the listener.
- (string) –
  
  The key of the tag.
  
  Constraints: Tag keys are case-sensitive and accept a maximum of 128 Unicode characters. Valid characters are Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @ May not begin with aws:.
  - (string) –
    
    The value of the tag.
    
    Constraints: Tag values are case-sensitive and accept a maximum of 256 Unicode characters. Valid characters are Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @

Return type:

dict

Returns:

Response Syntax

{
    'arn': 'string',
    'defaultAction': {
        'fixedResponse': {
            'statusCode': 123
        },
        'forward': {
            'targetGroups': [
                {
                    'targetGroupIdentifier': 'string',
                    'weight': 123
                },
            ]
        }
    },
    'id': 'string',
    'name': 'string',
    'port': 123,
    'protocol': 'HTTP'|'HTTPS',
    'serviceArn': 'string',
    'serviceId': 'string'
}

Response Structure

(dict) –
- arn (string) –
  
  The Amazon Resource Name (ARN) of the listener.
- defaultAction (dict) –
  
  The action for the default rule.
  Note
  This is a Tagged Union structure. Only one of the following top level keys will be set: fixedResponse, forward. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
  'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
  - fixedResponse (dict) –
    
    Describes the rule action that returns a custom HTTP response.
    - statusCode (integer) –
      
      The HTTP response code.
  - forward (dict) –
    
    The forward action. Traffic that matches the rule is forwarded to the specified target groups.
    - targetGroups (list) –
      
      The target groups. Traffic matching the rule is forwarded to the specified target groups. With forward actions, you can assign a weight that controls the prioritization and selection of each target group. This means that requests are distributed to individual target groups based on their weights. For example, if two target groups have the same weight, each target group receives half of the traffic.
      
      The default value is 1. This means that if only one target group is provided, there is no need to set the weight; 100% of traffic will go to that target group.
      - (dict) –
        
        Describes the weight of a target group.
        
        targetGroupIdentifier (string) –
        
        The ID or Amazon Resource Name (ARN) of the target group.
        
        weight (integer) –
        
        Only required if you specify multiple target groups for a forward action. The “weight” determines how requests are distributed to the target group. For example, if you specify two target groups, each with a weight of 10, each target group receives half the requests. If you specify two target groups, one with a weight of 10 and the other with a weight of 20, the target group with a weight of 20 receives twice as many requests as the other target group. If there’s only one target group specified, then the default value is 100.
- id (string) –
  
  The ID of the listener.
- name (string) –
  
  The name of the listener.
- port (integer) –
  
  The port number of the listener.
- protocol (string) –
  
  The protocol of the listener.
- serviceArn (string) –
  
  The Amazon Resource Name (ARN) of the service.
- serviceId (string) –
  
  The ID of the service.

Exceptions

VPCLattice.Client.exceptions.ValidationException
VPCLattice.Client.exceptions.AccessDeniedException
VPCLattice.Client.exceptions.ThrottlingException
VPCLattice.Client.exceptions.ResourceNotFoundException
VPCLattice.Client.exceptions.ConflictException
VPCLattice.Client.exceptions.ServiceQuotaExceededException
VPCLattice.Client.exceptions.InternalServerException