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 may 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 AWS 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.

To upload a .zip archive from your local machine (console)

  1. In the Functions page of the Lambda console, choose the function you want to upload the .zip file for.

  2. Select the Code tab.

  3. In the Code source pane, choose Upload from.

  4. Choose .zip file.

  5. To upload the .zip file, do the following:

    1. Select Upload, then select your .zip file in the file chooser.

    2. Choose Open.

    3. Choose Save.

To upload a .zip archive from an Amazon S3 bucket (console)

  1. In the Functions page of the Lambda console, choose the function you want to upload a new .zip file for.

  2. Select the Code tab.

  3. In the Code source pane, choose Upload from.

  4. Choose Amazon S3 location.

  5. Paste the Amazon S3 link URL of your .zip file and choose Save.

Creating and updating functions with .zip files using the AWS CLI

You can can use the AWS CLI to create a new function or to update an existing one using a .zip file. Use the create-function and update-function-code commands to deploy your .zip package. If your .zip file is smaller than 50MB, you can upload the .zip package from a file location on your local build machine. For larger files, you must upload your .zip package from an Amazon S3 bucket. For instructions on how to upload a file to an Amazon S3 bucket using the AWS CLI, see Move objects in the AWS CLI User Guide.

Note

If you upload your .zip file from an Amazon S3 bucket using the AWS CLI, the bucket must be located in the same AWS Region as your function.

To create a new function using a .zip file with the AWS CLI, you must specify the following:

  • The name of your function (--function-name)

  • Your function’s runtime (--runtime)

  • The Amazon Resource Name (ARN) of your function’s execution role (--role)

  • The name of the handler method in your function code (--handler)

You must also specify the location of your .zip file. If your .zip file is located in a folder on your local build machine, use the --zip-file option to specify the file path, as shown in the following example command. 

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

To specify the location of .zip file in an Amazon S3 bucket, use the --code option as shown in the following example command. You only need to use the S3ObjectVersion parameter for versioned objects. 

aws lambda create-function --function-name myFunction \
--runtime provided.al2023 --handler bootstrap \
--role arn:aws:iam::111122223333:role/service-role/my-lambda-role \
--code S3Bucket=amzn-s3-demo-bucket,S3Key=myFileName.zip,S3ObjectVersion=myObjectVersion

To update an existing function using the CLI, you specify the the name of your function using the --function-name parameter. You must also specify the location of the .zip file you want to use to update your function code. If your .zip file is located in a folder on your local build machine, use the --zip-file option to specify the file path, as shown in the following example command. 

aws lambda update-function-code --function-name myFunction \
--zip-file fileb://myFunction.zip

To specify the location of .zip file in an Amazon S3 bucket, use the --s3-bucket and --s3-key options as shown in the following example command. You only need to use the --s3-object-version parameter for versioned objects. 

aws lambda update-function-code --function-name myFunction \
--s3-bucket amzn-s3-demo-bucket --s3-key myFileName.zip --s3-object-version myObject Version

Creating and updating functions with .zip files using the Lambda API

To create and update functions using a .zip file archive, use the following API operations:

Creating and updating functions with .zip files using AWS SAM

The AWS Serverless Application Model (AWS SAM) is a toolkit that helps streamline the process of building and running serverless applications on AWS. You define the resources for your application in a YAML or JSON template and use the AWS SAM command line interface (AWS SAM CLI) to build, package, and deploy your applications. When you build a Lambda function from an AWS SAM template, AWS SAM automatically creates a .zip deployment package or container image with your function code and any dependencies you specify. To learn more about using AWS SAM to build and deploy Lambda functions, see Getting started with AWS SAM in the AWS Serverless Application Model Developer Guide.

You can also use AWS SAM to create a Lambda function using an existing .zip file archive. To create a Lambda function using AWS SAM, you can save your .zip file in an Amazon S3 bucket or in a local folder on your build machine. For instructions on how to upload a file to an Amazon S3 bucket using the AWS CLI, see Move objects in the AWS CLI User Guide.

In your AWS SAM template, the AWS::Serverless::Function resource specifies your Lambda function. In this resource, set the following properties to create a function using a .zip file archive:

  • PackageType - set to Zip

  • CodeUri - set to the function code's Amazon S3 URI, path to local folder, or FunctionCode object

  • Runtime - Set to your chosen runtime

With AWS SAM, if your .zip file is larger than 50MB, you don’t need to upload it to an Amazon S3 bucket first. AWS SAM can upload .zip packages up to the maximum allowed size of 250MB (unzipped) from a location on your local build machine.

To learn more about deploying functions using .zip file in AWS SAM, see AWS::Serverless::Function in the AWS SAM Developer Guide.

Example: Using AWS SAM to build a Go function with provided.al2023

  1. Create an AWS SAM template with the following properties:

    • BuildMethod: Specifies the compiler for your application. Use go1.x.

    • Runtime: Use provided.al2023.

    • CodeUri: Enter the path to your code.

    • Architectures: Use [arm64] for the arm64 architecture. For the x86_64 instruction set architecture, use [amd64] or remove the Architectures property.

    Example template.yaml
    AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: go1.x
    Properties:
      CodeUri: hello-world/ # folder where your main program resides
      Handler: bootstrap
      Runtime: provided.al2023
      Architectures: [arm64]

  2. Use the sam build command to compile the executable.

    sam build

  3. Use the sam deploy command to deploy the function to Lambda.

    sam deploy --guided

Creating and updating functions with .zip files using AWS CloudFormation

You can use AWS CloudFormation to create a Lambda function using a .zip file archive. To create a Lambda function from a .zip file, you must first upload your file to an Amazon S3 bucket. For instructions on how to upload a file to an Amazon S3 bucket using the AWS CLI, see Move objects in the AWS CLI User Guide.

In your AWS CloudFormation template, the AWS::Lambda::Function resource specifies your Lambda function. In this resource, set the following properties to create a function using a .zip file archive:

  • PackageType - Set to Zip

  • Code - Enter the Amazon S3 bucket name and the .zip file name in the S3Bucket and S3Key fields

  • Runtime - Set to your chosen runtime

The .zip file that AWS CloudFormation generates cannot exceed 4MB. To learn more about deploying functions using .zip file in AWS CloudFormation, see AWS::Lambda::Function in the AWS CloudFormation User Guide.