Move from SAM to Serverless

[mnapoli]

Closes #320, closes #351

This PR implements the change described in #320: switch from SAM to Serverless as the recommended deployment tool.

TODO

• Update the templates
• Update the demo
• Create the serverless plugin
• Store the layer versions in the repository
• Finish updating the documentation
• Update the SAM tests Serverless is slower, I'll keep SAM to run the tests for now
• Remove legacy template.yaml files
• Write an update guide I'll write it in the release notes, I want to keep the website as simple as possible
• Local development
• Bref init

Why?

Serverless lets us write much simpler and smaller config for the same result.

Here is a comparison for a HTTP application:

• with SAM (template.yaml):

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: ''

Resources:
    MyFunction:
        Type: AWS::Serverless::Function
        Properties:
            FunctionName: api
            Handler: index.php
            Timeout: 30 # in seconds (API Gateway has a timeout of 30 seconds)
            MemorySize: 1024
            Runtime: provided
            Layers:
                - 'arn:aws:lambda:us-east-1:209497400698:layer:php-73-fpm:7'
            Events:
                HttpRoot:
                    Type: Api
                    Properties:
                        Path: /
                        Method: ANY
                HttpSubPaths:
                    Type: Api
                    Properties:
                        Path: /{proxy+}
                        Method: ANY

# Outputs show up in the CloudFormation dashboard
Outputs:
    DemoHttpApi:
        Description: 'URL of our function in the *Prod* environment'
        Value: !Sub 'https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/'

• with Serverless (serverless.yml):

service: app

provider:
    name: aws
    runtime: provided

functions:
    api:
        handler: index.php
        timeout: 30 # in seconds (API Gateway has a timeout of 30 seconds)
        layers:
            - 'arn:aws:lambda:us-east-1:209497400698:layer:php-73-fpm:7'
        events:
            -   http: 'ANY /'
            -   http: 'ANY /{proxy+}'

Read #320 for more details on what we gain.

Note that SAM will continue to work with Bref. You don't have to ditch SAM if you'd rather stick with it. That's fine.

Serverless plugin

This closes #351

On top of switching to Serverless, this PR provides a Serverless plugin. For the moment the plugin provides the following variables:

• bref:layer.php-72
• bref:layer.php-73
• bref:layer.php-72-fpm
• bref:layer.php-73-fpm
• bref:layer.console

This makes it easier to reference Bref layers. Here is a diff to show how to use them:

+ plugins:
+     - ./vendor/bref/bref

functions:
    api:
        handler: index.php
        layers:
-            - 'arn:aws:lambda:us-east-1:209497400698:layer:php-73-fpm:7'
+            - ${bref:layer.php-73}
        events:
            -   http: 'ANY /'
            -   http: 'ANY /{proxy+}'

It is shorter, simpler (no need to care about the region anymore), but it also means we don't have to track and update layer versions anymore. To get the latest versions you just need to update Bref via composer update.

[mnapoli]

I got a bit carried away, I rewrote a good part of the documentation to get started and install everything. Much clearer now, and I've added screenshots to create the AWS access keys.

I have also finished the plugin and started documenting it. Everything is awesome, I can't wait to release that. The whole developer experience will be much much better I think.

[mnapoli]

Preview URL for the documentation: https://5d2303e6a4cbf9110aba55cd--bref-website.netlify.com/docs/environment/serverless-yml.html

[mnapoli]

I have deprecated vendor/bin/bref invoke in favor of serverless invoke:

• simpler to use (picks up the region from serverless.yml for example)
• all commands in one tool (serverless)
• less things to maintain in Bref

The command will still work for now, I haven't removed it.

[mnapoli]

Regarding local development, since serverless-offline doesn't work with layers yet (dherault/serverless-offline#648), and since it is pretty slow anyway, I've edited the docs to suggest using a classic stack when running locally (for HTTP only).

We are separately working on Docker images in #237, that should help running locally with an environment close to production. And it will be super fast as well. But at least it won't block this pull request.

[lmcnearney]

I pulled the serverless branch down and was playing around with it. One immediate issue I had was that any serverless command would load the plugin but error out as it couldn't open the layers.json file. Looking at some other plugins, they resolve the path using the __dirname global.

const fs = require("fs");
const path = require('path');
const filename = path.resolve(__dirname, 'layers.json');
const layers = JSON.parse(fs.readFileSync(filename));

[mnapoli]

@lmcnearney thank you for testing, I really appreciate it! Until now I have tested it in the Bref repository, and paths are different here ^^

I'll work on fixing this. Thanks again.

[mnapoli]

Thanks for the code example @lmcnearney! That should be fixed.

As soon as the build finishes I'll be merging and tagging an alpha version, that way it will be easier to test locally.