forked from lobo/lambda-zig
125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
lambda-zig: A Custom Runtime for AWS Lambda
|
|
===========================================
|
|
|
|
This is a custom runtime built in Zig (0.15). Simple projects will
|
|
execute in <1ms, with a cold start init time of approximately 11ms.
|
|
|
|
Custom build steps are available for packaging and deploying Lambda functions:
|
|
|
|
* `zig build awslambda_package`: Package the Lambda function into a zip file
|
|
* `zig build awslambda_iam`: Create or verify IAM role for the Lambda function
|
|
* `zig build awslambda_deploy`: Deploy the Lambda function to AWS
|
|
* `zig build awslambda_run`: Invoke the deployed Lambda function
|
|
|
|
Build options:
|
|
|
|
* **function-name**: Name of the AWS Lambda function
|
|
* **payload**: JSON payload for function invocation (used with awslambda_run)
|
|
* **region**: AWS region for deployment and invocation
|
|
* **profile**: AWS profile to use for credentials
|
|
* **role-name**: IAM role name for the function (default: lambda_basic_execution)
|
|
* **env-file**: Path to environment variables file for the Lambda function
|
|
|
|
The Lambda function can be compiled for x86_64 or aarch64. The build system
|
|
automatically configures the Lambda architecture based on the target.
|
|
|
|
A sample project using this runtime can be found at
|
|
https://git.lerch.org/lobo/lambda-zig-sample
|
|
|
|
Environment Variables
|
|
---------------------
|
|
|
|
Lambda functions can be configured with environment variables during deployment.
|
|
This is useful for passing configuration, secrets, or credentials to your function.
|
|
|
|
### Using the build system
|
|
|
|
Pass the `-Denv-file` option to specify a file containing environment variables:
|
|
|
|
```sh
|
|
zig build awslambda_deploy -Dfunction-name=my-function -Denv-file=.env
|
|
```
|
|
|
|
### Using the CLI directly
|
|
|
|
The `lambda-build` CLI supports both `--env` flags and `--env-file`:
|
|
|
|
```sh
|
|
# Set individual variables
|
|
./lambda-build deploy --function-name my-fn --zip-file function.zip \
|
|
--env DB_HOST=localhost --env DB_PORT=5432
|
|
|
|
# Load from file
|
|
./lambda-build deploy --function-name my-fn --zip-file function.zip \
|
|
--env-file .env
|
|
|
|
# Combine both (--env values override --env-file)
|
|
./lambda-build deploy --function-name my-fn --zip-file function.zip \
|
|
--env-file .env --env DEBUG=true
|
|
```
|
|
|
|
### Environment file format
|
|
|
|
The environment file uses a simple `KEY=VALUE` format, one variable per line:
|
|
|
|
```sh
|
|
# Database configuration
|
|
DB_HOST=localhost
|
|
DB_PORT=5432
|
|
|
|
# API keys
|
|
API_KEY=secret123
|
|
```
|
|
|
|
Lines starting with `#` are treated as comments. Empty lines are ignored.
|
|
|
|
Using the Zig Package Manager
|
|
-----------------------------
|
|
|
|
To add Lambda package/deployment steps to another project:
|
|
|
|
1. Fetch the dependency:
|
|
|
|
```sh
|
|
zig fetch --save git+https://git.lerch.org/lobo/lambda-zig
|
|
```
|
|
|
|
2. Update your `build.zig`:
|
|
|
|
```zig
|
|
const std = @import("std");
|
|
const lambda_zig = @import("lambda_zig");
|
|
|
|
pub fn build(b: *std.Build) !void {
|
|
const target = b.standardTargetOptions(.{});
|
|
const optimize = b.standardOptimizeOption(.{});
|
|
|
|
// Get lambda-zig dependency
|
|
const lambda_zig_dep = b.dependency("lambda_zig", .{
|
|
.target = target,
|
|
.optimize = optimize,
|
|
});
|
|
|
|
const exe_module = b.createModule(.{
|
|
.root_source_file = b.path("src/main.zig"),
|
|
.target = target,
|
|
.optimize = optimize,
|
|
});
|
|
|
|
// Add lambda runtime to your module
|
|
exe_module.addImport("aws_lambda_runtime", lambda_zig_dep.module("lambda_runtime"));
|
|
|
|
const exe = b.addExecutable(.{
|
|
.name = "bootstrap",
|
|
.root_module = exe_module,
|
|
});
|
|
|
|
b.installArtifact(exe);
|
|
|
|
// Add Lambda build steps
|
|
try lambda_zig.configureBuild(b, lambda_zig_dep, exe);
|
|
}
|
|
```
|
|
|
|
Note: The build function return type must be `!void` or catch/deal with errors
|
|
to support the Lambda build integration.
|