# Add triggers for a Lambda@Edge function
<a name="lambda-edge-add-triggers"></a>

A Lambda@Edge trigger is one combination of a CloudFront distribution, cache behavior, and event that causes a function to execute. For example, you can create a trigger that causes the function to execute when CloudFront receives a request from a viewer for a specific cache behavior you set up for your distribution. You can specify one or more CloudFront triggers. 

**Tip**  
When you create a CloudFront distribution, you specify settings that tell CloudFront how to respond when it receives different requests. The default settings are called the *default cache behavior* for the distribution. You can set up additional cache behaviors that define how CloudFront responds under specific circumstances, for example, when it receives a request for a specific file type. For more information, see [Cache behavior settings](DownloadDistValuesCacheBehavior.md).

When you first create a Lambda function, you can specify only *one* trigger. You can add more triggers to the same function later by using the Lambda console or by editing the distribution in the CloudFront console.
+ The Lambda console works well if you want to add more triggers to a function for the same CloudFront distribution.
+ The CloudFront console can be better if you want to add triggers for multiple distributions because it's easier to find the distribution that you want to update. You can also update other CloudFront settings at the same time.

**Topics**
+ [CloudFront events that can trigger a Lambda@Edge function](lambda-cloudfront-trigger-events.md)
+ [Choose the event to trigger the function](lambda-how-to-choose-event.md)
+ [Add triggers to a Lambda@Edge function](lambda-edge-add-triggers-console.md)

# CloudFront events that can trigger a Lambda@Edge function
<a name="lambda-cloudfront-trigger-events"></a>

For each cache behavior in a Amazon CloudFront distribution, you can add up to four triggers (associations) that cause a Lambda function to execute when specific CloudFront events occur. CloudFront triggers can be based on one of four CloudFront events, as shown in the following diagram.

![\[Conceptual graphic that shows how CloudFront trigger events for Lambda functions integrate with CloudFront.\]](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/images/cloudfront-events-that-trigger-lambda-functions.png)


The CloudFront events that can be used to trigger Lambda@Edge functions are the following:

**Viewer request**  
The function executes when CloudFront receives a request from a viewer, before it checks to see whether the requested object is in the CloudFront cache.  
The function doesn't execute in the following cases:  
+ When fetching a custom error page.
+ When CloudFront automatically redirects an HTTP request to HTTPS (when the value of the [Viewer protocol policy](DownloadDistValuesCacheBehavior.md#DownloadDistValuesViewerProtocolPolicy) is **Redirect HTTP to HTTPS**).

**Origin request**  
The function executes *only* when CloudFront forwards a request to your origin. When the requested object is in the CloudFront cache, the function doesn't execute.

**Origin response**  
The function executes after CloudFront receives a response from the origin and before it caches the object in the response. Note that the function executes even if an error is returned from the origin.  
The function doesn't execute in the following cases:  
+ When the requested file is in the CloudFront cache and is not expired.
+ When the response is generated from a function that was triggered by an origin request event.

**Viewer response**  
The function executes before returning the requested file to the viewer. Note that the function executes regardless of whether the file is already in the CloudFront cache.  
The function doesn't execute in the following cases:  
+ When the origin returns an HTTP status code of 400 or higher.
+ When a custom error page is returned.
+ When the response is generated from a function that was triggered by a viewer request event.
+ When CloudFront automatically redirects an HTTP request to HTTPS (when the value of the [Viewer protocol policy](DownloadDistValuesCacheBehavior.md#DownloadDistValuesViewerProtocolPolicy) is **Redirect HTTP to HTTPS**).

When you add multiple triggers to the same cache behavior, you can use them to run the same function or run different functions for each trigger. You can also associate the same function with more than one distribution.

**Note**  
When a CloudFront event triggers the execution of a Lambda function, the function must finish *before* CloudFront can continue.   
For example, if a Lambda function is triggered by a CloudFront viewer request event, CloudFront won't return a response to the viewer or forward the request to the origin until the Lambda function finishes running.   
This means that each request that triggers a Lambda function increases latency for the request, so you want the function to execute as fast as possible.

# Choose the event to trigger the function
<a name="lambda-how-to-choose-event"></a>

When you're deciding which CloudFront event you want to use to trigger a Lambda function, consider the following:

**I want CloudFront to cache objects that are changed by a Lambda function**  
To cache an object that was modified by a Lambda function so that CloudFront can serve the object from the edge location the next time it's requested, use the *origin request* or *origin response* event.   
This reduces the load on the origin, reduces latency for subsequent requests, and reduces the cost of invoking Lambda@Edge on subsequent requests.  
For example, if you want to add, remove, or change headers for objects that are returned by the origin and you want CloudFront to cache the result, use the origin response event.

**I want the function to execute for every request**  
To execute the function for every request that CloudFront receives for the distribution, use the *viewer request* or *viewer response* events.   
Origin request and origin response events occur only when a requested object isn't cached in an edge location and CloudFront forwards a request to the origin.

**I want the function to change the cache key**  
To change a value that you're using as a basis for caching, use the *viewer request* event.   
For example, if a function changes the URL to include a language abbreviation in the path (for example, because the user chose their language from a dropdown list), use the viewer request event:  
+ **URL in the viewer request** – https://example.com/en/index.html
+ **URL when the request comes from an IP address in Germany** – https://example.com/de/index.html
You also use the viewer request event if you're caching based on cookies or request headers.  
If the function changes cookies or headers, configure CloudFront to forward the applicable part of the request to the origin. For more information, see the following topics:  
+ [Cache content based on cookies](Cookies.md)
+ [Cache content based on request headers](header-caching.md)

**The function affects the response from the origin**  
To change the request in a way that affects the response from the origin, use the *origin request* event.   
Typically, most viewer request events aren't forwarded to the origin. CloudFront responds to a request with an object that's already in the edge cache. If the function changes the request based on an origin request event, CloudFront caches the response to the changed origin request.

# Add triggers to a Lambda@Edge function
<a name="lambda-edge-add-triggers-console"></a>

You can use the AWS Lambda console or Amazon CloudFront console to add a trigger to your Lambda@Edge function.

**Important**  
You can create triggers only for numbered versions of your function (not the **\$1LATEST**).

------
#### [ Lambda console ]<a name="lambda-edge-add-triggers-procedure"></a>

**To add triggers for CloudFront events to a Lambda@Edge function**

1. Sign in to the AWS Management Console and open the AWS Lambda console at [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).

1. In the Region list at the top of the page, choose **US East (N. Virginia)**.

1. On the **Functions** page, choose the name of the function that you want to add triggers for.

1. On the **Function overview** page, choose the **Versions** tab.

1. Choose the version that you want to add triggers to.

   After you choose a version, the name of the button changes to **Version: \$1LATEST** or **Version:** *version number*.

1. Choose the **Triggers** tab.

1. Choose **Add trigger**.

1. For **Trigger configuration**, choose **Select a source**, enter **cloudfront**, and then choose **CloudFront**.
**Note**  
If you've already created one or more triggers, CloudFront is the default service.

1. Specify the following values to indicate when you want the Lambda function to execute.

   1. **Distribution** – Choose the distribution that you want to add the trigger to.

   1. **Cache behavior** – Choose the cache behavior that specifies the objects that you want to execute the function on.
**Note**  
If you specify `*` for the cache behavior, the Lambda function deploys to the default cache behavior.

   1. **CloudFront event** – Choose the CloudFront event that causes the function to execute.

   1. **Include body** – Select this check box if you want to access the request body in your function. 

   1. **Confirm deploy to Lambda@Edge** – Select this check box so that AWS Lambda replicates the function to AWS Regions globally.

1. Choose **Add**.

   The function starts to process requests for the specified CloudFront events when the updated CloudFront distribution is deployed. To determine whether a distribution is deployed, choose **Distributions** in the navigation pane. When a distribution is deployed, the value of the **Status** column for the distribution changes from **Deploying** to the date and time of deployment.

------
#### [ CloudFront console ]<a name="lambda-create-functions-add-triggers-cloudfront-console-procedure"></a>

**To add triggers for CloudFront events to a Lambda@Edge function**

1. Get the ARN of the Lambda function that you want to add triggers for:

   1. Sign in to the AWS Management Console and open the AWS Lambda console at [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).

   1. In the list of Regions at the top of the page, choose **US East (N. Virginia)**.

   1. In the list of functions, choose name of the function that you want to add triggers to.

   1. On the **Function overview** page, choose the **Versions** tab, and choose the numbered version that you want to add triggers to.

   1. Choose the **Copy ARN** button to copy the ARN to your clipboard. The ARN for the Lambda function looks something like this:

      `arn:aws:lambda:us-east-1:123456789012:function:TestFunction:2`

      The number at the end (**2** in this example) is the version number of the function.

1. Open the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home).

1. In the list of distributions, choose the ID of the distribution that you want to add triggers to.

1. Choose the **Behaviors** tab.

1. Select the cache behavior that you want to add triggers to, and then choose **Edit**.

1. For **Function associations**, in the **Function type** list, choose **Lambda@Edge** for when you want the function to execute: for viewer requests, viewer responses, origin requests, or origin responses. 

   For more information, see [Choose the event to trigger the function](lambda-how-to-choose-event.md).

1. In the **Function ARN / Name** text box, paste the ARN of the Lambda function that you want to execute when the chosen event occurs. This is the value that you copied from the Lambda console.

1. Select **Include body** if you want to access the request body in your function.

   If you just want to replace the request body, you don't need to select this option.

1. To execute the same function for more event types, repeat steps 6 and 7.

1. Choose **Save changes**.

1. To add triggers to more cache behaviors for this distribution, repeat steps 5 through 10.

   The function starts to process requests for the specified CloudFront events when the updated CloudFront distribution is deployed. To determine whether a distribution is deployed, choose **Distributions** in the navigation pane. When a distribution is deployed, the value of the **Status** column for the distribution changes from **Deploying** to the time and date of deployment.

------