3.2.1

Edge Function

Resource Overview

An Edge Function represents an AWS Lambda@Edge function.

Lambda@Edge functions are Lambda functions that are subscribed to events emitted from a CloudFront distribution's request cycle. Once a Lambda@Edge Function is defined, it gets propagated to all of the AWS edge locations around the world.

As a result, it allows you to modify static content or responses that are cached at edge locations which saves time and improves performance.

With that in mind, this resource is suitable for latency sensitive use cases in which your end users are distributed globally. Decisions on how to serve content to end users can be made based on user characteristics gathered at CDN edge locations.

Lambda@Edge use cases include:

  • Dynamically routing requests to different origins based on a users location and responding with region specific content
  • Authenticating and authorizing users before accessing content from the origin.
  • Adding HTTP security headers on responses without modifying the origin

More examples, including related blog posts, can be found in the AWS Lambda@Edge product overview under Use Cases

AWS Lambda@Edge

AWS Lambda@Edge shares many key benefits with AWS Lambda like automatically scaling to usage, and pay-per-use pricing models, but need to meet additional requirements and restrictions as described below:

  • Defined in the us-east-1 (N. Virginia) region
  • Work exclusively with the Node.js runtime
  • Do not have access to Lambda environment variables *
  • Cannot access resources inside a Virtual Network
  • Cannot be associated with a CDN distribution in another AWS account

* Stackery implements a custom solution that provide Edge Functions with access to environment variables; a crucial feature currently unavailable with a standalone Lambda@Edge function. See Common Lambda@Edge Concerns below.

In addition to Lambda@Edge Function requirements and restrictions, the AWS Developer Guide specifies additional Lambda@Edge Function limits to consider

Common Lambda@Edge Concerns

Lambda Environment Variables

Accessing environment variables in your Lambda@Edge function is possible with Stackery Edge Functions.

Environment variables can be defined using the Edge Function resource configuration panel. They are injected into the function at runtime and are referenced by using process.env(node.js).

Edge Functions can utilize service discovery wires and are capable of environment aware service discovery and permission scoping for other cloud resources. See the Service Discovery section below for the list of resources.

us-east-1 Region

Regardless of which region the stack's Environment deploys to, Stackery automatically provision the Edge Function in the us-east-1 region.

Versioning

The newest version of an Edge Function is automatically published and distributed to edge locations for use when the stack is deployed.

Implementation

Edge Function + CDN

Edge Functions are meant to be implemented alongside a CDN. This is because Edge Functions can only be subscribed to events that occur within a CDN's request cycle.

An Edge Function is associated with one or more CDN distributions, where users have access to the cache behavior and event. The CDN distribution, cache behavior, and event make up the CDN trigger responsible for invoking your Edge Function.

Distribution : Which CDN the Function is deployed to.

Cache Behavior : Configuration of your CDN functionality for a given URL path pattern. Stackery automatically configures this to use the default cache behavior /*.

CDN events that can be used to trigger Functions :

  • Viewer Request

    Edge Function is invoked when the CDN receives a request from an end user. Occurs before the CDN checks if the requested data is in its cache.

  • Origin Request

    Edge Function is invoked only when the CDN forwards a request to your origin. If the requested data is in the CDN cache, the Edge Function assigned to this event does not execute.

  • Origin Response

    Edge Function is invoked when the CDN receives a response from your origin. Occurs before the CDN caches the origin's response data. An Edge Function assigned to this event is triggered even if the origin returns an error.

  • Viewer Response

    Edge Function is invoked when the CDN returns the requested data to the end user. An Edge Function assigned to this event is triggered regardless of whether the data is already present in the CDN's cache.

When deciding which CDN event should trigger your Edge Function, consider these questions from the AWS Developer Guide, as well as additional clarifying questions from this helpful AWS blog post in the Choose the right trigger section.

Service Discovery

An Edge Function adopts the permissions and environment variables required to perform actions using cloud resources within the stack. This occurs when a service discovery wire (dashed line) is connected from this resource to another resource in the stack.

Edge Functions are capable of environment aware service discovery and permission scoping for the following resources:

  • Function
  • Docker Task
  • GraphQL API
  • Job Queue
  • Object Store
  • PubSub Topic
  • REST API
  • Stream
  • Table
  • Timer
  • User Pool

Edge Functions do not have access to these resources if they are placed inside a Virtual Network

Configurable Properties

Display Name

Human readable name for this resource that is displayed on the Stackery Dashboard and Stackery CLI output.

Logical ID

The unique identifier used to reference this resource in the stack template. Defining a custom Logical ID is recommended, as it allows you to quickly identify a resource and any associated sub-resources when working with your stack in AWS, or anywhere outside of the Stackery Dashboard. As a project grows, it becomes useful in quickly spotting this resource in template.yaml or while viewing a stack in Template View mode.

The Logical ID of all sub-resources associated with this Edge Function will be prefixed with this value.

The identifier you provide must only contain alphanumeric characters (A-Za-z0-9) and be unique within the stack.

Default Logical ID Example: EdgeFunction2

IMPORTANT : AWS uses the Logical ID of each resource to coordinate and apply updates to the stack when deployed. On any update of a resource's logical ID (or any modification that results in one), CloudFormation will delete the currently deployed resource and create a new one in it's place when the updated stack is deployed.

Runtime

Edge Functions can use the following runtime versions:

Source Path

You can designate a specific path within the repository that houses the Edge Function's source code. Edge Functions are given an auto-generated name and stored within the 'src' folder by default.

Handler

The handler serves as the function's entry point; the method that is executed when the function is invoked.

Default Handler Names:

  • Node.js - index.handler

Memory Size

The amount of memory allocated to the Edge Function process.

Limits for memory size differ between event types.

Origin Request & Response Events: 3008 MB

Viewer Request & Response Events: 128 MB

If these limits are exceeded, the Edge Function invocation will be terminated

Timeout

The maximum amount of time the Edge Function can spend executing. An error will occur if the timeout is reached before the function completes execution.

Limits for function timeouts differ between event types.

Origin Request & Response Events: 30 seconds

Viewer Request & Response Events: 5 seconds

Permissions

SAM or IAM permission policies which grant your Edge Function permission to perform actions on other Cloud Resources. Edge Function permissions are automatically populated when you connect a service discovery wire (dashed wire) from a Edge Function to another Cloud Resource. You also have the ability to manually define these permissions that your Edge Function requires.

Environment Variables

Environment variables are key-value pairs that enable users to define variables in the runtime environment that will dynamically populate in your Edge Function. Edge Function environment variables are automatically populated when you connect a service discovery wire (dashed wire) from a Edge Function to another Cloud Resource. You also have the ability to manually define these environment variables that your Edge Function requires.

Metrics & Logs

Edge Functions are replicated to edge locations in each AWS Region. Because of this, Edge Functions can be invoked in different AWS Regions and their logs will be sent to the CloudWatch of that region.

  • Example: If an Edge Function is invoked at an edge location in the us-west-2 (Oregon) region, function logs can be found in the us-west-2 region's CloudWatch logs.

The AWS Developer Guide provides a useful script to helpfind your Lambda@Edge logs

← Docker TaskFunction →