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:

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

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

Step 3: Serve the function locally for testing ​

Run the Lambda emulator built in with the watch subcommand:

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:

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:

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:

cargo lambda build --release

cargo lambda build --release

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.

cargo lambda deploy

cargo lambda deploy

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:

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.