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:
- Install and compile Lambda function dependencies
- Create Lambda code package zip files
- Upload zip files to s3
- Generate a deployable Cloudformation template which references uploaded zip files
- Submit the generated template to Cloudformation
- 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 -n {stack} -e {environment} -r {git ref}
Stacks using the CodeBuild deployment strategy can specify which build image to use in the Stack Settings page:
Newly-created stacks default to the latest Amazon Linux image, currently version 3.0, whereas some existing stacks may be set to Ubuntu Standard 2.0.
Choosing a specific build image is useful in the case of certain runtimes, such as DotNetCore3.1, that require the 3.0 version of the Amazon Linux image. To find out the build image requirements for your runtime, please reference the AWS CodeBuild docs.
Additional options:
--prepare-only: Prepare a deployment in your AWS account without executing the generated CloudFormation template
The CodeBuild deployment strategy is only available and is the default for Stackery Professional and Enterprise accounts. Developer accounts default to the local deployment strategy.
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
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.
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 generatedtemplate.yamlfile 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.yamlgenerated 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 within the .stackery directory that consists of the following two lines:
- Change Set ID
- 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 CloudFormation 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
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.