Serverless framework integration

marktani commented 6 years ago

Issue by schickling Friday Sep 29, 2017 at 08:46 GMT Originally opened as https://github.com/graphcool/prisma/issues/691

There are two ways to integrate with the Serverless framework:

1) Reference Serverless functions/resources from graphcool.yml 2) Reference a Graphcool backend from serverless.yml

1) Reference Serverless functions/resources from `graphcool.yml`

Goal

Use the Serverless framework to deploy functions on AWS (or other providers) and reference the deployed functions in the graphcool.yml file.

Design decisions

Graphcool assumes that during deploy-time all serverless functions are already deployed and can be referenced directly as AWS Lambda function

Implementation

TBD

Challenges

Avoid code duplication when referencing a serverless.yml file
IAM permissions (role statements)
Zero-downtime deployment (blue-green)

Initial limitations

Supports only AWS Lambda (other service providers can be added later)

External todos

[ ] Serverless needs to provide information about deployed functions/resources in a readable format (e.g. JSON)

2) Reference a Graphcool backend from `serverless.yml`

TBD

marktani commented 6 years ago

Comment by kbrandwijk Friday Sep 29, 2017 at 09:20 GMT

Initial thoughts:

Having two different configuration files for two different parts of the same solution is really not optimal
For 'basic' uses (inline functions and existing webhooks) the graphcool.yml method is easiest
For advanced uses (especially now the CLI has been completely refactored this should be easy), think about exposing the CLI functionality as serverless plugin, and define the entire deployment in the serverless.yml.
If you go that route, you are not limited to AWS Lambda, expecially now Serverless has just released their plugin for Webtask supporting Node 8!

marktani commented 6 years ago

Comment by kbrandwijk Friday Sep 29, 2017 at 13:38 GMT

I'll address a few different topics in different comments.

Deploying using serverless to a single provider

With serverless, the provider determines where your functions will be deployed. So for deploying functions to Graphcool (as inline functions), Graphcool needs to be defined as provider. For deploying your functions to another provider, Graphcool can be defined as a plugin. For example:

# serverless.yml with webtasks provider

service: myProject

provider:
  name: webtasks

functions:
  hello:
    handler: hello
    events:
    - graphcool:
       type: resolver
       schema: hello.graphql
  after-post-create:
    handler: after-post-create
    events:
    - graphcool:
        type: operationAfter
        operation: Post.create

custom:
  graphcool:
    permissions:
    - operation: Post.create
      authenticated: true

plugins:
  - '@webtask/serverless-webtasks'
  - 'serverless-graphcool'

# serverless.yml with aws provider

service: myProject

provider:
  name: aws

functions:
  hello:
    handler: handlers.hello
    events:
    - http:
        path: hello
        method: get
    - graphcool:
        type: resolver
        schema: hello.graphql

custom:
  graphcool:
    permissions:
    - operation: Post.create
      authenticated: true

plugins:
  - 'serverless-graphcool'

# serverless.yml with Graphcool provider

service: myProject

provider:
  name: graphcool

functions:
  hello:
    handler: hello
    events:
      - graphcool:
          type: resolver
          schema: hello.graphql

custom:
  graphcool:
    permissions:
    - operation: Post.create
      authenticated: true

Basically, anything that's in the graphcool.yml can be moved 1-on-1 under the custom/graphcool node in serverless.yml, except for the functions part, because that moves to the main serverless functions node.

marktani commented 6 years ago

Comment by kbrandwijk Friday Sep 29, 2017 at 14:00 GMT

Mix-n-match

There might be scenarios, where you want to combine different services together, deployed to different providers:

# service1/serverless.yml

service: service1

provider:
  name: webtasks

functions:
  hello:
    handler: hello
  after-post-create:
    handler: after-post-create

plugins:
  - '@webtask/serverless-webtasks'

# service2/serverless.yml

service: service2

provider:
  name: aws

functions:
  create-post:
    handler: handlers.createPost
    events:
    - http:
        path: create-post
        method: post

# serverless.yml

service: myProject

provider:
  name: graphcool

functions:
  hello:
    webhook: `${self:custom.webtaskBaseUrl}/hello`
    - events:
       - graphcool:
           type: resolver
           schema: hello.graphql
  create-post:
    webhook: `${self:custom.webtaskBaseUrl}/post-create`
    - events:
       - graphcool:
           type: operationAfter
           operation: Post.create

custom:
  webtaskBaseUrl: 'https://sandbox.it-auth0.com/container'
  awsBaseUrl: 'https://..........'
  graphcool:
    permissions:
    - operation: Post.create
      authenticated: true

marktani commented 6 years ago

Comment by kbrandwijk Friday Sep 29, 2017 at 14:17 GMT

External todos

Serverless needs to provide information about deployed functions/resources in a readable format (e.g. JSON)

Serverless actually does provide this information to plugins. It depends which provider you use. Have a look at the info command for serverless-webtasks for example, which provides you with the endpoints. AWS has something similar: https://github.com/auth0/serverless-webtasks/blob/master/lib/info/service.js#L36-L51

marktani commented 6 years ago

Comment by kbrandwijk Saturday Sep 30, 2017 at 18:30 GMT

I also created https://github.com/graphcool/graphcool/issues/710, because that aligns better with the serverless concept of having different services, each in their own folder, with their own serverless.yml file. The only wait to align that with Graphcool, is to allow deployment of different serverless services to the same Graphcool project, essentially merging.

marktani commented 6 years ago

Comment by kbrandwijk Monday Oct 23, 2017 at 12:25 GMT

@schickling Update: I took a different direction for now for integrating Graphcool and Serverless. I have described some of the details here: https://gist.github.com/kbrandwijk/86683ad58a98447b0ddc5f7f11cdb789.

Graphcool / graphcool-framework