[RFC] Attaching Hooks to SAM CLI Commands for Executing Custom Commands

[qingchm]

Introduction

SAM CLI is a tool that helps developing and deploying serverless applications, providing a complete serverless experience interacting with AWS. Currently a complete development cycle consists of steps such as validating, building, local and cloud testing, and deploying, which are all fulfilled by SAM CLI commands. To expand the development routine from using a combination of SAM native commands, we want to provide customers with their own ability to define actions alongside the SAM command executions. By attaching series of actions to a SAM command, customers can develop their own verification and testing steps to involve in SAM’s development iteration.

Definition of SAM CLI Development Life Cycle

Life cycle refers to a flow of processes for a certain system. For SAM CLI, the development life cycle is a user-oriented system that is highly adhere to developer’s usual development, testing and deployment iteration. Starting from the project initiation, SAM CLI life cycle starts with sam init command, and involve the below flow of processes.

The validate and build phases are the start of the application development, where the serverless application is created and validated for its deployment readiness. After the application is validated and built, we support local emulations of lambda function invocations and API functionality testing. Following the local command runs, we have deployment supporting commands that help with shipping the code packages and the stack template to cloud. After the application gets deployed, we also support cloud-oriented testing strategy with logs and traces command that help collecting cloud testing results. Also this year we have proposed to introduce remote invoke support #5018 , making remote testing more convenient. Currently, all steps of the life cycle are assembled through a series of SAM commands.

With the introduction of the SAM Accelerate project, the development cycle can be simplified to a heavily cloud-based cycle as illustrated below. We introduced a “sync” command which efficiently updates the cloud resources upon every source code change. With a single command run, the cloud resources will already be ready for remote testing, which is also why we have the above mentioned remote testing related commands as a part of the Accelerate project to support this real-time deployment model. In that regards, one sync command plus one remote invoke command can complete a development cycle on its own. Particularly, “sam sync” has a “watch” option which monitors all local updates and automatically deploy them to the cloud. Using this mode, the user can just finish the whole development process with only one sam command run. But this is not compatible with the remote testing schemas that we support, as to test a particular update, the customer needs to either kill the watch session or open another terminal.

And for that reason, the idea of adding hooks to our SAM commands become interesting. What if we can just attach a customizable set of commands to run automatically after every sync update? Then we can truly develop with just one running watch session on the side.

Proposed SAM CLI Life Cycle Hooks

As mentioned above, this is one of the inspirations to invite customers into our development life cycle above with hooks attached to every command. By inserting certain command runs before and/or after a certain command, customers can build their own flow logic of their development routine. We are offering hooks at both the start and the end of each command.

Pre-hooks

Pre-hooks are a set of commands that will be ensured to execute before a command run, one example is illustrated below.

sam deploy \
    --stack-name test-stack \
    --guided \
    --pre-hook 'sam validate --lint'

Post-hooks

Pre-hooks are a set of commands that will be ensured to execute after a command run, one example is illustrated below.

sam deploy \
    --stack-name test-stack \
    --guided \
    --post-hook 'aws lambda invoke --region=us-west-2 --function-name=$PHYSICAL_ID response.json && cat response.json'

Alternative Option Input: samconfig

Alternative to a string input to represent one command hooked, the customer can also provide a list of commands as the command input (which is easier to maintain in a stored samconfig file), one example is illustrated.

sam deploy \
     --guided \
    --config-file samconfig.toml \
    --config-env default

Inside the samconfig.toml file, the user can specify the serial of commands.

version=0.1
[default.deploy.parameters]
stack_name = "test-stack"
post_hook = [
    "aws lambda invoke --region=us-west-2 --function-name=$PHYSICAL_ID response.json && cat response.json",
    "echo Logical ID of my function $LOGICAL_ID",
    "echo Physical ID of my function $PHYSICAL_ID"
]

Alternative Option Input: shell script

Alternative to the above options, users can also input the hook in the format of a shell script file, which we will execute. One example is illustrated.

sam deploy \
     --guided \
    --post-hook hooks.sh

The shell script is just a normal shell script that the current user has execution permissions to. An example shell script that can be used as hook is illustrated.

#!/bin/sh
set -eu

aws lambda invoke --region=us-west-2 --function-name=$PHYSICAL_ID response.json && cat response.json
echo Logical ID of my function $LOGICAL_ID
echo Physical ID of my function $PHYSICAL_ID

Make Hooks Resource-specific

Users can also make the hooks targeting a specific resource, which means that the actions of the hook only applies to that resource, one example is illustrated.

sam build \
    --use-container \
    --post-hook HelloWordFunction='sam local invoke'

Hooks in Accelerate Context

For accelerate context, the hooks will be applied with the exact same logic. However, with the “watch” option or the “tail” option on, the user can utilize the execution of hooks every event within the command session. With this integration of hooks into the running session, the user can repetitively experience the full development cycle without having to interrupt the command run session. One example is illustrated.

sam sync \
    --stack-name test-stack \
    --watch \
    --code \
    --post-hook HelloWorldFunction='aws lambda invoke --region=us-west-2 --function-name=$PHYSICAL_ID response.json && cat response.json'

SAM CLI Command Life Cycle

Normal Command Life Cycle

Then what does the life cycle of a single look like now? For all normal commands, the execution order will be:

1. IaC hooks, these are the IaC integration hooks that prepare IaC projects (such as Terraform) for SAM readiness
2. Life Cycle pre-hooks
3. SAM CLI command run, where the command context will be executed
4. Life Cycle post-hooks

Accelerate’s Special Command Life Cycle

As for the Accelerate context, since throughout a sync watch session updates can go out consecutively, the life cycle of a command will look somewhat circular. Each local update event will trigger the execution of IaC hooks, pre-hooks, command itself, and post-hooks according to order.

Error Handling

By default as the pre-hooks and post-hooks are a part of the command life-cycle, therefore any failure in executing the hooks will signal the failure in the command run. But we can also introduce a non-interrupting mode for hooks to fail without terminating the command execution and failing the command.

Request for Comments

We are looking for general comments on the following topics as well as thoughts regarding the new SAM CLI command:

• Is it useful to support pre-hooks and post-hooks to execute on certain resource-types besides resource-ids?
• Which use case will you be interested in using the hooks in? Or which commands can benefit the most by having hooks implemented?
• Does it make sense for sync watch related use case to trigger hooks on every update by default? Or is there a need to support only executing hooks for watch session only upon Ctrl+C terminating the process?
• Any comments on the proposed execution order of the command life cycle?
• By default the failure of hook executions will result in the failure of the command, is it useful to provide a non-failing flag so that one hook failure will not terminate a watch session so that the user can continue development without interruption?

We encourage the community to provide feedback and suggestions for the proposed design and how SAM CLI can help improve the developer experience.

[trallnag]

Which use case will you be interested in using the hooks in?

In applications written in Python, in my team we use Poetry to manage dependencies instead of plain requirements files like SAM expects. This requires us to export the dependencies to a requirements.txt file with poetry export and place the file at the correct location before executing a SAM command like sam local start-lambda.

It would improve the developer experience to have SAM support such hooks. Or of course direct support of Poetry.

[shashanklmurthy]

As a developer using SAM, this would certainly improve developer experience and allow infrastructure teams to implement a lot of customizations on top of the sam accelerate capabilities.

Examples of where supporting pre and post sync hooks would be useful

PreSync tasks

1. Valiidate SAM template to catch syntax errors.
2. Check AWS credentials & permissions to prevent auth failures.
3. Ensure required environment variables are set for the deployment.
4. Verify dependencies & install missing packages (pip/npm).
5. Run linting & formatting checks (flake8/eslint) for code quality.
6. Run security scans (Snyk/Bandit) to detect vulnerabilities.
7. Run unit/integration tests to catch regressions early.

Etc

Post-Sync Tasks

1.Clear cache in S3/DynamoDB to avoid stale data issues.
2. Send deployment notifications (Slack, email) for visibility.
3. Warm-up Lambda functions to reduce cold start delays.
4. Trigger a health check to verify the application is running.
5. Update monitoring dashboards with new sync details( particularly useful in a multi account integration environment)
6. Invalidate CloudFront cache to ensure updated frontend assets are served during local tests.

Having plugins in SAM would help bring some parity with other cli tools like kubectl in terms of capabilities and allow developer experience teams to automate repeatable tasks needed to speed up development.