# Use the AWS FIS aws:lambda:function actions You can use the **aws:lambda:function** actions to inject faults into invocations of your AWS Lambda functions. These actions use an AWS FIS managed extension to inject faults. To use **aws:lambda:function** actions, you will need to attach the extension as a layer to your Lambda functions and configure an Amazon S3 bucket to communicate between AWS FIS and the extension. When you run an AWS FIS experiment targeting **aws:lambda:function**, AWS FIS reads the Amazon S3 configuration from your Lambda function and writes fault injection information to the specified Amazon S3 location, as shown in the diagram below. ![\[Diagram showing the configuration of the AWS Fault Injection Service Lambda extension.\]](http://docs.aws.amazon.com/fis/latest/userguide/images/Serverless-config-distro-3.png) ## Actions + [aws:lambda:invocation-add-delay](fis-actions-reference.md#invocation-add-delay) + [aws:lambda:invocation-error](fis-actions-reference.md#invocation-error) + [aws:lambda:invocation-http-integration-response](fis-actions-reference.md#invocation-http-integration-response) ## Limitations + The AWS FIS Lambda extension cannot be used with functions that use response streaming. Even when no faults are applied, the AWS FIS Lambda extension will suppress streaming configurations. For more information, see [Response streaming for Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html) in the *AWS Lambda user guide*. ## Prerequisites Before using AWS FIS Lambda actions, ensure that you have completed these one-time tasks: + **Create an Amazon S3 bucket in the region you plan to start an experiment from** ‐ You can use a single Amazon S3 bucket for multiple experiments and share the bucket between multiple AWS accounts. However, you must have a separate bucket for each AWS Region. + **Create an IAM policy to grant read access for the Lambda extension to the Amazon S3 bucket** ‐ In the following template, replace `my-config-distribution-bucket` with the name of the Amazon S3 bucket you created above and `FisConfigs` with the name of a folder in your Amazon S3 bucket you want to use. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowListingConfigLocation", "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::my-config-distribution-bucket"], "Condition": { "StringLike": { "s3:prefix": ["FisConfigs/*"] } } }, { "Sid": "AllowReadingObjectFromConfigLocation", "Effect": "Allow", "Action": "s3:GetObject", "Resource": ["arn:aws:s3:::my-config-distribution-bucket/FisConfigs/*"] } ] } ``` ------ + **Create an IAM policy to grant write access for the AWS FIS experiment to the Amazon S3 bucket** ‐ In the following template, replace `my-config-distribution-bucket` with the name of the Amazon S3 bucket you created above and `FisConfigs` with the name of a folder in your Amazon S3 bucket you want to use. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowFisToWriteAndDeleteFaultConfigurations", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::my-config-distribution-bucket/FisConfigs/*" }, { "Sid": "AllowFisToInspectLambdaFunctions", "Effect": "Allow", "Action": [ "lambda:GetFunction" ], "Resource": "*" }, { "Sid": "AllowFisToDoTagLookups", "Effect": "Allow", "Action": [ "tag:GetResources" ], "Resource": "*" } ] } ``` ------ ## Configure Lambda functions Follow the steps below for every Lambda function that you want to impact: 1. Attach the Amazon S3 read access policy created above to the Lambda function. 1. Attach the AWS FIS extension as a layer to the function. For more information on the layer ARNs, see [Available versions of the AWS FIS extension for Lambda](actions-lambda-extension-arns.md). 1. Set the `AWS_FIS_CONFIGURATION_LOCATION` variable to the ARN of the Amazon S3 configuration folder, for example `arn:aws:s3:::my-config-distribution-bucket/FisConfigs/`. 1. Set the `AWS_LAMBDA_EXEC_WRAPPER` variable to `/opt/aws-fis/bootstrap`. ## Configure an AWS FIS experiment Before running your experiment, ensure that you have attached the Amazon S3 write access policy that you created in the prerequisites to the experiment roles that will use AWS FIS Lambda actions. For more information on how to set up an AWS FIS experiment, see [Managing AWS FIS experiment templatesManaging your AWS FIS experiments](experiments.md). ## Logging The AWS FIS Lambda extension writes logs to the console and CloudWatch logs. Logging can be configured using the `AWS_FIS_LOG_LEVEL` variable. Supported values are `INFO`, `WARN`, and `ERROR`. Logs will be written in the log format configured for your Lambda function. The following is an example of a log in text format: ``` 2024-08-09T18:51:38.599984Z INFO AWS FIS EXTENSION - extension enabled 1.0.1 ``` The following is an example of a log in JSON format: ``` { "timestamp": "2024-10-08T17:15:36.953905Z", "level": "INFO", "fields": { "message": "AWS FIS EXTENSION - adding 5000 milliseconds of latency to function invocation", "requestId":"0608bf70-908f-4a17-bbfe-3782cd783d8b" } } ``` The emitted logs can be used with Amazon CloudWatch metric filters to generate custom metrics. For more information on metric filters, see [Creating metrics from log events using filters](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/MonitoringLogData.html) in the *Amazon CloudWatch Logs user guide*. ### Using CloudWatch Embedded Metric Format (EMF) You can configure the AWS FIS Lambda extension to emit EMF logs by setting the `AWS_FIS_EXTENSION_METRICS` variable to `all`. By default, the extension does not emit EMF logs, and `AWS_FIS_EXTENSION_METRICS` defaults to `none`. EMF logs are published in the `aws-fis-extension namespace` on the CloudWatch console. Within the `aws-fis-extension` namespace, you can select certain metrics to be displayed in a graph. The example below shows some of the available metrics in the `aws-fis-extension` namespace. ![\[Example graph of output EMF metrics in the CloudWatch dashboard.\]](http://docs.aws.amazon.com/fis/latest/userguide/images/emf-metrics-graph.png) ## Advanced topics This section provides additional information on how AWS FIS works with the Lambda extension and special use cases. **Topics** + [ ### Understanding polling ](#understanding-polling) + [ ### Understanding concurrency ](#understanding-concurrency) + [ ### Understanding invocation percentage ](#understanding-invocation-percentage) + [ ### Special considerations for SnapStart ](#considerations-for-snapshot) + [ ### Special considerations for fast infrequent functions ](#considerations-for-fast-infrequent-functions) + [ ### Configuring multiple extensions using Lambda Runtime API proxy ](#configuring-multiple-extensions) + [ ### Using AWS FIS with container runtimes ](#container-runtimes) + [ ### AWS FIS Lambda environment variables ](#fis-extension-environment-variables) ### Understanding polling You may notice a ramp-up period of up to 60s before faults begin to affect all invocations. This is because the Lambda extension polls for configuration information infrequently while waiting for an experiment to start. You can adjust the polling interval by setting the `AWS_FIS_SLOW_POLL_INTERVAL_SECONDS` environment variable (default 60s). A lower value will poll more often but incur greater performance impact and cost. You may also notice a ramp-down period of up to 20s after the fault has been injected. This is because the extension polls more frequently while experiments are running. ### Understanding concurrency You may target the same Lambda functions with multiple actions concurrently. If the actions are all different from each other, then all actions will be applied. For example, you can add an initial delay before returning an error. If two identical or conflicting actions are applied to the same function, then only the action with the earliest start date will be applied. The figure below shows two conflicting actions, **aws:lambda:invocation-error** and **aws:lambda:invocation-http-integration-response**, overlapping. Initially, **aws:lambda:invocation-error** ramps up at 11:38 and runs for 2 minutes. Then, **aws:lambda:invocation-http-integration-response** attempts to start at 11:39, but does not come into effect until 11:40 after the first action has concluded. To maintain experiment timing, **aws:lambda:invocation-http-integration-response** still finishes at the originally intended time of 11:41. ![\[Graphs showing error and response code percentages for x86 and arm during overlapping actions.\]](http://docs.aws.amazon.com/fis/latest/userguide/images/understanding-concurrency.png) ### Understanding invocation percentage The AWS Fault Injection Service Lambda actions use an **aws:lambda:function** target which allows you to select one or more AWS Lambda function ARNs. Using these ARNs, the AWS Fault Injection Service Lambda actions can inject faults in every invocation of the selected Lambda function. To allow you to inject faults into only a fraction of invocations, each action allows you to specify an `invocationPercentage` parameter with values from 0 to 100. Using the `invocationPercentage` parameter, you can ensure that actions are concurrent even for invocation percentages below 100%. ### Special considerations for SnapStart AWS Lambda functions with SnapStart enabled will have a higher likelihood of waiting the full duration of `AWS_FIS_SLOW_POLL_INTERVAL_SECONDS` before picking up the first fault configuration, even if an experiment is already running. This is because Lambda SnapStart uses a single snapshot as the initial state for multiple execution environments and persists temporary storage. For the AWS Fault Injection Service Lambda extension it will persist polling frequency and skip the initial configuration check on initialization of the execution environment. For more information on Lambda SnapStart, see [Improving startup performance with Lambda SnapStart](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html) in the *AWS Lambda user guide.* ### Special considerations for fast infrequent functions If your Lambda function runs for less than the average poll duration of 70 milliseconds then the polling thread may need multiple invocations to obtain fault configurations. If the function runs infrequently, for example once every 15 minutes, then the poll will never be completed. To ensure the polling thread can finish, set the `AWS_FIS_POLL_MAX_WAIT_MILLISECONDS` parameter. The extension will wait up to the duration that you set for an in-flight poll to finish before starting the function. Note that this will increase the billed function duration and lead to an additional delay on some invocations. ### Configuring multiple extensions using Lambda Runtime API proxy The Lambda extension uses the AWS Lambda Runtime API proxy to intercept function invocations before they reach the runtime. It does this by exposing a proxy for the AWS Lambda Runtime API to the runtime and advertising its location in the `AWS_LAMBDA_RUNTIME_API` variable. The following diagram shows the configuration for a single extension using the Lambda Runtime API proxy: ![\[The default configuration.\]](http://docs.aws.amazon.com/fis/latest/userguide/images/Proxy-1.png) To use the AWS FIS Lambda extension with another extension using the AWS Lambda Runtime API proxy pattern, you will need to chain the proxies using a custom bootstrap script. The AWS FIS Lambda extension accepts the following environment variables: + `AWS_FIS_PROXY_RUNTIME_API_ENDPOINT` ‐ Takes a string in the form `127.0.0.1:9876` representing the local IP and listener port for the AWS Lambda Runtime API. This could be the original value of `AWS_LAMBDA_RUNTIME_API` or the location of another proxy. + `AWS_FIS_PROXY_LISTENER_PORT` ‐ Takes a port number on which the AWS FIS extension should start its own proxy, by default `9100`. With these settings you can chain the AWS FIS extension with another extension using the Lambda Runtime API proxy in two different orders. ![\[Two chained extensions using the Lambda API proxy.\]](http://docs.aws.amazon.com/fis/latest/userguide/images/lambda-runtime-api-proxy.png) For more information on the AWS Lambda Runtime API proxy, see [ Enhancing runtime security and governance with the AWS Lambda Runtime API proxy extension](https://aws.amazon.com/blogs/compute/enhancing-runtime-security-and-governance-with-the-aws-lambda-runtime-api-proxy-extension/) and [Using the Lambda runtime API for custom runtimes](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html) in the *AWS Lambda user guide*. ### Using AWS FIS with container runtimes For AWS Lambda functions using container images that accept the `AWS_LAMBDA_RUNTIME_API` environment variable, you can package the AWS FIS Lambda extension into your container image by following the steps below: 1. Determine the ARN of the layer from which to extract the extension. For more information on how to find the ARN, see [Configure Lambda functions](#configure-lambda-functions). 1. Use the AWS Command Line Interface (CLI) to request details about the extension `aws lambda get-layer-version-by-arn --arn fis-extension-arn`. The response will contain a `Location` field containing a pre-signed URL from which you can download the FIS extension as a ZIP file. 1. Unzip the content of the extension into `/opt` of your Docker filesystem. The following is an example Dockerfile based on the NodeJS Lambda runtime: ``` # extension installation # FROM amazon/aws-lambda-nodejs:12 AS builder COPY extension.zip extension.zip RUN yum install -y unzip RUN mkdir -p /opt RUN unzip extension.zip -d /opt RUN rm -f extension.zip FROM amazon/aws-lambda-nodejs:12 WORKDIR /opt COPY --from=builder /opt . # extension installation finished # # JS example. Modify as required by your runtime WORKDIR ${LAMBDA_TASK_ROOT} COPY index.js package.json . RUN npm install CMD [ "index.handler" ] ``` For more information on container images, see [Create a Lambda function using a container image](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html) in the *AWS Lambda user guide*. ### AWS FIS Lambda environment variables The following is a list of environment variables for the AWS FIS Lambda extension + `AWS_FIS_CONFIGURATION_LOCATION` ‐ Required. Location where AWS FIS will write active fault configurations and the extension will read fault configurations. The locations should be in Amazon S3 ARN format including a bucket and path. For example, `arn:aws:s3:::my-fis-config-bucket/FisConfigs/`. + `AWS_LAMBDA_EXEC_WRAPPER` ‐ Required. Location of the AWS Lambda [wrapper script](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-modify.html#runtime-wrapper) used to configure the AWS FIS Lambda extension. This should be set to the `/opt/aws-fis/bootstrap` script that is included with the extension. + `AWS_FIS_LOG_LEVEL` ‐ Optional. Log level for messages emitted by AWS FIS Lambda extension. Supported values are `INFO`, `WARN`, and `ERROR`. If not set, AWS FIS extension will default to `INFO`. + `AWS_FIS_EXTENSION_METRICS` ‐ Optional. Possible values are `all` and `none`. If set to `all` the extension will emit EMF metrics under the `aws-fis-extension namespace`. + `AWS_FIS_SLOW_POLL_INTERVAL_SECONDS` ‐ Optional. If set will override the polling interval (in seconds) while the extension is not injecting faults and waiting for a fault configuration to be added to configuration location. Defaults to `60`. + `AWS_FIS_PROXY_RUNTIME_API_ENDPOINT` ‐ Optional. If set will override the value of `AWS_LAMBDA_RUNTIME_API` to define where the AWS FIS extension interacts with the AWS Lambda runtime API to control function invocation. Expects IP:PORT, for example, `127.0.0.1:9000`. For more information on `AWS_LAMBDA_RUNTIME_API`, see [Using the Lambda runtime API for custom runtimes ](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html) in the *AWS Lambda user guide.* + `AWS_FIS_PROXY_LISTENER_PORT` ‐ Optional. Defines the port on which the AWS FIS Lambda extension exposes an AWS Lambda runtime API proxy that can be used by another extension or the runtime. Defaults to `9100`. + `AWS_FIS_POLL_MAX_WAIT_MILLISECONDS` ‐ Optional. If set to non-zero value, this variable defines the number of milliseconds the extension will wait for an in-flight async poll to finish before evaluating fault configurations and starting the invocation of the runtime. Defaults to `0`. # Available versions of the AWS FIS extension for Lambda This section includes information about the AWS FIS Lambda extension versions. The extension supports Lambda functions developed for the x86-64 and ARM64 (Graviton2) platforms. Your Lambda function must be configured to use the specific Amazon Resource Name (ARN) for the AWS Region where it is currently hosted. You can view AWS Region and ARN details below. **Topics** + [ ## AWS FIS Lambda extension release notes ](#extension-release-notes) + [ ## Access Guide for Lambda Extension ARNs ](#extension-arns-access-guide) + [ ## Finding your Lambda extension version number ](#extension-version-find) ## AWS FIS Lambda extension release notes The following table describes changes made to recent versions of the AWS FIS Lambda extension | Version | Launch date | Notes | | --- | --- | --- | | 1.0.0 | 2024-10-29 | Initial release | ## Access Guide for Lambda Extension ARNs You must have at least one parameter in your AWS account and AWS Region before you can search for public parameters using the console. To discover public parameters, see [Discovering public parameters in Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-finding-public-parameters.html). ### Console Access: 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Parameter Store**. 1. Choose the **Public parameters** tab. 1. Choose the **Select a service** dropdown. From the dropdown options, choose `fis`. 1. (Optional) Filter the parameters you selected by entering more information into the search bar. For arm64 architectures, filter parameters by entering *"arm64"*. For x86\$164 architectures, filter parameters by entering *"x86\$164"*. 1. Choose the public parameter you want to use. 1. From the parameter details, locate the ARN value. Copy the ARN to use in configuring layer extensions on your target Lambda functions. ### AWS CLI Access: #### SSM Parameter Names The following SSM parameter names are available for different architectures: 1. arm64: `/aws/service/fis/lambda-extension/AWS-FIS-extension-arm64/1.x.x` 1. x86\$164: `/aws/service/fis/lambda-extension/AWS-FIS-extension-x86_64/1.x.x` #### AWS CLI Command Format To retrieve the extension ARNs, use the following AWS CLI command format where *parameterName* is the name for the architecture and *region* is the target AWS Region: ``` aws ssm get-parameter --name parameterName --region region ``` #### Example Usage ``` aws ssm get-parameter --name /aws/service/fis/lambda-extension/AWS-FIS-extension-x86_64/1.x.x --region ap-southeast-2 ``` #### Response Format The command returns a JSON object containing the parameter details like the following. The ARN of the Lambda layer is included in the *Value* field of the *Parameter* object. Copy the ARN to use in configuring layer extensions on your target Lambda functions. ``` { "Parameter": { "Name": "/aws/service/fis/lambda-extension/AWS-FIS-extension-x86_64/1.x.x", "Type": "String", "Value": "arn:aws:lambda:ap-southeast-2:211125361907:layer:aws-fis-extension-x86_64:9", "Version": 1, "LastModifiedDate": "2025-01-02T15:13:54.465000-05:00", "ARN": "arn:aws:ssm:ap-southeast-2::parameter/aws/service/fis/lambda-extension/AWS-FIS-extension-x86_64/1.x.x", "DataType": "text" } } ``` ### Programmatic Access: Retrieve these public parameters programmatically when building or configuring your Lambda functions using Infrastructure as Code (IaC). This approach helps maintain your Lambda functions with the latest layer version ARN without requiring manual code updates that would be necessary if the AWS FIS extension layer ARN were hardcoded. The following resources show how to retrieve public parameters using common IaC platforms: + [Get public parameters using the AWS SDK](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html) + [Get public parameters from AWS Systems Manager Parameter Store using the AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/get-ssm-value.html) + [Get public parameters using Terraform](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) ## Finding your Lambda extension version number Use the following procedure to locate the version number of your currently configured AWS FIS Lambda extension. 1. Open the AWS Lambda console at [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. Choose the Lambda function where you want to add the `AWS-FIS-Extension` layer. 1. In the **Layers** section, choose **Edit**. 1. In the **Edit layers** section, choose **Add a layer**. 1. In the **Choose a layer** section, choose **Specify an ARN**. 1. Enter the ARN for the AWS FIS extension layer that corresponds to your AWS Region and architecture. You can find the ARN using the console, AWS CLI, or programmatic access methods described in the preceding sections. 1. Choose **Verify** to confirm the layer ARN is valid, then choose **Add**. 1. Use the **Test** tab to test the function. 1. After the test completes, view the log output. Locate the AWS FIS Lambda extension version in the **Details of the Execution** section.