Serverless Go Plugin

Common errors

• Error: Cannot find module 'serverless-go-plugin'

  cause Attempting to `require` or `import` the plugin in a JavaScript/TypeScript file, instead of configuring it in `serverless.yaml`.
  fix Remove any JavaScript/TypeScript `require` or `import` statements for `serverless-go-plugin`. Ensure the plugin is listed correctly under the `plugins` section in your `serverless.yaml` file: `plugins: - serverless-go-plugin`.

• go build <module path> failed with exit status 1

  cause A generic Go compilation error indicating an issue with your Go source code, build environment, or `cmd` configuration.
  fix Review your Go source code for syntax errors, missing dependencies (check `go.mod`), or type mismatches. Verify your `custom.go.cmd` setting for any incorrect build flags or commands. Ensure Go is correctly installed and accessible in your environment.

• Lambda Validation Error: Your handler 'bootstrap' is not found in the deployment package.

  cause This error often occurs when deploying to `provided.al2` or similar custom runtimes without correctly configuring the plugin to build a `bootstrap` executable or without including it in the package.
  fix Ensure `runtime: provided.al2` is set for the function and that `custom.go.buildProvidedRuntimeAsBootstrap: true` is enabled in your plugin configuration. Also, append `GOARCH=arm64` (or target architecture) to your `custom.go.cmd`.

Warnings

• gotcha When deploying Go Lambda functions on ARM64 architecture using `provided.al2` runtime, the very first deployment may result in a small downtime (a few seconds) as the new runtime initializes. Consider using a deployment strategy like canary deployments for safer rollouts.
  Fix: Implement a deployment strategy such as Canary deployments in your Serverless configuration or use traffic shifting features in AWS Lambda.
• gotcha The `handler` property for Go functions must specify the path to the Go source file (e.g., `functions/myFunc/main.go`) or the package path (e.g., `functions/myFunc`). Unlike Node.js or Python, simply using the function name is incorrect and will lead to handler not found errors.
  Fix: Ensure your `handler` property in `serverless.yaml` points directly to the Go source file or its containing package directory, following the pattern: `handler: <path_to_function_directory>/main.go` or `handler: <path_to_function_directory>`.
• gotcha If you configure the `custom.go.baseDir` property in `serverless.yaml`, all `handler` paths for your Go functions must be specified relative to this `baseDir`, not relative to the `serverless.yaml` file itself. Misconfiguration can lead to compilation failures or handlers not being found.
  Fix: Adjust your `handler` paths to be relative to the `custom.go.baseDir` you've set, or omit `baseDir` if your Go modules are at the root of your project.

Install

• npm install serverless-go-plugin npm
• yarn add serverless-go-plugin yarn
• pnpm add serverless-go-plugin pnpm

Imports

• Plugin Activation
  wrong:

  import 'serverless-go-plugin'; // Incorrect for Serverless plugins
  // OR
  const plugin = require('serverless-go-plugin');

  correct:

  plugins:
    - serverless-go-plugin

  This plugin is activated by listing its name under the `plugins` section in your `serverless.yaml` file, not via standard JavaScript/TypeScript `import` or `require` statements.
• Go Function Handler Definition
  wrong:

  functions:
    myGoFunc:
      runtime: go1.x
      handler: myGoFunc // Assumes default JS/Node.js handler naming conventions

  correct:

  functions:
    myGoFunc:
      runtime: go1.x
      handler: functions/myGoFunc/main.go

  Specify the full path to the Go source file (`.go`) or the package directory containing `main.go` for the `handler` property. The plugin uses this path for compilation.
• Custom Plugin Configuration
  wrong:

  custom:
    go: { binDir: ".bin" } // Valid YAML but less readable; also, direct programmatic access via JS is not applicable

  correct:

  custom:
    go:
      binDir: .bin
      cgo: 1
      monorepo: true

  Plugin-specific settings like `binDir`, `cgo`, or `monorepo` are defined under the `custom.go` section in `serverless.yaml`.

Quickstart

This quickstart demonstrates how to set up a Serverless project with `serverless-go-plugin` to deploy Go functions. It includes a `package.json` for dependencies, a `serverless.yaml` configured for both standard `go1.x` and `provided.al2` (ARM64) runtimes, and two example Go Lambda functions (`hello` and `greet`). The `greet` function illustrates using path parameters and environment variables.

{
  "name": "my-go-serverless-app",
  "version": "1.0.0",
  "description": "A serverless Go application with serverless-go-plugin",
  "main": "handler.js",
  "scripts": {
    "deploy": "serverless deploy"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "serverless": "^3.0.0",
    "serverless-go-plugin": "^2.0.0",
    "@aws-cdk/aws-lambda": "^1.0.0"
  }
}

// serverless.yaml
service: my-go-app

frameworkVersion: '3'

provider:
  name: aws
  runtime: go1.x # Default runtime, can be overridden per function
  region: us-east-1
  architecture: x86_64 # Default architecture

plugins:
  - serverless-go-plugin

custom:
  go:
    binDir: .bin # Target folder for compiled binaries
    cmd: 'GOOS=linux go build -ldflags="-s -w"' # Default compile command
    supportedRuntimes: ["go1.x", "provided.al2"]

functions:
  hello:
    handler: functions/hello/main.go # Path to the Go source file
    events:
      - httpApi:
          path: /hello
          method: get
  greetArm:
    runtime: provided.al2 # Example for a bootstrapped runtime
    handler: functions/greet # Package path (assuming main.go inside)
    architecture: arm64
    environment:
      MESSAGE: "Hello from ARM64 Go Lambda!"
    events:
      - httpApi:
          path: /greet/{name}
          method: get


// functions/hello/main.go
package main

import (
	"context"
	"fmt"
	"github.com/aws/aws-lambda-go/events"
	"github.com/aws/aws-lambda-go/lambda"
)

type Response events.APIGatewayProxyResponse

func Handler(ctx context.Context, request events.APIGatewayProxyRequest) (Response, error) {
	body := fmt.Sprintf("Hello from Go Lambda on x86_64! Path: %s", request.Path)
	resp := Response{
		StatusCode:      200,
		IsBase64Encoded: false,
		Body:            body,
		Headers: map[string]string{
			"Content-Type": "application/json"
		},
	}
	return resp, nil
}

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

// functions/greet/main.go
package main

import (
	"context"
	"fmt"
	"net/http"
	"os"

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

func GreetHandler(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
	name := request.PathParameters["name"]
	if name == "" {
		name = "stranger"
	}
	messageEnv := os.Getenv("MESSAGE")
	message := fmt.Sprintf("%s Greetings, %s!", messageEnv, name)

	return events.APIGatewayProxyResponse{
		StatusCode: http.StatusOK,
		Headers:    map[string]string{"Content-Type": "text/plain"},
		Body:       message,
	},
	nil
}

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