Everything you need to know before building your first SAM packaged application
This tech blog covers our experience building our first SAM packaged server-less application. SAM stands for Serverless Application Model and it is AWS’s specification for packaging its lambda functions and auxiliary components in a reusable way enabling you to share (and eventually maybe even charge) others for access to your server-less applications.
Since lots of our customers rely on our lambda integration to process and analyze their S3 stored files, it made sense for us to investigate how much benefit a customer really gets from a SAM packaged application, after all, deploying our current lambda integration is a sad 10+ step process — so we set out to build a SAM packaged webhook debug tool named Guarana.
Before building your first SAM package application, these are the things you should know:
SAM packaged applications can be shared via the Serverless Application Repo - I assume that eventually you will be able to charge for them akin to an app store for lambda functions
You can share any application that has a SAM compliant YAML file and, at least, 1 version released
The serverless repo is now prominently featured whenever you try to deploy a new lambda function, currently the applications available seem very simple and prototype-like - which makes sense since SAM is quite new
The first oddity you discover here is that there is not way to navigate to neither the repository nor your published applications via the AWS Console ¯_(ツ)_/¯
The SAM CLI
If you are going to build your first SAM packaged application, you will need to install their command line tool that will allow you to convert your SAM specification template file into a CloudFormation file (that’s right, it’s just a preprocessor)
The CLI also comes with some nice local testing support logic so you can create sample events and trigger your function using them
Another oddity of the SAM CLI is that it was recently rewritten from go to python likely to better integrate with the AWS CLI which is also written in python, however, just like any good rewrite, it introduced lots of regressions
The CLI comes with a validate function which appears to solely perform a syntax check of your template file, it would be nice if it also looked for logical flaws
Technically all you need is a template YAML file that conforms to the SAM specification, here’s ours. It’s like a .travis.yml file but significantly more complex. As stated earlier, once you have the template you can have the CLI “package” the application that effectively converts it into a proper CloudFormation file and places your application bits, as a zip file, in S3. - here’s our packaged file.
Most (but not all) lambda functions can be SAM packaged, where things will fall apart is if the function needs access to AWS resources for which there isn’t an available policy template fileand policy template files are truly the most peculiar thing about SAM
Basically, these are simplified AIM policies bundles, for example DynamoDBCrudPolicy gives you all CRUD operations on a table. Naturally, this strategy can leave your IAM role with more access than your lambda function truly needs
Albeit the official spec says that AIM policy document objects are valid in your SAM spec file, we were not able to successfully publish applications using them to the application repo, only policy templates seem to reliably work at this point
The last item of note with regards to packaging your application is that the “sam package” command, which copies your assets to the s3 bucket, does not make the object public as required by the Serverless Repo hence you need to set either a bucket policy or do an extra step to make the published asset accessible to others
Deployment and ongoing maintenance
Deploying your SAM application is refreshingly simple, if your template file identify some parameters the user will be prompted for it and once they click on deploy CloudFormation will set out to build the infrastructure for you
Upgrades work surprisingly well albeit documentation is lacking. In a nutshell if you have version 1.2.0 of guarana already deployed and you try to deploy version 1.2.1, CloudFormation will identify the same stack name (masked as “application name” in the deploy UI) and perform an upgrade instead of a new deployment, this can even involved using CodeDeploy for complex rollouts with a little bit of logic in your template file.
It would be easy to discount SAM applications as a niche AWS feature that will be used by few, even with all its rough edges, there’s still obviously value in it. If you truly believe in a server-less future with small snippets of code as the smallest units of deployment then some packaging standard makes total sense, specially if secondary providers eventually get on board to support term.