bustle / sammie

Serverless Application Model Made Infinitely Easier

SAMMIE - Serverless Application Model Made Infinitely Easier

AWS's Serverless Application Model (SAM) is the official AWS provided way to define serverless applications. sammie's purpose is to get you set up and deployed in seconds using SAM.

Features

• Generate a minimal yet flexible SAM template for you to get started.
• Simplify SAM's complex packaging & deploy steps & flags into a simple deploy command.
• Provide a best practice for deploying multiple environments.

---

Prerequisites

AWS CLI - sammie uses this for all AWS operations under the hood.

Quickstart

npm i sammie -g
sammie init my-app
sammie deploy

This will generate a serverless application, deploy it to a development environment, and direct you to your app served over https!

---

Commands

init - Generates a serverless application including a SAM template & lambda function

sammie init <name>
Options:
-y, --yaml: Generate yaml for SAM template. Defaults to json, because javascript.

deploy - Deploys application

sammie deploy
Options:
-t, --template: Path to a SAM template. Defaults to sam.(json|yaml) in the current directory.
-e, --environment: An environment name to deploy. Defaults to "development".
-p, --parameters: A list of parameters to override in your template.
-s, --stack-name: Option to override the auto-generated environment stack name.
--s3-bucket: S3 bucket where code is uploaded. Defaults to Parameters.bucketName in template which is generated for you.
--s3-prefix: S3 path prefix added to the packaged code file. Defaults to stackName/year.

---

Environments

It's a best practice to create completely separate stacks for each of your application's environments, rather than a single stack with multiple lambda qualifiers, API Gateway stages, and permissions. This makes your application more portable and reduces the blast radius of taking down your live application during the development cycle.

To support this, sammie will deploy separate stacks for you based on the environment option:

E.g. your stack name is "my-app":
sammie deploy will deploy stack "my-app-development" (development is the default)
sammie deploy --environment production will deploy stack "my-app-production"

Environment variables & properties

To help add environment specific variables & properties, you can create separate SAM templates named with the environment suffix.
E.g. sam-production.json containing the following, will get merged with your base template sam.json upon sammie deploy --environment production

{
  "Resources": {
    "TestFunction": {
      "Properties": {
        "MemorySize": 1280,
        "Environment": {
          "Variables": {
            "ENV_VAR1": "var1-prod",
            "ENV_VAR2": "var2-prod"
          }
        }
      }
    }
  }
}

sammie's Issues

Call describe-stack-events on failure

When a cloudformation deploy fails, it logs this without specific failure reasons:

Failed to create/update the stack. Run the following command
to fetch the list of events leading up to the failure
aws cloudformation describe-stack-events --stack-name stack-name

Let's run that suggested command automatically as a convenience in sammie.

Remove AWS CLI dependency

cloudfront package and cloudfront deploy are exclusive to AWS CLI and not available via the JS SDK.

They are however a series of commands that are able to be rebuilt with the SDK, it's just complex.

--create-bucket-configuration LocationConstraint=eu-west-1

How would I pass a the --create-bucket-configuration LocationConstraint=eu-west-1 flag to sammie?

I am getting this error when running sammie deploy

sammie deploy --create-bucket-configuration LocationConstraint=eu-west-3
[sammie] Validating template...
 aws cloudformation validate-template --template-body file://sam.json
[sammie] Template valid ✔︎
[sammie] Creating s3 code bucket (if necessary)...
 aws s3api create-bucket --bucket sam-uploads-086445346371

An error occurred (IllegalLocationConstraintException) when calling the CreateBucket operation: The unspecified location constraint is incompatible for the region specific endpoint this request was sent to.

Error: 255
    at ChildProcess.child.on.code (/Users/prisc_000/.npm-global/lib/node_modules/sammie/src/utils.js:21:47)
    at ChildProcess.emit (events.js:182:13)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:237:12)

CREATE BUCKET flag should resolve this but can figure out how to pass the flag to sammie. Thank you!

Deploy fails with yaml template

figured this was intentional, but if you can generate a yaml template, i think you should be able to deploy with one

$ sammie deploy -y -t template.yaml
(node:27404) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): SyntaxError: Unexpected token :
(node:27404) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

[Feature Request] Handle ENV vars in Lambda functions

I have a need for deploying lambda functions with ENV vars per alias. This can be accomplished using https://github.com/awslabs/aws-sam-cli#package-and-deploy-to-lambda however the environment variables must be explicitly declared (with values) inside of the sam.json or sam.yaml file.

Since Sammie uses the template per env , i.e., adds -${env} to the stack name, I would need sammie to add these environment variables from a file on a per environment basis.

An idea is to detect ${env}.json files at the same directory level as the SAM config file sam.json. Sammie can then write those ENV vars into the lambda functions specified in sam.json if a file with the same name as the ENV exists.

E.g.

When using sammie deploy with the ENV staging, if there exists a staging.json in the same directory, extract those key values and add them to the EnvironmentVariables section of the Lambda portion of sam.json

Improved sam-packaged.json artifact handling

sam-packaged.json is created by aws cloudformation package with info specific to an individual deploy. After the deploy succeeds, sammie deletes this file.

A few enhancement ideas:

1. Delete sam-packaged.json on failure too. It's not usable again, and we don't want it getting added to source control.
2. Add a flag to explicitly keep it or do a dry-run so you can observe the output for debugging purposes. Especially useful with the sammie-specific feature that merges environment specific configs.