Skip to content

Latest commit

 

History

History
executable file
·
119 lines (76 loc) · 9.26 KB

using-extensions.md

File metadata and controls

executable file
·
119 lines (76 loc) · 9.26 KB

Using Lambda extensions

You can use Lambda extensions to augment your Lambda functions. For example, use Lambda extensions to integrate functions with your preferred monitoring, observability, security, and governance tools. You can choose from a broad set of tools that AWS Lambda Partners provides, or you can create your own Lambda extensions.

Lambda supports external and internal extensions. An external extension runs as an independent process in the execution environment and continues to run after the function invocation is fully processed. Because extensions run as separate processes, you can write them in a different language than the function.

An internal extension runs as part of the runtime process. Your function accesses internal extensions by using wrapper scripts or in-process mechanisms such as JAVA_TOOL_OPTIONS. For more information, see Modifying the runtime environment.

You can add extensions to a function using the Lambda console, the AWS Command Line Interface (AWS CLI), or infrastructure as code (IaC) services and tools such as AWS CloudFormation, AWS Serverless Application Model (AWS SAM), and Terraform.

The following Lambda runtimes support extensions:

  • .NET Core 3.1 (C#/PowerShell) (dotnetcore3.1)
  • Custom runtime (provided)
  • Custom runtime on Amazon Linux 2 (provided.al2)
  • Java 11 (Corretto) (java11)
  • Java 8 (Corretto) (java8.al2)
  • Node.js 14.x (nodejs14.x)
  • Node.js 12.x (nodejs12.x)
  • Node.js 10.x (nodejs10.x)
  • Python 3.9 (python3.9)
  • Python 3.8 (python3.8)
  • Python 3.7 (python3.7)
  • Ruby 2.7 (ruby2.7)
  • Ruby 2.5 (ruby2.5)

Note that the Go 1.x runtime does not support extensions. To support extensions, you can create Go functions on the provided.al2 runtime. For more information, see Migrating Lambda functions to Amazon Linux 2.

You are charged for the execution time that the extension consumes (in 1 ms increments). For more pricing information for extensions, see AWS Lambda Pricing. For pricing information for partner extensions, see those partners' websites. There is no cost to install your own extensions.

Topics

Execution environment

Lambda invokes your function in an execution environment, which provides a secure and isolated runtime environment. The execution environment manages the resources required to run your function and provides lifecycle support for the function's runtime and extensions.

The lifecycle of the execution environment includes the following phases:

  • Init: In this phase, Lambda creates or unfreezes an execution environment with the configured resources, downloads the code for the function and all layers, initializes any extensions, initializes the runtime, and then runs the function’s initialization code (the code outside the main handler). The Init phase happens either during the first invocation, or in advance of function invocations if you have enabled provisioned concurrency.

    The Init phase is split into three sub-phases: Extension init, Runtime init, and Function init. These sub-phases ensure that all extensions and the runtime complete their setup tasks before the function code runs.

  • Invoke: In this phase, Lambda invokes the function handler. After the function runs to completion, Lambda prepares to handle another function invocation.

  • Shutdown: This phase is triggered if the Lambda function does not receive any invocations for a period of time. In the Shutdown phase, Lambda shuts down the runtime, alerts the extensions to let them stop cleanly, and then removes the environment. Lambda sends a Shutdown event to each extension, which tells the extension that the environment is about to be shut down.

During the Init phase, Lambda extracts layers containing extensions into the /opt directory in the execution environment. Lambda looks for extensions in the /opt/extensions/ directory, interprets each file as an executable bootstrap for launching the extension, and starts all extensions in parallel.

Impact on performance and resources

The size of your function's extensions counts towards the deployment package size limit. For a .zip file archive, the total unzipped size of the function and all extensions cannot exceed the unzipped deployment package size limit of 250 MB.

Extensions can impact the performance of your function because they share function resources such as CPU, memory, and storage. For example, if an extension performs compute-intensive operations, you may see your function's execution duration increase.

Each extension must complete its initialization before Lambda invokes the function. Therefore, an extension that consumes significant initialization time can increase the latency of the function invocation.

To measure the extra time that the extension takes after the function execution, you can use the PostRuntimeExtensionsDuration function metric. To measure the increase in memory used, you can use the MaxMemoryUsed metric. To understand the impact of a specific extension, you can run different versions of your functions side by side.

Permissions

Extensions have access to the same resources as functions. Because extensions are executed within the same environment as the function, permissions are shared between the function and the extension.

For a .zip file archive, you can create an AWS CloudFormation template to simplify the task of attaching the same extension configuration—including AWS Identity and Access Management (IAM) permissions—to multiple functions.

Configuring extensions (.zip file archive)

You can add an extension to your function as a Lambda layer. Using layers enables you to share extensions across your organization or to the entire community of Lambda developers. You can add one or more extensions to a layer. You can register up to 10 extensions for a function.

You add the extension to your function using the same method as you would for any layer. For more information, see Using layers with your Lambda function.

Add an extension to your function (console)

  1. Open the Functions page of the Lambda console.

  2. Choose a function.

  3. Choose the Code tab if it is not already selected.

  4. Under Layers, choose Edit.

  5. For Choose a layer, choose Specify an ARN.

  6. For Specify an ARN, enter the Amazon Resource Name (ARN) of an extension layer.

  7. Choose Add.

Using extensions in container images

You can add extensions to your container image. The ENTRYPOINT container image setting specifies the main process for the function. Configure the ENTRYPOINT setting in the Dockerfile, or as an override in the function configuration.

You can run multiple processes within a container. Lambda manages the lifecycle of the main process and any additional processes. Lambda uses the Extensions API to manage the extension lifecycle.

Example: Adding an external extension

An external extension runs in a separate process from the Lambda function. Lambda starts a process for each extension in the /opt/extensions/ directory. Lambda uses the Extensions API to manage the extension lifecycle. After the function has run to completion, Lambda sends a Shutdown event to each external extension.

Example of adding an external extension to a Python base image

FROM public.ecr.aws/lambda/python:3.8

# Copy and install the app
COPY /app /app
WORKDIR /app
RUN pip install -r requirements.txt

# Add an extension from the local directory into /opt
ADD my-extension.zip /opt
CMD python ./my-function.py

Next steps

To learn more about extensions, we recommend the following resources: