Mason

Serverless code & doc generation + doc verification + deployment process

Mason is a command line that allows developers to create, test, document and deploy Serverless Python code. It is based on the Serveless framework. In case you are not yet familiar with it, have a look at this amazing guide and come back!

Functionalities

Mason's main features are:

• Add a function to a serverless service: generate code, tests, mocks, events, request/response JSON schemas. Integrate the function into serverless.yml.
• Publish openapi.yml file: mason elaborates the output of Serverless Openapi Documentation, and integrates it to obtain a readymade, fully actionable openapi.yml file. The file can be automatically published online, and visualized using Lincoln. Dredd is used to check whether the code is compatible with the openapi.yml specifications.
• CI+CD a serverless service: mason comes with a readymade gitlabCI pipeline that allows you to publish automatically in stage, and trigger manual deployment to production, optionally using a custom domain instead of the default cloud provider URLs.
• Check backwards compatibility of API contract: compare the openapi.yml file generated by mason with the openapi.yml that defines an existing version of an API, to check whether modifications are introducing breaking changes, using openapi-diff.
• Readymade integration with DynamoDB and ElasticSearch: generate classes that model data structures and store them into DynamoDB or ElasticSearch.

Getting started

1. Fork mason. Clone the fork on your computer: this file will be located in
2. Create a virtualenv, called /venv
3. Activate it source/venv/bin/activate and install the necessary packages pip install -r requirements.txt
4. Run sls to check all the necessary packets are installed.

Creating a function

Create your first function (a GET): python cli.py generateFunction hello --path=hello/{path_parameter} --http_verb=get. This command will update serverless.yml, and create other files to update manually.

1. /src/functions/hello.py: the code of the new function. By default, it will return a 200 response.
2. /test/functions/testhello.py: a unittest test case, which always fails. Edit it to make it meaningful.
3. /schemas/responses/hello.json: an empyt JSON schema that defines the HTTP response of the function. Use this tool to generate JSON schema.

Create your second function (a POST): python cli.py generateFunction hello --path=hello2/{path_parameter} --http_verb=post. This command will update serverless.yml, and create other files to update manually.

1. /src/functions/hello2.py: the code of the new function. By default, it will return a 200 response.
2. /test/functions/testhello2.py: a unittest test case, which always fails. Edit it to make it meaningful.
3. /schemas/responses/hello2.json: an empyt JSON schema that defines the HTTP response of the function. Use this tool to generate JSON schema.
4. /schemas/requests/hello2.json: an empyt JSON schema that defines the HTTP request of the function. Use this tool to generate JSON schema.
5. /mocks/hello2ExamplePayload.json: an empyt JSON that contains the payload of the request for the function.

Decorating a function

By default, every function is wrapped with a decorator which sends an email upon failure execution. Feel free to use other decorators, which are in /src/wrappers, or create your own decorators. Multiple decorators can be applied to every function: remember to annotate in the correct order

Documenting a function

Edit /serverless.doc.yml: edit the textual fields. Generate the documentation python cli.py doc. The documentation will be generated in openapi.yml. Go to swagger to have a preview.

Creating resources (e.g. database/cognito user pool)

Check in the /resources for a cloudformation file that describes the resource. If it exists, include it into serverless.yml, as an entry of the "resources" array. For example:

service: mason-serverless
resources:
  - ${file(resources/elasticsearch-service.yml)}

Deploying a service

Edit /serverless.doc.yml:

1. service: choose the name of the service.
2. custom/domains/*: indicate the domains where the service will be deployed.

If you have included CloudFormation resources, sls deploy will fail after the first deploy, because the given resource is already existing. Therefore, run locally

SLS_DEBUG=* serverless deploy --stage prod
SLS_DEBUG=* serverless deploy --stage stage

to initialize the stack, and then remove the resources from serverless.yml

service: mason-serverless
resources: []

Customize the pipeline

The default pipeline shipped with mason contains a script to fill credentials in your classes using environment variables, and starts an elasticsearch cluster to perform tests; in case you don't need these or other features, please consider removing it.

Use Gitlab CI to run tests and deploy:

1. Generate a IAM user who is allowed to deploy Serverless services. An example policy can be found in infrastructure-generators/configuration_files/serverless_deploy_policy.json. If your test involve writing/reading from DynamoDB, authorize the user to interact with DynamoDB to perform the required actions. An example policy can be found in in infrastructure-generators/configuration_files/interact_with_dynamo_table.json.

2. Insert AWS credentials into gitlab variables. Make credentials available also in non-protected branches.

3. Push to gitlab, on branch stage.

4. Verify that everything is working by checking the stage environment.

5. Submit a merge request for branch stage into master.