Deployment to AWS Lambda using SAM

Ginboot applications are designed for easy deployment to AWS Lambda using the AWS Serverless Application Model (SAM) CLI. This document guides you through the process of building and deploying your Ginboot application as a serverless function.

Prerequisites

Before you begin, ensure you have the following installed and configured:

Go 1.21 or later: The Go runtime is required to build your application.
AWS SAM CLI: Install the AWS SAM CLI to build, test, and deploy your serverless applications. Follow the official AWS documentation for installation instructions.
AWS CLI: Ensure you have the AWS Command Line Interface (CLI) installed and configured with appropriate credentials and a default region. Your AWS credentials will be used by SAM CLI to deploy resources to your AWS account.

Project Structure for SAM Deployment

When you create a new Ginboot project using ginboot new myproject, it generates a project structure that is compatible with AWS SAM. The main.go file in the cmd directory typically contains the entry point for your Lambda function.

myproject/
├── cmd/
│   └── main.go
├── internal/
│   └── ... (your application logic)
├── template.yaml  # AWS SAM template
└── ... (other project files)

Building Your Application for Lambda

Ginboot provides a CLI tool to simplify the build process for AWS Lambda. This command compiles your Go application and prepares it for deployment.

ginboot build

This command will:

Compile your Go application for the linux/amd64 architecture, which is compatible with AWS Lambda.
Place the compiled binary (e.g., bootstrap) in a build/ directory.
Generate a template.yaml file (if not already present or updated) that defines your serverless application's resources, including the Lambda function, API Gateway, and any other AWS services.

Deploying to AWS

Once your application is built, you can deploy it to your AWS account using the Ginboot CLI tool, which internally leverages the AWS SAM CLI.

ginboot deploy

First-Time Deployment

On your first deployment, the SAM CLI will prompt you for several configuration details:

Stack Name: A unique name for your CloudFormation stack (e.g., myproject-stack). This defaults to your project name.
AWS Region: The AWS region where you want to deploy your application (e.g., us-east-1).
S3 Bucket: An S3 bucket name to store your deployment artifacts. If you don't have one, SAM CLI can create one for you.

These settings will be saved in a ginboot-app.yml file in your project root. This file is used for subsequent deployments, so you won't be prompted for these details again unless you delete the file or change the configuration.

Subsequent Deployments

For subsequent deployments, simply run ginboot deploy again. SAM CLI will detect changes in your code or template.yaml and perform an incremental update to your CloudFormation stack.

Understanding `template.yaml`

The template.yaml file is the heart of your SAM application. It defines your serverless resources. A typical Ginboot template.yaml might look like this:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: A Ginboot application deployed to AWS Lambda.

Globals:
  Function:
    Timeout: 30 # Default timeout for all functions
    MemorySize: 128 # Default memory for all functions

Resources:
  GinbootFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: bootstrap # The name of your compiled Go binary
      Runtime: go1.x
      CodeUri: build/ # Path to your compiled binary
      Architectures:
        - x86_64
      Events:
        Api: # This defines an API Gateway endpoint
          Type: Api
          Properties:
            Path: /{proxy+}
            Method: ANY

Key Sections in `template.yaml`

Transform: AWS::Serverless-2016-10-31: Specifies that this is a SAM template.
Globals: Defines properties that apply to all resources of a certain type (e.g., Function).
Resources: Declares the AWS resources that make up your application.
- GinbootFunction: This is your Lambda function.
  - Handler: bootstrap: Points to the compiled Go binary named bootstrap (generated by ginboot build).
  - Runtime: go1.x: Specifies the Go runtime for Lambda.
  - CodeUri: build/: Indicates that the Lambda code is located in the build/ directory.
  - Events.Api: Configures an API Gateway endpoint that triggers your Lambda function for any HTTP method and path (/{proxy+}).

Local Testing with SAM CLI

Before deploying, you can test your Lambda function locally using the SAM CLI.

Build Locally

sam build

Run Locally

sam local start-api

This will start a local API Gateway endpoint (usually http://127.0.0.1:3000) that proxies requests to your local Lambda function. You can then use tools like curl or Postman to test your API endpoints.

Troubleshooting

go: command not found: Ensure Go is installed and its binary directory is in your system's PATH.
sam: command not found: Ensure AWS SAM CLI is installed and its binary directory is in your system's PATH.
Deployment Errors: Check the CloudFormation events in the AWS console for detailed error messages if your deployment fails.
Lambda Function Logs: Use AWS CloudWatch Logs to view the logs generated by your Lambda function during execution.

Deployment to AWS Lambda using SAM

On this page