3.2.1

Deploying Your Stacks

When you deploy your apps to AWS, you want everyone on the team to deploy consistently. You'll also want extensibility so you can customize the process to meet your unique needs, and the ability to easily debug build and deploy issues.

Deploying AWS SAM applications involves a series of steps by which the application code and infrastructure configuration are published to an AWS account and made active.

The basic steps for deploying AWS SAM apps is:

  1. Install and compile Lambda function dependencies
  2. Create Lambda code package zip files
  3. Upload zip files to s3
  4. Generate a deployable Cloudformation template which references uploaded zip files
  5. Submit the generated template to Cloudformation
  6. Execute the Cloudformation Change Set

Stackery Deployments provides multiple pre-configured deployment strategies and is customizable to meet any application and organizational needs.

Triggering Deploys

Deploys can be triggered using the stackery deploy cli command or through the Stackery dashboard. See the stackery deploy cli documentation for details on the command line interface and options.

Deployment Strategies

Stackery provides multiple pre-configured strategies for deploying your serverless applications.

This section introduces each strategy and provides the appropriate deploy command, which can all be referenced in the stackery deploy cli docs.

AWS CodeBuild

Triggers an AWS CodeBuild job in your account (named StackeryFactory) which is preconfigured to clone the project's git repository and deploy the project.

This CodeBuild project is automatically created when you link your AWS account with Stackery. Stackery applies minimum permissions and does not have access to any other AWS CodeBuild projects besides Stackery Factory.

This strategy has the benefit of building your function code artifacts in your AWS account.

stackery deploy --strategy codebuild -n {stack} -e {environment} -r {git ref}

Additional options:

  • --prepare-only: Prepare a deployment in your AWS account without executing the generated CloudFormation template

Local Checkout

The Local Checkout strategy uses the Stackery CLI to build your deployable artifacts using a locally checked out copy of the project. This is useful for debugging builds on a developer workstation or for running the Stackery deploy process on your own designated CI/CD server.

With this strategy you are responsible for cloning the appropriate version of your code and invoking the appropriate stackery deploy command to initiate the deployment process.

stackery deploy --strategy local -n {stack} -e {environment}

Additional options:

  • --prepare-only: Prepare a deployment in your AWS account without executing the generated CloudFormation template
  • --template-path: Path to template
  • --base-dir: Build & Package your stack locally by resolving relative paths to a function's source code with respect to this folder (default ".")
  • --use-container: Runs 'sam build' with the '--use-container' flag to build your function inside an AWS Lambda-like Docker container
  • --deploy-hooks-dir: Path to a folder where deploy phase overrides are located (default "deployHooks")

Legacy

This strategy builds your deployable artifacts in a AWS Lambda based pipeline hosted in Stackery's backend. It is supported for backwards compatibility reasons but discouraged for new projects.

stackery deploy --strategy legacy -n {stack} -e {environment} -r {git-ref}

Additional options:

  • --prepare-only: Prepare a deployment in your AWS account without executing the generated CloudFormation template

Interactive Deploy

The interactive-setup deploy flag is a guided way to deploy new stacks locally. If you need to link your AWS account before deploying, or want to create a new environment to deploy into, the setup will walk you through those steps, then deploy your stack using the local deploy strategy.

It needs to be run from the root directory of the stack you would like to deploy.

Try it by running stackery deploy --interactive-setup (no other flags required).

Deployment Phases

A Stackery deployment can be broken up into major phases. Each phase can be overridden or customized using pre and post hooks providing a high degree of customizability and extensibility.

The Stack Overview
Stack Deployment phases in Stackery

Build

Invokes the standard AWS sam build command to:

  • Install dependencies of each function in your stack
  • Generate the deployment artifacts to be packaged in the next phase

Note that passing the --use-container flag will ensure functions are installed in a Lambda-like container, which is useful if your function contains compiled dependencies.

Expected input files

  • .stackery/<template.yaml>: Stackery provides the appropriately generated template.yaml file for your stack. The template includes resolved parameters, tags, and wait condition resources needed to satisfy CloudFormation requirements. This input cannot be overridden.

Required output files

In the project's files, a new directory ./aws-sam/build/ that consists of the following files:

  • template.yaml generated automatically by Stackery
  • Separate directories for Functions that include the built source code needed to run
.aws-sam
    ├── build
        ├── template.yaml
        ├── Function1
              // built files needed to run
        └── Function2
              // built files needed to run

Package

Invokes the standard AWS sam package command to:

  • Zip local files
  • Upload these zipped files to an S3 bucket
  • Update the template to point to these S3 paths
  • Upload the updated template to S3 for CloudFormation to use on stack deploy.

Expected input files

Accepts the output files from the Build phase.

Required output files

A finalized packaged-template.yaml that points to the S3 locations of the packaged stack files.

.aws-sam
    ├── build
        ├── template.yaml
        ├── Function1
        ├── Function2
        └── packaged-template.yaml
              // Finalized template

Submit Change Set

Submits a CloudFormation Change Set which allows users to preview changes in a stack that may impact existing functionality or services.

Required output files

A changeset.info file wihin the .stackery directory that consists of the following two lines:

  1. Change Set ID
  2. Stack ID
.aws-sam
    ├── build
        ├── template.yaml
        ├── Function1
        ├── Function2
        └── packaged-template.yaml
.stackery
    ├── changeset.info

Execute Change Set

Executes the submitted change set in CloudFormation via the AWS SDK.

Deployment Phase Hooks

Each phase hook in a deployment phase has access to the expected input files defined above.

Pre phase hooks can alter these input files prior to the phase action (build, package, submit change set) being executed.

Post phase hooks have access to the required output files created by the phase action (build, package, submit change set) execution. These output files can be altered in the Post hook of a phase before passing them along to the next phase.

Pre-Build

Initial deployment phase hook that occurs after Stackery generates your stack template, and before sam build.

Script Name: stackery.prebuild.*

Build

Runs sam build to begin building the stack.

Script Name: stackery.build.*

Post-Build

Occurs after sam build has completed and before passing the required Build output to the Package phase.

Script Name: stackery.postbuild.*

Pre-Package

Occurs after Stackery builds the function code in the stack and before sam package.

Script Name: stackery.prepackage.*

Package

Runs sam package to generate and store required project files.

Script Name: stackery.package.*

Post-Package

Occurs after sam package has completed and before passing the required Package output to the Change Set phase.

Script Name: stackery.postpackage.*

Pre-Submit Change Set

Occurs before Stackery prepares and submits a CloudFormation change set.

Script Name: stackery.presubmitchangeset.*

Submit Change Set

Submits a CloudForamtion change set to be approved manually (--prepare-only) or automatically executed.

Script Name: stackery.submitchangeset.*

Accepts the output files from the Package phase.

Post-Submit Change Set

Occurs after a change set has been submitted to CloudFormation. If the stackery deploy command is run with a --prepare-only flag, Submit Change Set phase is the last phase in the deployment process. If --prepare-only is omitted, Stackery automatically moves to the next phase and executes the change set in CloudFormation.

Script Name: stackery.postsubmitchangeset.*

Execute Change Set

Executes the stack change set in CloudFormation.

Phase hook file requirements

When you run stackery deploy with the appropriate flags, Stackery proceeds through each deployment phase, searching for any phase hook files in the deployHooks directory or the directory you've specified. If a matching file exists, that script is executed before moving on to the next phase. If no file exists for a phase hook, the deployment process continues.

Files must adhere to the following:

  • Must be executable
  • File extension is optional and any extension is accepted(stackery.prebuild.py, stackery.postpackage, etc)
  • One file per hook. Multiple files associated with a hook will cause the deploy to fail
  • Follow the naming pattern: stackery.{phase hook}[.*]

Directory structure

The following illustrates a typical project directory structure for stackery deploy commands run in the root directory:

MyStack
  ├── src
      └── Function1
          ...
      └── Function2
          ...
  ├── template.yaml
  ├── deployHooks //default deployHooks directory with phase hook override scripts
      ├── stackery.prebuild.sh
      └── stackery.build.sh
  └── .stackery-config.yml // Default parameters for all directories in project repository

Troubleshooting

NPM Name/Version field error

NPM Failed: npm ERR! package.json requires a "name" / "version" field

The absence of the name or version fields in package.json can be addressed by running npm init on all the Function directories in the src folder.

The following one-liner runs npm init on all files in a project directory and applies the missing fields.

for i in src/*; do echo $i; (cd $i; npm init -y); done

GraphQL packaging fails for Local & CodeBuild deployments

If your stack consists of one or more GraphQL APIs, you may encounter the following error on local & CodeBuild deployments.

Unable to upload artifact ../../.stackery/Graphql/schema.graphql
referenced by DefinitionS3Location parameter of GraphqlSchema resource.
Parameter DefinitionS3Location of resource GraphqlSchema refers to a file or
folder that does not exist /private/tmp/1/myStack/.stackery/Graphql/schema.graphql

To address the way sam build handles GraphQL files, add the following script to deployHooks/stackery.postbuild.sh:

#!/bin/bash

# `sam build` updates the GraphQL Schema's 'DefinitionS3Location' and
# the GraphQL Resolver's 'RequestMappingTemplateS3Location' &
# 'ResponseMappingTemplateS3Location' properties to be relative to the
# template provided rather than from the --base-dir flag if provided

# This script will go through sam build's generated template file,
# update the paths and move the referenced files into the .aws-sam/build directory

# Update this if your template file name is not `template.yaml`
TEMPLATE=template.yaml

echo Fixing GraphQL Schema and Resolver filepaths...

sed -e 's/\.\.\/\.\.\/\.stackery\///g' -i.orig .aws-sam/build/$TEMPLATE
# Remove temp file
rm .aws-sam/build/$TEMPLATE.orig

echo Moving GraphQL Schema and Resolver files into .aws-sam/build
grep -E 'RequestMappingTemplateS3Location|ResponseMappingTemplateS3Location|DefinitionS3Location' .aws-sam/build/$TEMPLATE | sed -e 's/.*://g' | xargs -I {} dirname {} | xargs -I {} mkdir -p ".aws-sam/build/{}"
grep -E 'RequestMappingTemplateS3Location|ResponseMappingTemplateS3Location|DefinitionS3Location' .aws-sam/build/$TEMPLATE | sed -e 's/.*://g' | xargs -I {} cp ./{} .aws-sam/build/{}

Failed to fetch function layers from SSM Parameter Store (Local & Codebuild deployments)

A notable error you may encounter when working with Lambda Layers stored as Stackery environment variables, is an Invalid Lambda ARN error. If permissions for the Lambda Layer are scoped correctly, and you've confirmed it exists (in your account or another), the error may be related to this open sam build issue.

Stackery environment variables are stored in AWS SSM Parameter Store, which when used to store Lambda Layers, fails to properly resolve them. The following GitHub repository has the deployHooks directory, and deployment hook override scripts needed to continue using the Local and CodeBuild deployment strategies.

SSM + Lambda Layers deploy hook repository

← Configuring the Stackery CLIStackery CLI →