Browse the Repo

file-type-icon.circleci
file-type-iconexamples
file-type-iconmodules
file-type-icontest
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.md

Browse the Repo

file-type-icon.circleci
file-type-iconexamples
file-type-iconmodules
file-type-icontest
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.md
API Gateway

API Gateway

Define API Gateway APIs in Swagger, run your app locally using SAM, and deploy the app to production using Terraform and API Gateway.

Code Preview

Preview the Code

mobile file icon

README.md

down

Terraform Version

Serverless Application Model Package

This repo contains modules to locally test and deploy applications following the AWS Serverless Application Model (SAM) within a Terraform ecosystem.

Motivation

After evaluating AWS SAM CLI, the Serverless Framework and pure Terraform code, we realized that there wasn't an ideal solution that fit well into the Terraform/Gruntwork ecosystem. We had several goals in mind as we evaluated each solution:

  • use API Gateway
  • use Lambda Functions
  • provide a way to easily test API Gateway and Lambda Functions locally
  • provide a method deploy to production, while still managing everything as code
  • integrate with existing Terraform-managed infrastructures (for example reading database URLs from RDS deployed by Terraform).
  • minimize duplication of configuration

After looking at each of these soltions, we came to the conclusion that there isn't a comprehensive solution that met each of our goals that didn't also require a ton of additional configuration, copy/paste and extra verbosity. As a result, we decided to develop this package.

Features

The main features of the Gruntwork SAM package are:

  • Define your API once in Swagger and automatically:
    • Test your Lambda functions locally with gruntsam local and Docker
    • Start a local API Gateway and quickly iterate over your functions with hot-reloading
    • Generate Terraform code to launch your API Gateway in production on AWS

The main modules are:

  • api-gateway-account-settings: This module sets the global, regional API Gateway account settings that apply to every API Gateway defined in a region.
  • gruntsam: A lightweight wrapper around the AWS SAM CLI cli tool used for testing Lambda functions and API Gateway locally and generating Terraform code to deploy API Gateway on AWS.

Click on each module above to see its documentation. Head over to the examples folder for examples.

What is a module?

At Gruntwork, we've taken the thousands of hours we spent building infrastructure on AWS and condensed all that experience and code into pre-built packages or modules. Each module is a battle-tested, best-practices definition of a piece of infrastructure, such as a VPC, ECS cluster, or an Auto Scaling Group. Modules are versioned using Semantic Versioning to allow Gruntwork clients to keep up to date with the latest infrastructure best practices in a systematic way.

How do you use a module?

Most of our modules contain either:

  1. Terraform code
  2. Scripts & binaries

Using a Terraform Module

To use a module in your Terraform templates, create a module resource and set its source field to the Git URL of this repo. You should also set the ref parameter so you're fixed to a specific version of this repo, as the master branch may have backwards incompatible changes (see module sources).

For example, to use v0.0.1 of the api-gateway-account-settings module, you would add the following:

module "api_gateway_account_settings" {
  source = "git::git@github.com:gruntwork-io/package-sam.git//modules/api-gateway-account-settings?ref=v0.0.1"

  // set the parameters for the API Gateway Account settings   module
}

Note: the double slash (//) is intentional and required. It's part of Terraform's Git syntax (see module sources).

See the module's documentation and vars.tf file for all the parameters you can set. Run terraform get -update to pull the latest version of this module from this repo before runnin gthe standard terraform plan and terraform apply commands.

Using scripts & binaries

You can install the scripts and binaries in the modules folder of any repo using the Gruntwork Installer. For example, if the scripts you want to install are in the modules/ecs-scripts folder of the https://github.com/gruntwork-io/module-ecs repo, you could install them as follows:

gruntwork-install --module-name "ecs-scripts" --repo "https://github.com/gruntwork-io/module-ecs" --tag "0.0.1"

See the docs for each script & binary for detailed instructions on how to use them.

Developing a module

Versioning

We are following the principles of Semantic Versioning. During initial development, the major version is to 0 (e.g., 0.x.y), which indicates the code does not yet have a stable API. Once we hit 1.0.0, we will follow these rules:

  1. Increment the patch version for backwards-compatible bug fixes (e.g., v1.0.8 -> v1.0.9).
  2. Increment the minor version for new features that are backwards-compatible (e.g., v1.0.8 -> 1.1.0).
  3. Increment the major version for any backwards-incompatible changes (e.g. 1.0.8 -> 2.0.0).

The version is defined using Git tags. Use GitHub to create a release, which will have the effect of adding a git tag.

Tests

See the test folder for details.

License

Please see LICENSE.txt for details on how the code in this repo is licensed.

Questions? Ask away.

We're here to talk about our services, answer any questions, give advice, or just to chat.

Ready to hand off the Gruntwork?