# Listeners for your VPC Lattice service
Before you start using your VPC Lattice service, you must add a *listener*. A listener is a process that checks for connection requests, using the protocol and port that you configure. The rules that you define for a listener determine how the service routes requests to its registered targets.
![\[A service with a listener, listener rules, and two target groups.\]](http://docs.aws.amazon.com/vpc-lattice/latest/ug/images/service.png)
**Topics**
+ [Listener configuration](#listener-configuration)
+ [HTTP listeners](http-listeners.md)
+ [HTTPS listeners](https-listeners.md)
+ [TLS listeners](tls-listeners.md)
+ [Listener rules](listener-rules.md)
+ [Delete a listener](delete-listener.md)
## Listener configuration
Listeners support the following protocols and ports:
+ **Protocols**: HTTP, HTTPS, TLS
+ **Ports**: 1-65535
If the listener protocol is HTTPS, VPC Lattice will provision and manage a TLS certificate that is associated with the VPC Lattice generated FQDN. VPC Lattice supports TLS on HTTP/1.1 and HTTP/2. When you configure a service with an HTTPS listener, VPC Lattice will automatically determine the HTTP protocol using Application-Layer Protocol Negotiation (ALPN). If ALPN is absent, VPC Lattice defaults to HTTP/1.1. For more information, see [HTTPS listeners](https-listeners.md).
VPC Lattice can listen on HTTP, HTTPS, HTTP/1.1, and HTTP/2 and communicate to targets in any of these protocols and versions. We do not require that the listener and target group protocols match. VPC Lattice manages the entire process of upgrading and downgrading between protocols and versions. For more information, see [Protocol version](target-groups.md#target-group-protocol-version).
You can create a TLS listener to ensure that your application decrypts the encrypted traffic instead of VPC Lattice. For more information, see [TLS listeners](tls-listeners.md).
VPC Lattice does not natively support WebSockets. However, you can still connect to Websocket-based services by using TLS Listeners or routing through VPC Lattice resources.
# HTTP listeners for VPC Lattice services
A listener is a process that checks for connection requests. You can define a listener when you create your VPC Lattice service. You can add listeners to your service at any time.
The information on this page helps you create an HTTP listener for your service. For information about creating listeners that use other protocols, see [HTTPS listeners](https-listeners.md) and [TLS listeners](tls-listeners.md).
## Prerequisites
+ To add a forward action to the default listener rule, you must specify an available VPC Lattice target group. For more information, see [Create a VPC Lattice target group](create-target-group.md).
+ You can specify the same target group in multiple listeners, but these listeners must belong to the same service. To use a target group with a VPC Lattice service, you must verify that it is not used by a listener for any other VPC Lattice service.
## Add an HTTP listener
You can add listeners and rules to your service at any time. You configure a listener with a protocol and a port for connections from clients to the service, and a VPC Lattice target group for the default listener rule. For more information, see [Listener configuration](listeners.md#listener-configuration).
**To add an HTTP listener using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, under **VPC Lattice**, choose **Services**.
1. Select the name of the service to open its details page.
1. On the **Routing** tab, choose **Add listener**.
1. For **Listener name**, you can either provide a custom listener name, or use the protocol and port of your listener as the listener name. A custom name that you specify can have up to 63 characters, and it must be unique for every service in your account. 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. You cannot change the name after you create it.
1. For **Protocol : port**, choose **HTTP** and enter a port number.
1. For **Default action**, choose the VPC Lattice target group to receive traffic and choose the weight to assign to this target group. The weight that you assign to a target group sets its priority to receive traffic. For example, if two target groups have the same weight, each target group receives half of the traffic. If you've specified only one target group, then 100 percent of the traffic is sent to the one target group.
You can optionally add another target group for the default action. Choose **Add action** and then choose a target group and specify its weight.
1. (Optional) To add another rule, choose **Add rule** and then enter a name, a priority, a condition, and an action for the rule.
You can give each rule a priority number between 1 and 100. A listener can't have multiple rules with the same priority. Rules are evaluated in priority order, from the lowest value to the highest value. The default rule is evaluated last. For more information, see [Listener rules](listener-rules.md).
1. (Optional) To add tags, expand **Listener tags**, choose **Add new tag**, and enter a tag key and tag value.
1. Review your configuration, and then choose **Add**.
**To add an HTTP listener using the AWS CLI**
Use the [create-listener](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/create-listener.html) command to create a listener with a default rule, and the [create-rule](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/create-rule.html) command to create additional listener rules.
# HTTPS listeners for VPC Lattice services
A listener is a process that checks for connection requests. You define a listener when you create your service. You can add listeners to your service in VPC Lattice at any time.
You can create an HTTPS listener, which uses TLS version 1.2 or TLS version 1.3 to terminate HTTPS connections with VPC Lattice directly. VPC Lattice will provision and manage a TLS certificate that is associated with the VPC Lattice generated Fully Qualified Domain Name (FQDN). VPC Lattice supports TLS on HTTP/1.1 and HTTP/2. When you configure a service with an HTTPS listener, VPC Lattice will automatically determine the HTTP protocol via Application-Layer Protocol Negotiation (ALPN). If ALPN is absent, VPC Lattice defaults to HTTP/1.1.
VPC Lattice uses a multi-tenancy architecture, meaning that it can host multiple services on the same endpoint. VPC Lattice uses TLS with Server Name Indication (SNI) for every client request. Encrypted Client Hello (ECH) and Encrypted Server Name Indication (ESNI) aren't supported.
VPC Lattice can listen on HTTP, HTTPS, HTTP/1.1, and HTTP/2 and communicate to targets in any of these protocols and versions. These listener and target group configurations do not need to match. VPC Lattice manages the entire process of upgrading and downgrading between protocols and versions. For more information, see [Protocol version](target-groups.md#target-group-protocol-version).
To ensure that your application decrypts the traffic, create a TLS listener instead. With TLS passthrough, VPC Lattice does not terminate TLS. For more information, see [TLS listeners](tls-listeners.md).
**Contents**
+ [Security policy](#listener-security-policy)
+ [ALPN policy](#listener-alpn-policy)
+ [Add an HTTPS listener](#add-https-listener)
## Security policy
VPC Lattice uses a security policy that is a combination a TLSv1.2 protocol and a list of SSL/TLS ciphers. The protocol establishes a secure connection between a client and a server and helps to ensure that all data passed between the client and your service in VPC Lattice is private. A cipher is an encryption algorithm that uses encryption keys to create a coded message. Protocols use several ciphers to encrypt data. During the connection negotiation process, the client and VPC Lattice present a list of ciphers and protocols that they each support, in order of preference. By default, the first cipher on the server's list that matches any one of the client's ciphers is selected for the secure connection.
VPC Lattice uses the following TLS 1.2 SSL/TLS ciphers in this order of preference:
+ `ECDHE-RSA-AES128-GCM-SHA256`
+ `ECDHE-RSA-AES128-SHA`
+ `ECDHE-RSA-AES256-GCM-SHA384`
+ `ECDHE-RSA-AES256-SHA`
+ `AES128-GCM-SHA256`
+ `AES128-SHA`
+ `AES256-GCM-SHA384`
+ `AES256-SHA`
VPC Lattice also uses the following TLS 1.3 SSL/TLS ciphers in this order of preference:
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
## ALPN policy
*Application-Layer Protocol Negotiation (ALPN)* is a TLS extension that is sent on the initial TLS handshake hello messages. ALPN enables the application layer to negotiate which protocols should be used over a secure connection, such as HTTP/1 and HTTP/2.
When the client initiates an ALPN connection, the VPC Lattice service compares the client ALPN preference list with its ALPN policy. If the client supports a protocol from the ALPN policy, the VPC Lattice service establishes the connection based on the preference list of the ALPN policy. Otherwise, the service does not use ALPN.
VPC Lattice supports the following ALPN policy:
`HTTP2Preferred`
Prefer HTTP/2 over HTTP/1.1. The ALPN preference list is h2, http/1.1.
## Add an HTTPS listener
You configure a listener with a protocol and a port for connections from clients to the service, and a target group for the default listener rule. For more information, see [Listener configuration](listeners.md#listener-configuration).
**Prerequisites**
+ To add a forward action to the default listener rule, you must specify an available VPC Lattice target group. For more information, see [Create a VPC Lattice target group](create-target-group.md).
+ You can specify the same target group in multiple listeners, but these listeners must belong to the same VPC Lattice service. To use a target group with a VPC Lattice service, you must verify that it is not used by a listener for any other VPC Lattice service.
+ You can use the certificate provided by VPC Lattice or import your own certificate to AWS Certificate Manager. For more information, see [Bring Your Own Certificate (BYOC) for VPC Lattice](service-byoc.md).
**To add an HTTPS listener using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, under **VPC Lattice**, choose **Services**.
1. Select the name of the service to open its details page.
1. On the **Routing** tab, choose **Add listener**.
1. For **Listener name**, you can either provide a custom listener name or use the protocol and port of your listener as the listener name. A custom name that you specify can have up to 63 characters, and it must be unique for every service in your account. 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. You cannot change the name of a listener after you create it.
1. For **Protocol : port**, choose **HTTPS** and enter a port number.
1. For **Default action**, choose the VPC Lattice target group to receive traffic and choose the weight to assign to this target group. The weight that you assign to a target group sets its priority to receive traffic. For example, if two target groups have the same weight, each target group receives half of the traffic. If you've specified only one target group, then 100 percent of the traffic is sent to the one target group.
You can optionally add another target group for the default action. Choose **Add action** and then choose a target group and specify its weight.
1. (Optional) To add another rule, choose **Add rule** and then enter a name, a priority, a condition, and an action for the rule.
You can give each rule a priority number between 1 and 100. A listener can't have multiple rules with the same priority. Rules are evaluated in priority order, from the lowest value to the highest value. The default rule is evaluated last. For more information, see [Listener rules](listener-rules.md).
1. (Optional) To add tags, expand **Listener tags**, choose Add new tag, and enter a tag key and tag value.
1. For **HTTPS listener certificate settings**, if you did not specify a custom domain name when you created the service, VPC Lattice automatically generates a TLS certificate to secure the traffic flowing though the listener.
If you created the service with a custom domain name, but didn't specify a matching certificate, you can do so now by choosing the certificate from **Custom SSL/TLS certificate**. Otherwise, the certificate that you specified when you created the service is already chosen.
1. Review your configuration, and then choose **Add**.
**To add an HTTPS listener using the AWS CLI**
Use the [create-listener](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/create-listener.html) command to create a listener with a default rule, and the [create-rule](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/create-rule.html) command to create additional listener rules.
# TLS listeners for VPC Lattice services
A listener is a process that checks for connection requests. You can define a listener when you create your VPC Lattice service. You can add listeners to your service at any time.
You can create a TLS listener so that VPC Lattice passes encrypted traffic through to your applications without decrypting it.
If you prefer that VPC Lattice decrypts encrypted traffic and sends unencrypted traffic to your applications, create an HTTPS listener instead. For more information, see [HTTPS listeners](https-listeners.md).
## Considerations
The following considerations apply to TLS listeners:
+ The VPC Lattice service must have a custom domain name. The service custom domain name is used as a Service Name Indication (SNI) match. If you specified a certificate when you created the service, it is not used.
+ The only rule allowed for a TLS listener is the default rule.
+ The default action for a TLS listener must be a forward action to a TCP target group.
+ By default, health checks are disabled for TCP target groups. If you enable health checks for a TCP target group, you must specify a protocol and protocol version.
+ TLS listeners route requests using the SNI field of the client-hello message. You can use wildcard and SAN certificates on your targets if the matching condition is an exact match to the client-hello.
+ Because all traffic remains encrypted from the client to the target, VPC Lattice can't read the HTTP headers and can't insert or remove HTTP headers. Therefore, with a TLS listener, the following limitations exist:
+ Connection duration is limited to 10 minutes
+ Auth policies are limited to anonymous principals
+ Lambda targets are not supported
+ Websocket connections can use TLS Listeners to connect to , VPC Lattice services. The following limitations exist:
+ Connection duration is limited to 10 minutes
+ Auth policies are limited to anonymous principals
+ Lambda targets are not supported
+ Encrypted Client Hello (ECH) isn't supported.
+ Encrypted Server Name Indication (ESNI) isn't supported.
## Add a TLS listener
You configure a listener with a protocol and a port for connections from clients to the service, and a target group for the default listener rule. For more information, see [Listener configuration](listeners.md#listener-configuration).
**To add a TLS listener using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, under **VPC Lattice**, choose **Services**.
1. Select the name of the service to open its details page.
1. On the **Routing** tab, choose **Add listener**.
1. For **Listener name**, you can either provide a custom listener name or use the protocol and port of your listener as the listener name. A custom name that you specify can have up to 63 characters, and it must be unique for every service in your account. 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. You cannot change the name of a listener after you create it.
1. For **Protocol**, choose **TLS**. For **Port**, enter a port number.
1. For **Forward to target group**, choose a VPC Lattice target group that uses the TCP protocol to receive the traffic, and choose the weight to assign to this target group. You can optionally add another target group. Choose **Add target group** and then choose a target group and enter its weight.
1. (Optional) To add tags, expand **Listener tags**, choose Add new tag, and enter a tag key and tag value.
1. Review your configuration, and then choose **Add**.
**To add a TLS listener using the AWS CLI**
Use the [create-listener](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/create-listener.html) command to create a listener with a default rule. Specify the TLS\$1PASSTHROUGH protocol.
# Listener rules for your VPC Lattice service
Each listener has a default rule and additional rules that you can define. Each rule consists of a priority, one or more actions, and one or more conditions. You can add or edit rules at any time.
**Topics**
+ [Default rules](#listener-default-rule)
+ [Rule priority](#listener-rule-priority)
+ [Rule action](#listener-rule-actions)
+ [Rule conditions](#listener-rule-conditions)
+ [Add a rule](#add-rules)
+ [Update a rule](#update-rules)
+ [Delete a rule](#delete-rules)
## Default rules
When you create a listener, you define actions for the default rule. Default rules can't have conditions. If the conditions for none of a listener's rules are met, then the action for the default rule is performed.
## Rule priority
Each rule has a priority. Rules are evaluated in priority order, from the lowest value to the highest value. The default rule is evaluated last. You can change the priority of a non-default rule at any time. You cannot change the priority of the default rule.
## Rule action
Listeners for VPC Lattice services support forward actions and fixed response actions.
### Forward actions
You can use `forward` actions to route requests to one or more VPC Lattice target groups. If you specify multiple target groups for a `forward` action, you must specify a weight for each target group. Each target group weight is a value from 0 to 999. Requests that match a listener rule with weighted target groups are distributed to these target groups based on their weights. 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.
### Fixed-response actions
You can use `fixed-response` actions to drop client requests and return a custom HTTP response. You can use this action to return a 404 or a 500 response code.
**Example fixed response action for the AWS CLI**
You can specify an action when you create or update a rule. The following action sends a fixed response with the specified status code.
```
"action": {
"fixedResponse": {
"statusCode": 404
},
```
## Rule conditions
Each rule condition has a type and configuration information. When the conditions for a rule are met, then its actions are performed.
The following are the supported matching criteria for a rule:
**Header match**
Routing is based on the HTTP headers for each request. You can use HTTP header conditions to configure rules that route requests based on the HTTP headers for the request. You can specify the names of standard or custom HTTP header fields. The header name and the match evaluation are not case sensitive. You can change this setting by turning on case-sensitivity. Wildcard characters are not supported in the header name. Prefix, exact, and contains matching are supported on header match.
**Method match**
Routing is based on the HTTP request method of each request.
You can use HTTP request method conditions to configure rules that route requests based on the HTTP request method of the request. You can specify standard or custom HTTP methods. The method match is case sensitive. The method name must be an exact match. Wildcard characters are not supported.
**Path match**
Routing is based on matching the path patterns in the request URLs.
You can use path conditions to define rules that route requests based on the URL in the request. Wildcard characters are not supported. Prefix and exact matching on path are supported.
## Add a rule
You can add a listener rule at any time.
**To add a listener rule using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, under **VPC Lattice**, choose **Services**.
1. Select the name of the service to open its details page.
1. On the **Routing** tab, choose **Edit listener**.
1. Expand **Listener rules** and choose **Add rule**.
1. For **Rule name**, enter a name for the rule.
1. For **Priority**, enter a priority between 1 and 100. Rules are evaluated in priority order, from the lowest value to the highest value. The default rule is evaluated last.
1. For **Condition**, enter a path pattern for the path match condition. The maximum size of each string is 200 characters. The comparison is not case sensitive. Wildcard characters are not supported.
To add a header match or method match rule condition, use the AWS CLI or an AWS SDK.
1. For **Action**, choose a VPC Lattice target group.
1. Choose **Save changes**.
**To add a rule using the AWS CLI**
Use the [create-rule](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/create-rule.html) command.
## Update a rule
You can update a listener rule at any time. You can modify its priority, condition, target group, and the weight of each target group. You can't modify the name of the rule.
**To update a listener rule using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, under **VPC Lattice**, choose **Services**.
1. Select the name of the service to open its details page.
1. On the **Routing** tab, choose **Edit listener**.
1. Modify the rule priorities, conditions, and actions as needed.
1. Review your updates and choose **Save changes**.
**To update a rule using the AWS CLI**
Use the [update-rule](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/update-rule.html) command.
## Delete a rule
You can delete the non-default rules for a listener at any time. You cannot delete the default rule for a listener. When you delete a listener, all of its rules are deleted.
**To delete a listener rule using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, under **VPC Lattice**, choose **Services**.
1. Select the name of the service to open its details page.
1. On the **Routing** tab, choose **Edit listener**.
1. Find the rule and choose **Remove**.
1. Choose **Save changes**.
**To delete a rule using the AWS CLI**
Use the [delete-rule](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/delete-rule.html) command.
# Delete a listener for your VPC Lattice service
You can delete a listener at any time. When you delete a listener, all its rules are automatically deleted.
**To delete a listener using the console**
1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).
1. In the navigation pane, under **VPC Lattice**, choose **Services**.
1. Select the name of the service to open its details page.
1. On the **Routing** tab, choose **Delete listener**.
1. When prompted for confirmation, enter **confirm** and then choose **Delete**.
**To delete a listener using the AWS CLI**
Use the [delete-listener](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/delete-listener.html) command.