example-go-sam

This template can be used as a boilerplate for RESTful APIs built with Go, AWS Lambda, and AWS SAM.

How to use this template

Requirements

To be able to use this repo successfully you will need:

1. Go 1.23+
2. AWS SAM CLI
3. Docker (for sam build and sam local)
4. An AWS account where the resources will be created.
5. AWS IAM roles for CD via GitHub Actions. This template uses the strategy for using IAM roles during deployment that is outlined in this article. Make sure that you have ARNs for an "OIDC" role handy, since you'll need to set it as a repo secret during the set up process.
6. A DataDog API Key.

Set up your new project

1. Start a new repo with this repo as the template.
2. Clone this repo locally and switch to a new branch that will be used for repo set up.
3. Update the Description and AppCode default in template.yaml to match your new service name.
4. Update the stack_name and s3_prefix in samconfig.toml to match your new service name.
5. Update the module path in go.mod to match your new repo (e.g. github.com/xplor/your-service-name).

Run the project locally

You can use SAM CLI to run the API locally. You can get things up and running with these steps:

1. Build the project

make build

2. Start the local API

make local

3. Check that the healthcheck endpoint is working correctly

curl -i http://localhost:3000/v1/healthcheck

Set Up CI/CD

This application comes with a number of GitHub Actions workflows that we recommend you use for CI/CD.

1. Set the required repo secrets in GitHub for the IAM roles that are needed for deployment. The OIDC role should be set as OIDC_ROLE_ARN.
2. Set the DataDog API Key as the repo secret DD_API_KEY.
3. Move the GitHub actions to .github so that they will work as expected the next time you push up your code.

mv github-actions .github

4. Commit your changes and push your branch up.
5. Open a PR with the set up changes.
6. Verify that GitHub actions were run for testing and linting. We strongly recommend enforcing that these jobs pass before PRs can be merged to main.
7. Once your tests are green, merge your branch into main.
8. Verify that the Deploy action was kicked off, and that the application deploys successfully.
9. Celebrate!!!! Your new service is ready for development! Go build cool things!

Tips for local development

Linting

# run golangci-lint
make lint

# fix golangci-lint errors
make lint-fix

Linting is done using golangci-lint. The configuration is in .golangci.yml.

To install golangci-lint locally:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Tests

You can run tests with the following command:

make test

To generate a coverage report:

make test-coverage

This produces coverage.out and coverage.html in the project root.

Adding a new Lambda function

1. Create a new directory under functions/ with a main.go:

mkdir functions/my-function

2. Add a new AWS::Serverless::Function resource in template.yaml pointing to the new directory.

3. Run make build to verify the build succeeds.

Project structure

template-go-sam-api/
├── functions/                # Lambda function source code
│   └── healthcheck/          # Each function in its own directory
│       ├── main.go           # Handler entry point
│       └── main_test.go      # Handler tests
├── github-actions/           # GitHub Actions (move to .github to activate)
│   ├── dependabot.yml
│   └── workflows/
│       ├── deploy-sam.yml    # Deploy on merge to main
│       ├── lint.yml          # Lint on PRs
│       └── test.yml          # Test on PRs
├── .editorconfig             # Editor settings
├── .gitignore
├── .golangci.yml             # Linter configuration
├── go.mod                    # Go module definition
├── go.sum                    # Go dependency checksums
├── Makefile                  # Build, test, lint commands
├── README.md
├── samconfig.toml            # SAM CLI configuration
└── template.yaml             # SAM/CloudFormation template

Inspiration

• xplor/template-node-serverless-api
• aws/aws-sam-cli-app-templates
• aws-samples/serverless-go-demo