View a markdown version of this page

Deploy Go Lambda functions with .zip file archives - AWS Lambda
Creating a .zip file on macOS and LinuxCreating a .zip file on WindowsCreating and updating Go Lambda functions using .zip files

Deploy Go Lambda functions with .zip file archives

Your AWS Lambda function's code consists of scripts or compiled programs and their dependencies. You use a deployment package to deploy your function code to Lambda. Lambda supports two types of deployment packages: container images and .zip file archives.

This page describes how to create a .zip file as your deployment package for the Go runtime, and then use the .zip file to deploy your function code to AWS Lambda using the AWS Management Console, AWS Command Line Interface (AWS CLI), and AWS Serverless Application Model (AWS SAM).

Note that Lambda uses POSIX file permissions, so you might need to set permissions for the deployment package folder before you create the .zip file archive.

Creating a .zip file on macOS and Linux

The following steps show how to compile your executable using the go build command and create a .zip file deployment package for Lambda. Before compiling your code, make sure you have installed the lambda package from GitHub. This module provides an implementation of the runtime interface, which manages the interaction between Lambda and your function code. To download this library, run the following command.

go get github.com/aws/aws-lambda-go/lambda

If your function uses the AWS SDK for Go, download the standard set of SDK modules, along with any AWS service API clients required by your application. To learn how to install the SDK for Go, see Getting Started with the AWS SDK for Go V2.

Using the provided runtime family

Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an OS-only runtime (the provided runtime family) to deploy Go functions to Lambda.

To create a .zip deployment package (macOS/Linux)

  1. In the project directory that contains your application's main.go file, compile your executable. Note the following:

    • The executable must be named bootstrap. For more information, see Handler naming conventions.

    • Set your target instruction set architecture. OS-only runtimes support both arm64 and x86_64.

    • You can use the optional lambda.norpc tag to exclude the Remote Procedure Call (RPC) component of the lambda library. The RPC component is only required if you are using the deprecated Go 1.x runtime. Excluding the RPC reduces the size of the deployment package.

    For the arm64 architecture:

    GOOS=linux GOARCH=arm64 go build -tags lambda.norpc -o bootstrap main.go

    For the x86_64 architecture:

    GOOS=linux GOARCH=amd64 go build -tags lambda.norpc -o bootstrap main.go

  2. (Optional) You may need to compile packages with CGO_ENABLED=0 set on Linux:

    GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o bootstrap -tags lambda.norpc main.go

    This command creates a stable binary package for standard C library (libc) versions, which may be different on Lambda and other devices.

  3. Create a deployment package by packaging the executable in a .zip file.

    zip myFunction.zip bootstrap
    Note

    The bootstrap file must be at the root of the .zip file.

  4. Create the function. Note the following:

    • The binary must be named bootstrap, but the handler name can be anything. For more information, see Handler naming conventions.

    • The --architectures option is only required if you're using arm64. The default value is x86_64.

    • For --role, specify the Amazon Resource Name (ARN) of the execution role.

    aws lambda create-function --function-name myFunction \
--runtime provided.al2023 --handler bootstrap \
--architectures arm64 \
--role arn:aws:iam::111122223333:role/lambda-ex \
--zip-file fileb://myFunction.zip

Creating a .zip file on Windows

The following steps show how to download the build-lambda-zip tool for Windows from GitHub, compile your executable, and create a .zip deployment package.

Note

If you have not already done so, you must install git and then add the git executable to your Windows %PATH% environment variable.

Before compiling your code, make sure you have installed the lambda library from GitHub. To download this library, run the following command.

go get github.com/aws/aws-lambda-go/lambda

If your function uses the AWS SDK for Go, download the standard set of SDK modules, along with any AWS service API clients required by your application. To learn how to install the SDK for Go, see Getting Started with the AWS SDK for Go V2.

Using the provided runtime family

Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an OS-only runtime (the provided runtime family) to deploy Go functions to Lambda.

To create a .zip deployment package (Windows)

  1. Download the build-lambda-zip tool from GitHub.

    go install github.com/aws/aws-lambda-go/cmd/build-lambda-zip@latest

  2. Use the tool from your GOPATH to create a .zip file. If you have a default installation of Go, the tool is typically in %USERPROFILE%\Go\bin. Otherwise, navigate to where you installed the Go runtime and do one of the following:

    cmd.exe

    In cmd.exe, run one of the following, depending on your target instruction set architecture. OS-only runtimes support both arm64 and x86_64.

    You can use the optional lambda.norpc tag to exclude the Remote Procedure Call (RPC) component of the lambda library. The RPC component is only required if you are using the deprecated Go 1.x runtime. Excluding the RPC reduces the size of the deployment package.

    Example— For the x86_64 architecture
    set GOOS=linux
set GOARCH=amd64
set CGO_ENABLED=0
go build -tags lambda.norpc -o bootstrap main.go
%USERPROFILE%\Go\bin\build-lambda-zip.exe -o myFunction.zip bootstrap
    Example— For the arm64 architecture
    set GOOS=linux
set GOARCH=arm64
set CGO_ENABLED=0
go build -tags lambda.norpc -o bootstrap main.go
%USERPROFILE%\Go\bin\build-lambda-zip.exe -o myFunction.zip bootstrap
    PowerShell

    In PowerShell, run one of the following, depending on your target instruction set architecture. OS-only runtimes support both arm64 and x86_64.

    You can use the optional lambda.norpc tag to exclude the Remote Procedure Call (RPC) component of the lambda library. The RPC component is only required if you are using the deprecated Go 1.x runtime. Excluding the RPC reduces the size of the deployment package.

    For the x86_64 architecture:

    $env:GOOS = "linux"
$env:GOARCH = "amd64"
$env:CGO_ENABLED = "0"
go build -tags lambda.norpc -o bootstrap main.go
~\Go\Bin\build-lambda-zip.exe -o myFunction.zip bootstrap

    For the arm64 architecture:

    $env:GOOS = "linux"
$env:GOARCH = "arm64"
$env:CGO_ENABLED = "0"
go build -tags lambda.norpc -o bootstrap main.go
~\Go\Bin\build-lambda-zip.exe -o myFunction.zip bootstrap

  3. Create the function. Note the following:

    • The binary must be named bootstrap, but the handler name can be anything. For more information, see Handler naming conventions.

    • The --architectures option is only required if you're using arm64. The default value is x86_64.

    • For --role, specify the Amazon Resource Name (ARN) of the execution role.

    aws lambda create-function --function-name myFunction \
--runtime provided.al2023 --handler bootstrap \
--architectures arm64 \
--role arn:aws:iam::111122223333:role/lambda-ex \
--zip-file fileb://myFunction.zip

Creating and updating Go Lambda functions using .zip files

After you have created your .zip deployment package, you can use it to create a new Lambda function or update an existing one. You can deploy your .zip package using the Lambda console, the AWS Command Line Interface, and the Lambda API. You can also create and update Lambda functions using AWS Serverless Application Model (AWS SAM) and CloudFormation.

The maximum size for a .zip deployment package for Lambda is 250 MB (unzipped). Note that this limit applies to the combined size of all the files you upload, including any Lambda layers.

The Lambda runtime needs permission to read the files in your deployment package. In Linux permissions octal notation, Lambda needs 644 permissions for non-executable files (rw-r--r--) and 755 permissions (rwxr-xr-x) for directories and executable files.

In Linux and MacOS, use the chmod command to change file permissions on files and directories in your deployment package. For example, to give a non-executable file the correct permissions, run the following command.

chmod 644 <filepath>

To change file permissions in Windows, see Set, View, Change, or Remove Permissions on an Object in the Microsoft Windows documentation.

Note

If you don't grant Lambda the permissions it needs to access directories in your deployment package, Lambda sets the permissions for those directories to 755 (rwxr-xr-x).

Creating and updating functions with .zip files using the console

To create a new function, you must first create the function in the console, then upload your .zip archive. To update an existing function, open the page for your function, then follow the same procedure to add your updated .zip file.

If your .zip file is less than 50MB, you can create or update a function by uploading the file directly from your local machine. For .zip files greater than 50MB, you must upload your package to an Amazon S3 bucket first. For instructions on how to upload a file to an Amazon S3 bucket using the AWS Management Console, see Getting started with Amazon S3. To upload files using the AWS CLI, see Move objects in the AWS CLI User Guide.

Note

You cannot convert an existing container image function to use a .zip archive. You must create a new function.

To create a new function (console)

  1. Open the Functions page of the Lambda console and choose Create Function.

  2. Choose Author from scratch.

  3. Under Basic information, do the following:

    1. For Function name, enter the name for your function.

    2. For Runtime, choose provided.al2023.

  4. (Optional) Under Permissions, expand Change default execution role. You can create a new Execution role or use an existing one.

  5. Choose Create function. Lambda creates a basic 'Hello world' function using your chosen runtime.