This is a Feature Proposal

Description

Different implementation approaches we can take to resolve issues with a high resource count (such as #2387).

Refs #2995

1. Auto-Detect Swagger / OpenApi files

The user simply drops his own swagger / openapi file in the root of the service.
Serverless picks up this file automatically and uses this for the CloudFormation AWS::ApiGateway::RestApi resource.

Note: Serverless will fallback to the old CloudFormation approach if no swagger.yml / openapi.yml file is given.

This way Serverless will only generate the necessary resources to use OpenAPI for the API definition.
The high resource caused by the resource generation to create APIs with CloudFormation will be gone.

Upsides

• Reduces the resource problem for endpoint heavy services
• Uses the better, more feature rich OpenAPI standard
• More freedom for users since they have the full control over the openapi file

Downsides

• Only applies for APIs and won't help if the serverless.yml file is bloated because of other, non-api related resources
• The user has to write the openapi.yml file on his own

2. Compile http events to Swagger / OpenAPI definitions

Introduce the opt-in switch useOpenApi: true in the serverless.yml file to enable auto-compilation of http events to corresponding OpenAPI resources:

# serverless.yml

provider:
  useOpenApi: true

The opt-in is used to prevent breaking changes. We can deprecate this later on and always compile to OpenAPI definitions.

Serverless will auto-generate a openapi.yml file which is also pushed to the deployment S3 bucket. Additionally we can easily implement a way for users to drop-in their own openapi.yml file later on.

Upsides

• Will reduce high endpoint count
• Uses the more feature-rich OpenApi standard (we could e.g. introduce binary support)

Downsides

• Harder to overwrite / extend this file since Serverless auto-generates it for
• More complex to implement
• Only applies for APIs and won't help if the serverless.yml file is bloated because of other, non-api related resources

3. Use nested stacks

Introduce the opt-in switch useNestedStacks: true in the serverless.yml file to automatically let Serverless split up too large stacks into logical units of nested stacks.

# serverless.yml

provider:
  useNestedStacks: true

The opt-in is used to prevent breaking changes.

Serverless will automatically upload all the different parts of the nested stacks to S3.

Upsides

• Can be applied to all different kind of resources
• Can always be applied (services can be as big as needed)
• Faster deployments (not 100% sure if this really holds true)

Downsides

• Logic where to split the stacks is hard to implement (should be deterministic to reduce problems during re-deployments)
• Having multiple stacks to deal with and keep track of can be unintuitive
• Atomic deployments can be problematic when e.g. one stack gets into a weird state whereas the other succeeds

4. Use cross stack references

WIP

Upsides

• TBD

Downsides

• TBD

5. Use AWS::Include Transform

WIP

Use transform to split up and reference other CloudFormation templates.

Upsides

• TBD

Downsides

• Seems to only work with changesets
• See "huge" list of remarks in the official docs

Useful resources

• http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html
• http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/walkthrough-crossstackref.html
• http://forum.serverless.com/t/cross-stack-references/1402

/cc @brianneisler @eahefnawy @serverless/vip