Creates a SAM template for a given project
Project description
SAM Template Creator
Intro
The SAM Template Creator helps you set up Infrastructure as Code for an AWS serverless project. It reads your project folder and generates a SAM template containing the necessary functions, globals, environment variables, etc.
Compared to a full-fledged framework like Serverless, the scope of this template creator is limited. But this has advantages as well: the tool is lightweight, generating no additional files except your IaC yaml, and is simple to use.
Finally, the tool will probably be insufficient to handle very complex use-cases, though it can still provide a starting point to expand upon.
Requirements
- python 3.5 or higher
- pip
- a serverless project to scan. Currently only Python and Go projects are supported. Node and Java are planned.
Usage Guide / How-to
Install the tool using pip
pip install sam-template-creator
# or alternatively
pip3 install sam-template-creator
Now either go to the root directory of your project and type
sam-template-creator --location .
# or with shorthand argument names
sam-template-creator -l .
The tool will also work with absolute paths
sam-template-creator --location /path/to/project
The script will create a template.yaml
file in the root of your project's directory. Check its contents! It might point out some things you have to fill in.
You can also pass some (optional) arguments:
- language: by default, the tool will guess which language the project is written in. If it does not find the correct language, or if you want an older version of the runtime (the script will default to the latest version), you can use this argument.
- globals: if used, the memory and timeout of the lambdas will be set globally, instead of per function
With your template created, you should now be able to deploy to AWS using
aws cloudformation package --template-file template.yaml --s3-bucket YOUR-BUCKET-NAME --output-template-file outputSamTemplate.yaml
aws cloudformation deploy --template-file outputSamTemplate.yaml --stack-name PICK-A-STACK-NAME --capabilities CAPABILITY_IAM
Notes on usage
Important! SAM Template Creator requires your project to be organised in a certain way.
See generics (across languages) and specifics (per language) below.
Directory
Every lambda should have its own directory, under the root of the project. Other files can be present in the same directory. The tool will scan both the file containing the handler and files it directly refers to for information on required permissions, environment variables, etc.
If a single zip (for most languages) or executable is present in the folder of the handler file, or a subfolder, the tool assumes this zip contains the code you want to upload to AWS.
Naming conventions
Python
- the name of the Lambda handler function should contain the word 'handler'. The event should end with 'event' and the context should be 'context'.
For example
def lambda_handler(s3event, context)
- if part of the name equals a http method, we assume you want to map it to an api gateway method with the path represented by the rest of the name.
For example, if your handler's name is
def put_hello_world_hander(event, context)
, the function is mapped to aPUT
to/hello/world
. - if the lambda is triggered by an event source, the name should reflect this.
For example, if s3 is the source, the name of the event should contain
s3
:s3event
ors3_event
or...
Go
- the name of your executable should be
handler
, except if you have an executable in the folder of your lambda. If so, the tool will assume that this executable has the code of your lambda. It will setHandler
andCodeUri
accordingly.
For example, if your foldermylambda
contains amain
file underdist/main
, theHandler
will becomemain
, with theCodeUri
equal to/mylambda/dist/main
. - if you want to map a function to an api gateway method, the lambda handler should end with the word Request, with the path and method prepended to this word.
For example,
func PostAddHelloRequest(_ context.Context, event events.APIGatewayProxyRequest) error
is mapped to aPOST
to/add/hello
. - if the lambda is triggered by an event source, the name should reflect that.
For example, if s3 is the source, the name of the event should contain
s3
, like this:s3event
ors3_event
or...
Node
- TODO
Java
- TODO
Project Structure
There are three main parts to this project
reader
: contains files that help with reading the files in the project. TheFileInfo.py
class reads an individual file and retrieves resources and other configuration information. Because files will look very different depending on the language, it uses the strategy pattern to aid in these language-specific tasks. For example, when dealing with Python, thePythonStrategy
class is used.middleware
: these files and functions take the information from the read side and do transforms, adding/removing certain config, before this is passed to the writers.writer
: these files are responsible for writing the information to yaml.
Besides these folders, there is a util
folder, the coordinator.py
file which coordinates the work of the other files and the command_line.py
,
which contains the argument parser and calls the coordinator after checking the input.
Tests
Unit tests can be run with python -m unittest
. A relatively simple it-test is run with the bash script test.sh
under tests/it-test.
It requires a bucket as argument (for uploading the lambda zip) and default AWS credentials.
Planned improvements
- Languages
- Node
- Java
- Robust error handling
- Ask questions. See you call dynamo, add to template? generate outputs? how many buckets for events? deploy template? use 'middleware' for this
- Option to specify which kind of folders in project contain lambdas? or what kind of structure?
- Polyglot projects?
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sam-template-creator-0.1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3a748e6872bd4b9d73b470e5515ddc43320e9bfd4e66f9ee4575e8ba1e68766d |
|
MD5 | a8a667a6cada44671169ac458cbd80de |
|
BLAKE2b-256 | 8b14dad1493953b6f6cd8115c00ff861c8e1d971e2ef04845862adcc75397dd2 |
Hashes for sam_template_creator-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 42e033322b5ce9125faf38868cdaa4fa1282544908e7c7d6175c1c2c0233aee1 |
|
MD5 | 6dc9575ed6ac1a97828ebd4683059a02 |
|
BLAKE2b-256 | de789697aa76d9ced614ed7e31d8247660398edcb49d823bc4fe80c1d515b310 |