Hello, world

Your first function

First, you'll create and compile a simple AWS Lambda function on your local machine. Then you'll upload that compiled function using the AWS Management Console. Finally, you'll test your function in the Management Console using a simple test event.

Create a simple function

main.go

In an empty folder, create a file main.go and paste the following contents:

package main

import (
	"context"
	"fmt"

	"github.com/aws/aws-lambda-go/lambda"
)

type Input struct {
	Name string `json:"name"`
}

func handler(ctx context.Context, name Input) (string, error) {
	return fmt.Sprintf("Hello, %s!", name.Name), nil
}

func main() {
	lambda.Start(handler)
}

The highlighted lines show you how Lambda functions are both similar to and different from standalone programs written in Go:

package main
  • As with any executable Go program, you must declare a main package.
import (
    "github.com/aws/aws-lambda-go/lambda"
)
  • You must import github.com/aws/aws-lambda-go/lambda to execute lambda.Start(), which tells the Lambda runtime which function will handle the event that triggers invocation of your function.
type Input struct {
    Name string `json:"name"`
}

func handler(ctx context.Context, name Input) (string, error) {
  • Your Lambda function will be invoked with two arguments, a context and an event. The standard convention is to name your context object ctx. In this case, you see a generic user-defined Input event that is passed into the function. You will learn more about these events, their types, and how they are serialized and deserialized later in the workshop.
lambda.Start(handler)
  • After completing any one-time setup, your main function calls lambda.Start() with a single parameter, a function that will be invoked each time an event is received.

The following code block lists valid handler signatures. TIn and TOut represent types compatible with the encoding/json standard library. For more information, see AWS Lambda Function Handler in Go in the AWS Lambda Documentation.

func ()
func () error
func (TIn), error
func () (TOut, error)
func (context.Context) error
func (context.Context, TIn) error
func (context.Context) (TOut, error)
func (context.Context, TIn) (TOut, error)

Makefile

In the same folder where you created main.go, create a file Makefile and paste the following contents:

.PHONY: clean build package

clean: 
	rm -rf ./hello package.zip
	
build:
	go get github.com/aws/aws-lambda-go/lambda
	GOOS=linux GOARCH=amd64 go build -o hello .

package:
	zip -r package.zip hello

This simplified Makefile gives you three basic commands you will use to compile and package your Lambda function:

  1. make clean: remove the compiled executable and zipped package
  2. make build: compile the program to run in the Lambda go1.x runtime.
  3. make package: zip the compiled function for upload to the Management Console

The GOOS=linux and GOARCH=amd64 environment variables in the make build step allow you to build a binary that will run in the Lambda environment regardless of whether you develop locally in macOS, Linux, or Windows.

Run the following commands in a terminal in the directory where you created main.go and Makefile:

make clean
make build
make package

If you receive the error go: cannot find main module; see ‘go help modules’ you probably still have GO111MODULE=on set in your environment. If you're using a sh-like shell, unset GO111MODULE or export GO111MODULE=auto should put things back into auto mode. See this GitHub issue for additional information.

Below you can see the results of running the make build and make package commands on macOS, showing that the built binary is a Linux ELF 64-bit executable, not a Mach-O executable.

Terminal showing results of 'make build' and 'make package' commands.

Building and packaging a simple AWS Lambda function in Go

Upload your function

Now that you've built and packaged your function, you must upload it to the AWS Management Console.

  • In the Lambda console, choose “Create function”.
AWS Management Console showing the 'Create function' button location on the AWS Lambda page

AWS Lambda console

  • In the “Create function” screen that appears:
    1. choose “Author from scratch”
    2. give your function a name, such as “HelloWorld”
    3. choose the “Go 1.x” runtime
    4. choose “Create function”
AWS Management Console showing the 'Create function' button location on the AWS Lambda page

Creating an AWS Lambda function

  • On the function configuration page:
    1. change the “Handler” to match the filename of the executable you built, in this case, hello
    2. choose Upload and select the package.zip file you created previously
    3. choose Save
AWS Lambda Console showing the 'Upload package' button location

Uploading package.zip

Invoke your function

Before running your Lambda function for the first time, it's helpful to understand the Lambda invocation cycle. A Lambda is executed in three steps:

  1. An event source emits an event that triggers the Lambda function to begin execution. The event source can be either:

  2. A Lambda function receives the event and performs some sort of processing that implements your business logic.

  3. The Lambda function sends its result to a destination. The destination can be:

    • the caller, in the case of a synchronous invocation
    • a named destination, such as Amazon EventBridge or an Amazon SQS queue, in the case of an asynchronous invocation

The invocation cycle looks as follows:

graph TD; A[Event Source] --> |Event| B(Lambda Function) B --> |Result| C[Destination]

For your first Lambda function, you will create a basic test event in the Management Console and use that event to synchronously invoke your function.

Create a test event

In the function Configuration page, activate the “Select a test event” menu and choose “Configure test events”.

AWS Lambda Console showing the 'Configure test events' dropdown location

Configuring a test event

In the “Configure test event” screen that appears, give your test event a name, paste the following JSON into the text box, and choose “Create”.

{
    "name": "GoDays Berlin"
}
A sample test event for an AWS Lambda function

Test event data

Invoke your function

Now you can invoke your function for the first time! Ensure that the event you created is selected and choose “Test”.

Testing an AWS Lambda function in the AWS Lambda console

Testing the function

Expand the “Execution result” area that appears. You should see the following:

  1. A successful execution result with a link to the execution logs.
  2. The return value of your function, in our case “Hello, GoDays Berlin!”
  3. The “Log output” of this invocation of your Lambda function.
AWS Lambda function execution results

Displaying function execution results

Summary

In this section you learned how to:

  • create a simple Lambda function in Go
  • compile, package, and upload your Lambda function to the AWS Management Console
  • create a test event for your Lambda function
  • execute your Lambda function