Hot Swapping

Hot code swapping for Lambda functions using LocalStack’s code mounting

Complexity★☆☆☆☆
Time to read5 minutes
Editioncommunity/pro
Platformany

Quickly iterating over Lambda function code can be quite cumbersome, as you need to deploy your function on every change. With LocalStack you can avoid this hurdle by mounting your code directly from the source folder. This way, any saved change inside your source file directly affects the already deployed Lambda function – without any redeployment!

Covered Topics

Application Configuration Examples:

Deployment Configuration Examples:

Useful Links

Application Configuration Examples

Code hot-swapping for JVM Lambdas

Since lambda containers lifetime is usually limited, regular hot code swapping techniques are not applicable here.

In our implementation, we will be watching for fs changes under the project folder, then build a FatJar, unzip it, and mount it into the Lambda Docker Container.

We assume you already have:

  • watchman
  • configured JVM project capable of building FatJars using your preferred build tool

First, create a watchman wrapper by using one of our examples

Don’t forget to adjust permissions:

  1. $ chmod +x bin/watchman.sh

Now configure your build tool to unzip the FatJar to some folder, which will be then mounted to LocalStack. We are using Gradle build tool to unpack the FatJar into the build/hot folder:

  1. // We assume you are using something like `Shadow` plugin that comes with `shadowJar` task
  2. task buildHot(type: Copy) {
  3.     from zipTree("${project.buildDir}/libs/${project.name}-all.jar")
  4.     into "${project.buildDir}/hot"
  5. }
  6. buildHot.dependsOn shadowJar

Now run the following command to start watching your project in a hot-swapping mode:

  1. $ bin/watchman.sh src "./gradlew buildHot"

Please note that you still need to configure your deployment tool to use local code mounting. Read the “Deployment Configuration Examples” for more information.

Code hot-swapping for Python Lambdas

We will show you how you can do this with a simple example function, taken directly from the AWS Lambda developer guide.

You can check out that code, or use your own lambda functions to follow along. To use the example just do:

  1. $ cd /tmp
  2. $ git clone git@github.com:awsdocs/aws-doc-sdk-examples.git

Starting up LocalStack

First, we need to make sure we start LocalStack with the right configuration. This is as simple as setting LAMBDA_REMOTE_DOCKER(see the Configuration Documentation for more information):

  1. $ LAMBDA_REMOTE_DOCKER=0 localstack start

Accordingly, if you are launching LocalStack via Docker or Docker Compose:

  1. #docker-compose.yml
  3. services:
  4.   localstack:
  5.     ...
  6.     environment:
  7.       ...
  8.       - LAMBDA_REMOTE_DOCKER=false

Creating the Lambda Function

To create the Lambda function, you just need to take care of two things:

  1. Deploy via an S3 Bucket. You need to use the magic variable __local__ as the bucket.
  2. Set the S3 key to the path of the directory your lambda function resides in. The handler is then referenced by the filename of your lambda code and the function in that code that needs to be invoked.

So, using the AWS example, this would be:

  1. $ awslocal lambda create-function --function-name my-cool-local-function \
  2.     --code S3Bucket="__local__",S3Key="/tmp/aws-doc-sdk-examples/python/example_code/lambda/boto_client_examples" \
  3.     --handler lambda_handler_basic.lambda_handler \
  4.     --runtime python3.8 \
  5.     --role cool-stacklifter

You can also check out some of our “Deployment Configuration Examples”.

We can also quickly make sure that it works by invoking it with a simple payload:

  1. $ awslocal lambda invoke --function-name my-cool-local-function --payload '{"action": "square", "number": 3}' output.txt

The invocation returns itself returns:

  1. {
  2.     "StatusCode": 200,
  3.     "LogResult": "",
  4.     "ExecutedVersion": "$LATEST"
  5. }

and output.txt contains:

  1. {"result":9}

Changing things up

Now, that we got everything up and running, the fun begins. Because the function is now mounted as a file in the executing container, any change that we save on the file will be there in an instant.

For example, we can now make a minor change to the API and replace the response in line 41 with the following:

  1.     response = {'math_result': result}

Without redeploying or updating the function, the result of the previous request will look like this:

  1. {"math_result":9}

Cool!

Usage with Virtualenv

For virtualenv-driven projects, all dependencies should be made available to the Python interpreter at runtime. There are different ways to achieve that, including:

  • expanding the Python module search path in your Lambda handler
  • creating a watchman script to copy the libraries
Expanding the module search path in your Lambda handler

The easiest approach is to expand the module search path (sys.path) and add the site-packages folder inside the virtualenv. We can add the following two lines of code at the top of the Lambda handler script:

  1. import sys, glob
  2. sys.path.insert(0, glob.glob(".venv/lib/python*/site-packages")[0])
  3. ...
  4. import some_lib_from_virtualenv  # import your own modules here

This way you can easily import modules from your virtualenv, without having to change the file system layout.

Note: As an alternative to modifying sys.path, you could also set the PYTHONPATH environment variable when creating your Lambda function, to add the additional path.

Using a watchman script to copy libraries

Another alternative is to implement a watchman script that will be preparing a special folder for hot code swapping.

In our example, we are using build/hot folder as a mounting point for our Lambdas.

First, create a watchman wrapper by using one of our examples

After that, you can use the following Makefile snippet, or implement another shell script to prepare the codebase for hot swapping:

  1. BUILD_FOLDER ?= build
  2. PROJECT_MODULE_NAME = my_project_module
  4. build-hot:
  5.     rm -rf $(BUILD_FOLDER)/hot && mkdir -p $(BUILD_FOLDER)/hot
  6.     cp -r $(VENV_DIR)/lib/python$(shell python --version | grep -oE '[0-9]\.[0-9]')/site-packages/* $(BUILD_FOLDER)/hot/
  7.     cp -r $(PROJECT_MODULE_NAME) $(BUILD_FOLDER)/hot/$(PROJECT_MODULE_NAME)
  8.     cp *.toml $(BUILD_FOLDER)/hot
  10. watch:
  11.     bin/watchman.sh $(PROJECT_MODULE_NAME) "make build-hot"
  13. .PHONY: build-hot watch

To run the example above, run make watch. The script is copying the project module PROJECT_MODULE_NAME along with all dependencies into the build/hot folder, which is then mounted into LocalStack’s Lambda container.

Deployment Configuration Examples

Serverless Framework Configuration

Enable local code mounting

  1. custom:
  2.   localstack:
  3.     ...
  4.     lambda:
  5.       mountCode: true
  7. # or if you need to enable code mounting only for specific stages
  8. custom:
  9.   stages:
  10.     local:
  11.       mountCode: true
  12.     testing:
  13.       mountCode: false
  14.   localstack:
  15.     stages:
  16.       - local
  17.       - testing
  18.     lambda:
  19.       mountCode: ${self:custom.stages.${opt:stage}.mountCode}

Pass LAMBDA_MOUNT_CWD env var with path to the built code directory (in our case to the folder with unzipped FatJar):

  1. $ LAMBDA_MOUNT_CWD=$(pwd)/build/hot serverless deploy --stage local

AWS Cloud Development Kit (CDK) Configuration

  1.  1
  2.  2
  3.  3
  4.  4
  5.  5
  6.  6
  7.  7
  8.  8
  9.  9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28
  29. 29
  30. 30
  31. 31
  32. 32
  33. 33
  34. 34
  35. 35
  36. 36
  37. 37
  38. 38
  39. 39
  40. 40
  1. package org.localstack.cdkstack
  3. import java.util.UUID
  4. import software.amazon.awscdk.core.Construct
  5. import software.amazon.awscdk.core.Duration
  6. import software.amazon.awscdk.core.Stack
  7. import software.amazon.awscdk.services.lambda.
  8. import software.amazon.awscdk.services.s3.Bucket
  10. private val STAGE = System.getenv(“STAGE”) ?: “local”
  11. private val LAMBDA_MOUNT_CWD = System.getenv(“LAMBDA_MOUNT_CWD”) ?: “”
  12. private const val JAR_PATH = “build/libs/localstack-sampleproject-all.jar”
  14. class ApplicationStack(parent: Construct, name: String) : Stack(parent, name) {
  16.     init {
  17.         val lambdaCodeSource = this.buildCodeSource()
  19.         SingletonFunction.Builder.create(this, “ExampleFunctionOne”)
  20.             .code(lambdaCodeSource)
  21.             .handler(“org.localstack.sampleproject.api.LambdaApi”)
  22.             .environment(mapOf(“FUNCTION_NAME” to “functionOne”))
  23.             .timeout(Duration.seconds(30))
  24.             .runtime(Runtime.JAVA_11)
  25.             .uuid(UUID.randomUUID().toString())
  26.             .build()
  27.     }
  29.     /**
  30.       Mount code for hot-reloading when STAGE=local
  31.      */
  32.     private fun buildCodeSource(): Code  {
  33.         if (STAGE == “local”) {
  34.             val bucket = Bucket.fromBucketName(this, “HotReloadingBucket”, “local“)
  35.             return Code.fromBucket(bucket, LAMBDA_MOUNT_CWD)
  36.         }
  38.         return Code.fromAsset(JAR_PATH)
  39.     }
  40. }

Then to bootstrap and deploy the stack run the following shell script

  1. $ STAGE=local && LAMBDA_MOUNT_CWD=$(pwd)/build/hot &&
  2.   cdklocal bootstrap aws://000000000000/$(AWS_REGION) && \
  3.   cdklocal deploy

Terraform Configuration

  1. variable "STAGE" {
  2.     type    = string
  3.     default = "local"
  4. }
  6. variable "AWS_REGION" {
  7.     type    = string
  8.     default = "us-east-1"
  9. }
  11. variable "JAR_PATH" {
  12.     type    = string
  13.     default = "build/libs/localstack-sampleproject-all.jar"
  14. }
  16. variable "LAMBDA_MOUNT_CWD" {
  17.     type    = string
  18. }
  20. provider "aws" {
  21.     access_key                  = "test_access_key"
  22.     secret_key                  = "test_secret_key"
  23.     region                      = var.AWS_REGION
  24.     s3_force_path_style         = true
  25.     skip_credentials_validation = true
  26.     skip_metadata_api_check     = true
  27.     skip_requesting_account_id  = true
  29.     endpoints {
  30.         apigateway       = var.STAGE == "local" ? "http://localhost:4566" : null
  31.         cloudformation   = var.STAGE == "local" ? "http://localhost:4566" : null
  32.         cloudwatch       = var.STAGE == "local" ? "http://localhost:4566" : null
  33.         cloudwatchevents = var.STAGE == "local" ? "http://localhost:4566" : null
  34.         iam              = var.STAGE == "local" ? "http://localhost:4566" : null
  35.         lambda           = var.STAGE == "local" ? "http://localhost:4566" : null
  36.         s3               = var.STAGE == "local" ? "http://localhost:4566" : null
  37.     }
  38. }
  40. resource "aws_iam_role" "lambda-execution-role" {
  41.     name = "lambda-execution-role"
  43.     assume_role_policy = <<EOF
  44. {
  45.   "Version": "2012-10-17",
  46.   "Statement": [
  47.     {
  48.       "Action": "sts:AssumeRole",
  49.       "Principal": {
  50.         "Service": "lambda.amazonaws.com"
  51.       },
  52.       "Effect": "Allow",
  53.       "Sid": ""
  54.     }
  55.   ]
  56. }
  57. EOF
  58. }
  60. resource "aws_lambda_function" "exampleFunctionOne" {
  61.     s3_bucket     = var.STAGE == "local" ? "__local__" : null
  62.     s3_key        = var.STAGE == "local" ? var.LAMBDA_MOUNT_CWD : null
  63.     filename      = var.STAGE == "local" ? null : var.JAR_PATH
  64.     function_name = "ExampleFunctionOne"
  65.     role          = aws_iam_role.lambda-execution-role.arn
  66.     handler       = "org.localstack.sampleproject.api.LambdaApi"
  67.     runtime       = "java11"
  68.     timeout       = 30
  69.     source_code_hash = filebase64sha256(var.JAR_PATH)
  70.     environment {
  71.         variables = {
  72.             FUNCTION_NAME = "functionOne"
  73.         }
  74.     }
  75. }
  1. $ terraform init && \
  2.   terraform apply -var "STAGE=local" -var "LAMBDA_MOUNT_CWD=$(pwd)/build/hot"

Last modified July 26, 2022: fix some typos (#214) (6ab8502d)