A Practical Guide to Getting Started With AWS Lambda Functions Using Go


AWS Lambda functions that support Go were announced on Jan 15th, 2018. At the time of writing this blog there is very little information online around writing native Go-based AWS Lambda functions. This blog is for all of those who are looking for a simple guide to get started. I wrote this blog with macOS in mind, but the instructions can easily be adjusted for Windows or Linux-based operating systems.

Why Go?

Go is a compiled language, which means that once you compile it for a certain environment it contains all of the necessary libraries it needs to function. There is no need to upload and install any external libraries with your binary file. Lambda functions are designed to be self-contained, small, and fast, which goes well with the ability to upload a single self-contained file for the Lambda to execute.

Getting Started

You will need the following items installed to be able to run the example:

Make sure you add the following somewhere to your ~/.bash_profile (assuming you use bash) file:

export GOPATH=$HOME/go
export PATH=$GOPATH/bin:$PATH

If you want to keep the same terminal window open, run the following command as well:

source ~/.bash_profile
  • Install Docker — Docker is used to run the AWS Lambda locally
  • Install aws-sam-local — We will use this library to run Lambda functions locally on our machine during the development process.

Why Use aws-sam-local?

AWS Lambda functions are awesome, at the same time developing Lambda functions can be frustrating, especially when dealing with a compiled language such as Go (there is currently no web interface to write the code inline). Every code change requires you to compile, zip and upload the code to test it. That’s where aws-sam-local comes in. You can simply make a code change and type make run in the terminal to see the results.

Create the Application

The application we will create is a simple “hello world” in Go. The one extra piece is that calling this application will require the user to also send a token for simple verification.

Type the following into a terminal window:

go get -u github.com/aws/aws-lambda-go/events
go get -u github.com/aws/aws-lambda-go/lambda
go get -u github.com/tidwall/gjson

Note: The full code for the application is available at this Git repository

If you choose to manually go through the steps below, take into consideration that YAML files and Makefiles are sensitive to special characters and tabs, so cutting and pasting those from my instructions may not work out of the box.

We will create four files to run our hello world program:

  • hello_lambda.go — main go application code
  • template.yaml — Environment for local Lambda execution
  • event.js — Test data for the local Lambda execution
  • Makefile — A simple way to compile, run and zip the application

Use your favourite IDE to create the following files:


This file is the main application that contains the Lambda function. It accepts a JSON payload (provided by the event.js file).

package main
import (
func main() {
func Handler(ctx context.Context, evt json.RawMessage)   (events.APIGatewayProxyResponse, error) {
    param := gjson.Get(string(evt), "param1").String()
token := gjson.Get(string(evt), "token")
    returnVal := events.APIGatewayProxyResponse{
Body: "",
StatusCode: 200,
    if token.String() != os.Getenv("SECRET") {
returnVal.Body = "Error - wrong token"
returnVal.StatusCode = 401
} else {
fmt.Println("Hello Lambda")
// Do whatever you need to do here
returnVal.Body = "Completed request successfully " + param
    return returnVal, nil


This file is used by aws-sam-local to mimic running on the AWS Lambda environment.

The following parameters can be changed to your needs (the rest you should leave alone):

  • Description -> Simple text describing your Lambda function.
  • Timeout -> The time in seconds the Lambda will run before timing out
  • SECRET -> This is a simple way to incorporate some level of security when calling your function (the secret needs to be provided as part of the payload to allow the Lambda to run) — make sure to change the SECRET from my sample to something else — It supposed to be a secret, not a value that is available in someone’s blog :-). I used a simple UUID to generate the SECRET. The longer you make it the harder it is to guess.

Note: the “token” in the event.js file will need to match the SECRET environment variable from the YAML file (see below)

AWSTemplateFormatVersion : '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: A simple Hello World Serverless project
Type: AWS::Serverless::Function
Runtime: go1.x
Handler: myapp
CodeUri: .
Timeout: 5


This file contains a sample JSON payload the Lambda function will use to process the information — used to test the application locally.

"param1": "My param value",
"token": "35c760f4-b3dc-4657-b4f3–2c6566d4f42e"


This file is for convenience only, it allows you to compile the code, run it locally and zip the file so it can be uploaded to your AWS Lambda.

Notice that the compilation is done for a Linux operating system. If you try to run the Go app locally on a non Linux machine (for example a Mac), it will fail (the GOOS setting is set to Linux). The reason it works when we call make run is because aws-sam-local actually executes the app on a Linux docker container. Creating the file in Linux format makes it ready for deployment on the AWS Lambda.

GOOS=linux go build -o myapp
run:    compile
aws-sam-local local invoke "myapp" -e event.json
ship:   compile
zip hello_lambda.zip myapp

Trying Your New Application

Type the following:

cd $GOPATH/src/hello_go_lambda
make run

The above lines will change to the application’s directory, compile and run it. Note that on the very first run, Docker will download the image aws-sam-local uses to be able to run the application. This may take a couple of minutes (depending on your Internet speed). Subsequent calls do not require this step and therefore will be much faster.

What’s Next?

The Lambda function we created is specifically geared towards being invoked by AWS’s API Gateway. Creating the Lambda function and the corresponding API gateway to trigger the Lambda function is beyond the scope of this blog. There are many tutorials on how to do that, including:

AWS official documentation for creating a Lambda function
AWS official documentation for getting started with API Gateway

Once you have the API gateway setup, you can call your Lambda function from a terminal window using the following type of syntax:

curl -d '{"param1":"my param value","token":"35c760f4-b3dc-4657-b4f3-2c6566d4f42e"}' -H "Content-Type: application/json" -X POST  https://{url of api gateway}/{endpoint}

Closing Remarks

The beauty of using Go with AWS Lambda functions is that once you compile the application it’s self-contained and it’s pretty much guaranteed to run on the Lambda function without any complications. I am still new to Go, but it very quickly became my language of choice to developing AWS Lambda functions. My hope is that this blog will help others getting started with serverless computing.