Associating functions with distributions

To use a function in CloudFront Functions with a CloudFront distribution, you associate the function with one or more cache behaviors in the distribution. You can associate a function with multiple cache behaviors in multiple distributions. Before you associate a function, you must publish it to the LIVE stage.

When you associate a function with a cache behavior, you must choose an event type. The event type determines when CloudFront Functions runs the function. There are two event types to choose from:

For more information about event types, see CloudFront events that can trigger a Lambda@Edge function. You cannot use origin-facing event types (origin request and origin response) with CloudFront Functions.

• Viewer request – The function runs when CloudFront receives a request from a viewer.

• Viewer response – The function runs before CloudFront returns a response to the viewer.

You can associate a function with a distribution in the CloudFront console or with the AWS CLI.

Console

You can use the CloudFront console to associate a function with an existing cache behavior in an existing CloudFront distribution. For more information about creating a distribution, see Creating a distribution.

To associate a function with an existing cache behavior (console)

1. Open the Functions page in the CloudFront console at https://console.aws.amazon.com/cloudfront/v4/home#/functions, and then choose the name of the function that you want to associate.

2. On the function page, choose the Publish tab.

3. Choose Publish function.

4. Choose Add association. On the dialog that appears, select a distribution, an event type, and/or a cache behavior.

   For the event type, choose when you want this function to run:

   • To run the function every time CloudFront receives a request, choose Viewer Request.

   • To run the function every time CloudFront returns a response, choose Viewer Response.

   To save the configuration, choose Add association.

CloudFront associates the distribution with the function. Wait a few minutes for the associated distribution to finish deploying. You can choose View distribution on the function details page to check the progress.

CLI

You can associate a function with any of the following:

• An existing cache behavior.

• A new cache behavior in an existing distribution.

• A new cache behavior in a new distribution.

The following procedure shows how to associate a function with an existing cache behavior.

To associate a function with an existing cache behavior (AWS CLI)

1. Use the following command to save the distribution configuration for the distribution whose cache behavior you want to associate with a function. This command saves the distribution configuration to a file named dist-config.yaml. To use this command, do the following:

   • Replace DistributionID with the distribution's ID.

   • Run the command on one line. In the example, line breaks are provided to make the example more readable.

   aws cloudfront get-distribution-config \
       --id DistributionID \
       --output yaml > dist-config.yaml

   When the command is successful, the AWS CLI returns no output.

2. Open the file named dist-config.yaml that you just created. Edit the file to make the following changes.

   1. Rename the ETag field to IfMatch, but don't change the field's value.

   2. In the cache behavior, find the object named FunctionAssociations. Update this object to add a function association. The YAML syntax for a function association looks like the following example.

      • The following example shows a viewer request event type (trigger). To use a viewer response event type, replace viewer-request with viewer-response.

      • Replace arn:aws:cloudfront::111122223333:function/ExampleFunction with the Amazon Resource Name (ARN) of the function that you're associating with this cache behavior. To get the function ARN, you can use the aws cloudfront list-functions command.

      FunctionAssociations:
        Items:
          - EventType: viewer-request
            FunctionARN: arn:aws:cloudfront::111122223333:function/ExampleFunction
        Quantity: 1

   After making these changes, save the file.

3. Use the following command to update the distribution, adding the function association. To use this command, do the following:

   • Replace DistributionID with the distribution's ID.

   • Run the command on one line. In the example, line breaks are provided to make the example more readable.

   aws cloudfront update-distribution \
       --id DistributionID \
       --cli-input-yaml file://dist-config.yaml

   When the command is successful, you see output like the following that describes the distribution that was just updated with the function association. The following example output is truncated for readability.

   Distribution:
     ARN: arn:aws:cloudfront::111122223333:distribution/EBEDLT3BGRBBW
     ... truncated ...
     DistributionConfig:
       ... truncated ...
       DefaultCacheBehavior:
         ... truncated ...
         FunctionAssociations:
           Items:
           - EventType: viewer-request
             FunctionARN: arn:aws:cloudfront::111122223333:function/ExampleFunction
           Quantity: 1
         ... truncated ...
     DomainName: d111111abcdef8.cloudfront.net
     Id: EDFDVBD6EXAMPLE
     LastModifiedTime: '2021-04-19T22:39:09.158000+00:00'
     Status: InProgress
   ETag: E2VJGGQEG1JT8S

Effect of associating a distribution

The distribution's Status changes to InProgress while the distribution is redeployed. As soon as the new distribution configuration reaches a CloudFront edge location, that edge location begins using the associated function. When the distribution is fully deployed, the Status changes back to Deployed, which indicates that the associated CloudFront function is live in all CloudFront edge locations worldwide. This typically takes a few minutes.