cf-shared-apigwv2

AWS SAM Shared Api Gateway V2 (HttpApi) macro

The AWS Serverless Application Model (SAM) defines a simplified framework on top of CloudFormation for building serverless apps.

There are several issues that are IMHO inconvenient:

• Not supported: Attach functions to externally defined API Gateway
• Not supported: Lambda as ALB target
  • community solution can be found sam-alb
• Really annoying: HttpApi event type does not work with local start-api

We created this project in order to enable using externally defined API gateway. Currently, we only support ApiGatewayV2 (HttpApi). You can learn more about ClodFormation Macros here.

Installation

In order to be able to use this Macro functions, you have to install it in every region which is used for SAM Lambda projects.

The app is installable through the Serverless App Repository.

It's named SharedApiGatewayV2.

Usage

First, you need to have already provisioned ApiGatewayV2 instance. To be able to reference this Api Gateway instance, you must export Resource Reference.

Outputs:
  HttpApi:
    Description: "API Gateway Resource"
    Value: !Ref HttpApi
    Export:
      Name: !Sub "${AWS::StackName}-HttpApi"

You can find example in demo-apigwv2.yaml.

Second, you need to add a reference to the macro in the list of transforms in your template.

Replace this:

Transform: "AWS::Serverless-2016-10-31"

With this:

Transform: ["SharedApiGatewayV2", "AWS::Serverless-2016-10-31"]

Note that the order matters - SharedApiGatewayV2 needs to come first.

Finally, you can use a modified event type (HttpApi) type, but you must configure value of ImportApiId.

  Events:
    CatchAll: #this is just event name
      Type: HttpApi
      Properties:
        Path: /{proxy+}
        Method: ANY
        ImportApiId: http-apigw-HttpApi #Reference shared Api Gateway - exact exported value from parent stack

You can see a complete example in demo.yaml.

The complete set of properties for the modified HttpApi event type are:

We want to thank aidansteele for his work on sam-alb since we used sam-alb project as an inspiration.