Skip to content

Getting Started

This section will help you build a Rust function for AWS Lambda from scratch. If you already have an existent function, and would like to build it for AWS Lambda, start from Step 4.

Step 1: Install Cargo Lambda

See all the ways that you can install Cargo Lambda in your system.

Step 2: Create a new project

The new subcommand will help you create a new project with a default template. When that's done, change into the new directory:

sh
cargo lambda new new-lambda-project \
    && cd new-lambda-project
cargo lambda new new-lambda-project \
    && cd new-lambda-project

TIP

Add the flag --http if you want to automatically generate an HTTP function that integrates with Amazon API Gateway, Amazon Elastic Load Balancer, and AWS Lambda Function URLs.

Step 3: Serve the function locally for testing

Run the Lambda emulator built in with the watch subcommand:

sh
cargo lambda watch
cargo lambda watch

Step 4: Test your function

The invoke subcommand can send JSON payloads to the function running locally. Payloads are deserialized into strongly typed Rust structs, and the invoke call will fail if the payload doesn't have the right shape.

If you're starting with a basic function that only receives events with a command field in the payload, you can invoke them with the following command:

sh
cargo lambda invoke --data-ascii "{ \"command\": \"hi\" }"
cargo lambda invoke --data-ascii "{ \"command\": \"hi\" }"

If you're starting an HTTP function, you can access it with your browser from the local endpoint: http://localhost:9000/. You can also invoke HTTP functions with the invoke subcommand, the payload to send will depend if this function receives calls from Amazon API Gateway, Amazon Elastic Load Balancer, or Lambda Function URLs.

If your function integrates with Amazon API Gateway, you can use one of the payload examples that we provide by using the --data-example flag:

sh
cargo lambda invoke http-lambda --data-example apigw-request
cargo lambda invoke http-lambda --data-example apigw-request

Read more about the example flag in the Invoke documentation.

Step 5: Build the function to deploy it on AWS Lambda

Use the build subcommand to compile your function for Linux systems:

sh
cargo lambda build --release
cargo lambda build --release

TIP

Add the flag --arm64 if you want to use Graviton processors on AWS Lambda

Check out the build subcommand docs to learn how to compile multiple functions in the same project.

Step 6: Deploy the function on AWS Lambda

Use the deploy subcommand to upload your function to AWS Lambda. This subcommand requires AWS credentials in your system.

sh
cargo lambda deploy
cargo lambda deploy

INFO

A default execution role for this function will be created when you execute this command. Use the flag --iam-role if you want to use a predefined IAM role.

Debugging

Use the flag --verbose with any subcommand to enable tracing instrumentation. You can also enable instrumentation with the following environment variable RUST_LOG=cargo_lambda=trace.

GitHub Actions

If you want to use Cargo Lambda in a GitHub Action workflow, you can use one of the predefined actions that download release binaries from GitHub Releases.

The following example shows the steps to install Rust, Zig, and Cargo Lambda on a Linux x86-64 workflow:

yaml
jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - name: Install Rust toolchain
              uses: dtolnay/rust-toolchain@stable
            - name: Install Zig toolchain
              uses: korandoru/setup-zig@v1
              with:
                # Note: make sure you are using a recent version of zig (the one below isn't kept in sync with new releases)
                zig-version: 0.13.0
            - name: Install Cargo Lambda
              uses: jaxxstorm/action-install-gh-release@v1.9.0
              with:
                repo: cargo-lambda/cargo-lambda
                # Note: make sure you are using a recent version of cargo-lambda (the one below isn't kept in sync with new releases)
                tag: v1.3.0 # Remove this if you want to grab always the latest version
                platform: linux # Other valid options: 'windows' or 'darwin'
                arch: x86_64 # Other valid options for linux: 'aarch64'
            # Add your build steps below
jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - name: Install Rust toolchain
              uses: dtolnay/rust-toolchain@stable
            - name: Install Zig toolchain
              uses: korandoru/setup-zig@v1
              with:
                # Note: make sure you are using a recent version of zig (the one below isn't kept in sync with new releases)
                zig-version: 0.13.0
            - name: Install Cargo Lambda
              uses: jaxxstorm/action-install-gh-release@v1.9.0
              with:
                repo: cargo-lambda/cargo-lambda
                # Note: make sure you are using a recent version of cargo-lambda (the one below isn't kept in sync with new releases)
                tag: v1.3.0 # Remove this if you want to grab always the latest version
                platform: linux # Other valid options: 'windows' or 'darwin'
                arch: x86_64 # Other valid options for linux: 'aarch64'
            # Add your build steps below

AWS CDK Support

You can build and deploy Rust functions with Cargo Lambda and the AWS CDK with the constructs in the Cargo Lambda CDK repository.

Released under the MIT License.