README-DEPLOY.md

How to deploy the AWS Lambda Power Tuning tool

There are 5 deployment options for deploying the tool using Infrastructure as Code (IaC).

1. The easiest way is to deploy the app via the AWS Serverless Application Repository (SAR).
2. Using the AWS SAM CLI
3. Using the AWS CDK
4. Using Terraform by Hashicorp and SAR
5. Using native Terraform

Read more about the deployment parameters here.

Option 1: AWS Serverless Application Repository

You can find this app in the Serverless Application Repository and deploy it with just a few clicks in the AWS Management Console.

You can also integrate the SAR app in your existing CloudFormation stacks - check scripts/deploy-sar-app.yml and scripts/deploy-sar-app.sh for a sample implementation.

Option 2: Build and deploy with the AWS SAM CLI

Note: This method requires Docker.

1. Install the AWS SAM CLI in your local environment.

2. Configure your AWS credentials (requires AWS CLI installed):

   $ aws configure

3. Install Docker.

4. Clone this git repository:

   $ git clone https://github.com/alexcasalboni/aws-lambda-power-tuning.git

5. Build the Lambda layer and any other dependencies (Docker is required):

   $ cd ./aws-lambda-power-tuning
   $ sam build -u

   sam build -u will run SAM build using a Docker container image that provides an environment similar to that which your function would run in. SAM build in-turn looks at your AWS SAM template file for information about Lambda functions and layers in this project.

   Once the build completes successfully you will see output stating Build Succeeded. If the build is not successful, there will be error messages providing guidance on what went wrong.

6. Deploy the application using the guided SAM deploy mode:

   $ sam deploy -g

   • For Stack Name, enter a unique name for the stack.
   • For AWS Region, enter the region you want to deploy in.

   Accept the defaults for all other prompts.

   sam deploy -g provides simple prompts to walk you through the process of deploying the tool. The responses are saved in a configuration file, samconfig.toml, to be reused during subsequent deployments.

   SAM CLI will run the required commands to create the resources for the Lambda Power Tuning tool.

   A successful deployment displays the message Successfully created/updated stack.

7. To delete Lambda Power Tuning, run

   sam delete

   Answer Y to the prompts.

Option 3: Deploy the AWS SAR app with AWS CDK

1. Install AWS CDK.

   $ npm install -g aws-cdk

2. Bootstrap your account.

3. Configure your AWS credentials:

   $ aws configure

4. If you already have a CDK project you can include the following to use the sam module:

   import sam = require('@aws-cdk/aws-sam');
   
   new sam.CfnApplication(this, 'powerTuner', {
     location: {
       applicationId: 'arn:aws:serverlessrepo:us-east-1:451282441545:applications/aws-lambda-power-tuning',
       semanticVersion: '4.3.6'
     },
     parameters: {
       "lambdaResource": "*",
       "PowerValues": "128,256,512,1024,1536,3008"
     }
   })

Alternatively, you can build and deploy the solution from the source in this repo. See the following pages for language-specific instructions.

TypeScript

See the Typescript instructions

Python

See the Python instructions

go

See the go instructions

C#

See the Csharp instructions

Option 4: Deploy the SAR app with Terraform

Simply add the aws_serverlessapplicationrepository_cloudformation_stack resource below to your Terraform code and deploy as usual through terraform apply.

resource "aws_serverlessapplicationrepository_cloudformation_stack" "lambda-power-tuning" {
  name             = "lambda-power-tuner"
  application_id   = "arn:aws:serverlessrepo:us-east-1:451282441545:applications/aws-lambda-power-tuning"
  capabilities     = ["CAPABILITY_IAM"]
  # Uncomment the next line to deploy a specific version
  # semantic_version = "4.3.6"

  parameters = {
    # All of these parameters are optional and are only shown here for demonstration purposes
    # See https://github.com/alexcasalboni/aws-lambda-power-tuning/blob/master/README-INPUT-OUTPUT.md#state-machine-input-at-deployment-time
    # PowerValues           = "128,192,256,512,1024,2048,3072,4096,5120,6144,7168,8192,9216,10240"
    # lambdaResource        = "*"
    # totalExecutionTimeout = 900
    # visualizationURL      = "https://lambda-power-tuning.show/"
  }
}

See the Terraform documentation for more configuration options of aws_serverlessapplicationrepository_cloudformation_stack.

If you don't yet have a Terraform project, check out the Terraform introduction.

Option 5: Deploy natively with Terraform

The Terraform modules are located in the terraform directory. Deployment documentation is here.

State machine configuration (at deployment time)

The CloudFormation template (used for option 1 to 4) accepts the following parameters:

Parameter	Description
PowerValues type: list of numbers default: [128,256,512,1024,1536,3008]	These power values (in MB) will be used as the default in case no powerValues input parameter is provided at execution time.
visualizationURL type: string default: lambda-power-tuning.show	The base URL for the visualization tool, you can bring your own visualization tool.
totalExecutionTimeout type: number default: 300	The timeout in seconds applied to all functions of the state machine.
lambdaResource type: string default: *	The Resource used in IAM policies; it's * by default but you could restrict it to a prefix or a specific function ARN.
permissionsBoundary type: string	The ARN of a permissions boundary (policy), applied to all functions of the state machine.
payloadS3Bucket type: string	The S3 bucket name used for large payloads (>256KB); if provided, it's added to a custom managed IAM policy that grants read-only permission to the S3 bucket; more details in the S3 payloads section.
payloadS3Key type: string default: *	The S3 object key used for large payloads (>256KB); the default value grants access to all S3 objects in the bucket specified with payloadS3Bucket; more details in the S3 payloads section.
layerSdkName type: string	The name of the SDK layer, in case you need to customize it (optional).
logGroupRetentionInDays type: number default: 7	The number of days to retain log events in the Lambda log groups (a week by default).
securityGroupIds type: list of SecurityGroup IDs	List of Security Groups to use in every Lambda function's VPC Configuration (optional); please note that your VPC should be configured to allow public internet access (via NAT Gateway) or include VPC Endpoints to the Lambda service.
subnetIds type: list of Subnet IDs	List of Subnets to use in every Lambda function's VPC Configuration (optional); please note that your VPC should be configured to allow public internet access (via NAT Gateway) or include VPC Endpoints to the Lambda service.
stateMachineNamePrefix type: string default: powerTuningStateMachine	Allows you to customize the name of the state machine. Maximum 43 characters, only alphanumeric (plus - and _). The last portion of the AWS::StackId will be appended to this value, so the full name will look like powerTuningStateMachine-89549da0-a4f9-11ee-844d-12a2895ed91f. Note: StateMachineName has a maximum of 80 characters and 36+1 from the StackId are appended, allowing 43 for a custom prefix.

Please note that the total execution time should stay below 300 seconds (5 min), which is the default timeout. You can estimate the total execution timeout based on the average duration of your functions. For example, if your function's average execution time is 5 seconds and you haven't enabled parallelInvocation, you should set totalExecutionTimeout to at least num * 5: 50 seconds if num=10, 500 seconds if num=100, and so on. If you have enabled parallelInvocation, usually you don't need to tune the value of totalExecutionTimeout unless your average execution time is above 5 min. If you have set a sleep between invocations, remember to include that in your timeout calculations.

How to execute the state machine once deployed

See the execution instructions to run the state machine.