Deploy Your C++ Lambda with Docker

gowebing 2024-12-04

In this article we will explore how you can use your C++ runtime with Lambda Functions. AWS Lambda allows us to use our app in a serverless architecture. As an addition to all the available runtimes in AWS Lambda, AWS announced Custom Runtimes at AWS Re:Invent 2018 where they released open-source custom runtimes for C++.

The advantage of using a custom runtime is that it allows you to use any sort of code in your Lambda function. Though there are few examples to use C++ Api Runtime but there is not enough reference on HOW to use a handler function and send/receive JSON data, which we will explore below.

Prerequisites

You need a Linux-based environment. It will be used for compiling and deploying your code -

        Shell 
      
xxxxxxxxxx
 
##C++11 compiler, either GCC 5.x or later 
Clang 3.3 or later $ yum install gcc64-c++ libcurl-devel 
$ export CC=gcc64 
$ export CXX=g++64

        Shell 
      
xxxxxxxxxx
 
##CMake v.3.5 or later. 
$ yum install cmake3

        Shell 
      
xxxxxxxxxx
 
##Git $ 
yum install git

Here we will install all these tools with Docker. Running the docker build command with Dockerfile will install the necessary AWS Linux machine image's environment, complying C++ code and deploy to AWS Lambda.

Note:

This Dockerfile is only for an existing Lambda update, hence please ensure to create your Lambda instance by either the AWS CLI or the AWS Console.
Please ensure to create the API Gateway and bind with C++ Lambda.

The reason for using Docker is that it will create an isolated place to work, preventing all possible errors and making it simple and re-use.

C++ Lambda Compiler With Dockerfile

Open a project directory which includes all project codes and the Dockerfile, following which create the Docker image in the same directory. An example on how it should look like:

Let's start to build our Docker image from the Dockerfile.

        Shell 
      
xxxxxxxxxx
 
FROM amazonlinux:latest 
## install required development packages 
RUN yum -y groupinstall "Development tools" 
RUN yum -y install gcc-c++ libcurl-devel cmake3 git 
RUN pip3 install awscli

The above will use Amazon Linux for the base image and install necessary components.

Following that, we will add the C++ API runtime environment. This will let you install and use Lambda libraries for C++ in your code; through the call-handler function, you would be able to use the C++ dependencies.

        Shell 
      
xxxxxxxxxx
 
# install C++ runtime environment 
RUN git clone https://github.com/awslabs/aws-lambda-cpp.git && \
    cd aws-lambda-cpp && mkdir build && cd /aws-lambda-cpp/build && \
    cmake3 .. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF \
    -DCMAKE_INSTALL_PREFIX=/out -DCMAKE_CXX_COMPILER=g++ && \
    make && make install

This will install the Lambda C++ environment — you do not need to change anything in this part.
CMAKE will handle and use this library creating an output point which our main code will use as a dependency while compiling.

        Shell 
      
xxxxxxxxxx
 
# include C++ source code and build configuration 
ADD adaptiveUpdate.cpp /adaptiveUpdate 
ADD CMakeLists.txt /adaptiveUpdate

Copy your main code and the CMAKE file to the Docker container.

        Shell 
      
             x 
            
# compile & package C++ code 
RUN cd /adaptiveUpdate && mkdir build && cd build && \
    cmake3 .. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF \
    -DCMAKE_PREFIX_PATH=/out -DCMAKE_CXX_COMPILER=g++  && \
    make && make aws-lambda-package-adaptiveUpdate

This will compile our code and make a deployable zip file. You can change your package name and will find it in your build folder which is located under the code directory. Next step is to deploy this zip file as a Lambda function to your AWS account. To make this happen we need to add ENV which defines our user access-id and secret-key.

        Shell 
      
xxxxxxxxxx
 
ENV AWS_DEFAULT_REGION='' 
ENV AWS_ACCESS_KEY_ID='' 
ENV AWS_SECRET_ACCESS_KEY='' 
RUN aws lambda update-function-code --function-name hello-world \
--zip-file fileb://adaptiveUpdate/build/adaptiveUpdate.zip

Add your secret key, access id and region to access and deploy your code to AWS. Let us start by creating a Lambda named hello-world. Additional details can be found in the link below -

awslabs/aws-lambda-cpp

C++ implementation of the AWS Lambda runtime. Contribute to awslabs/aws-lambda-cpp development by creating an account on GitHub.

Handler Method For Lambda

When you start using Lambda, you will notice that Lambda needs handler function, and below we will see how you can import the C++ handler function to your main code and how you retrieve your function as a return. The handler function is used to access the Lambda function and to send and retrieve JSON data.

Firstly you need to create a main function which will call the handler function.

        JSON 
      
xxxxxxxxxx
 
int main() 
 {
  run_handler(my_handler);
     return 0;
 }

That's it!

Secondly we will add our code handler function which includes response and request when you invoke Lambda.

        JSON 
      
xxxxxxxxxx
 
invocation_response my_handler(invocation_request const& req)
 {
  string json = req.payload;
   test(json);
    return invocation_response::success(json, "application/json");
 }

In the section below, we are receiving the payload of the JSON value which separated from header.

        JSON 
      
xxxxxxxxxx
 
  string json = req.payload;

JSON value will be similar to:

Create a string variable considering the req.payload JSON value as a string. Use it update the test function.

        Shell 
      
xxxxxxxxxx
 
  test(json);

        Shell 
      
xxxxxxxxxx
 
  string json = req.payload;

Return the main function with the updated value. Note that this will return it as JSON format.

        Shell 
      
xxxxxxxxxx
 
  return invocation_response::success(json, "application/json");

In the next stage we will invoke Lambda with the API Gateway.

API Gateway to Invoke Lambda

There are several ways to invoke your Lambda function, which can be through CLI, S3 or API Gateway. For the purpose of this article, we are going to use the API Gateway (REST API) method to invoke Lambda. You can configure this gateway through the Swagger Yaml, details of which can be found in the link below.

AWS Lambda Runtime Interface

AWS Lambda provides an HTTP API for custom runtimes to receive invocation events from Lambda and send response data back within the Lambda execution environment.

We are going to use our API Gateway as a proxy for this project. We will create a stage, resources and method, following which we will integrate it with our Lambda function.

Give a name to your REST API: ours is cppjsonupdate. Leave everything as default. Click on Create API.

Next is to create new resources for our API. Choose Create Resource under the Actions menu and set a Resource Name as per your choice, and give the path or can leave it as Default. Click on Create Resource.

Under the Actions menu, add a Method. We are choosing Any for the purpose of this article. Please note to click the green tick to save.

Deploy your API by clicking Deploy API under the Actions menu. Choose Popup Menu Stage. You will also need to add ARN of the Lambda function which you can find in Lambda service page. Following that choose New Stage and set a Stage Name. Click on Deploy.

        JSON 
      
xxxxxxxxxx
 
arn:aws:lambda:us-east-1:34728394278492:function:adaptiveupdate

Your API Gateway is now configured and integrated with C++ lambda. You can use endpoint for invocation. It should be similar to this.

As the final step, you can find the invoke URL under the Stages section as shown below.

Conclusion

Hopefully, with the help of this article, you can now understand and use your code in Lambda Runtime API to easily manage, create, and deploy your function on Docker.

Previously posted at https://appfleet.com/.