Example: AWS SAM

I think it could be useful to have a basic canonical example of how to use SAM from CDK (See also: #703, https://github.com/awslabs/aws-sam-cli/issues/663)

If it would be useful, I could probably knock together what I figured out here into a PR to examples? If so… what would be the best naming/etc for it? Potentially could choose one of the simpler examples from the following and translate it to CDK:

• https://github.com/awslabs/serverless-application-model/tree/master/examples

I found the following, so should be doable:

• https://github.com/awslabs/aws-cdk/tree/master/packages/%40aws-cdk/aws-sam

But when I was exploring the docs, it didn’t look like I could do much without dropping into the cloudformation namespace (which is probably fine, as this is ‘lower level/direct mapping’):

• https://awslabs.github.io/aws-cdk/refs/_aws-cdk_aws-sam.html

So I decided to try and make a basic function example from that, just to see how it would work. It took me a little while to figure the intricacies of the types used and their interrelations:

import sam = require('@aws-cdk/aws-serverless');

const helloWorld = new sam.cloudformation.FunctionResource(this, "HelloWorld", {
            functionName: "HelloWorld",
            description: "Greeting the world",
            codeUri: "./target",
            handler: "hello-world",
            runtime: lambda.Runtime.Go1x.name,
            tracing: "active",
            events: {
                CatchAll: {
                    type: "Api",
                    properties: {
                        path: "/{proxy+}",
                        method: "ANY",
                        // restApiId: ""
                    }
                }
            }
        });

Which synthesises to:

Transform: 'AWS::Serverless-2016-10-31'
Resources:
    HelloWorld:
        Type: 'AWS::Serverless::Function'
        Properties:
            CodeUri: ./target
            Handler: hello-world
            Runtime: go1.x
            Description: 'Greeting the world'
            Events:
                CatchAll:
                    Properties:
                        Method: ANY
                        Path: '/{proxy+}'
                    Type: Api
            FunctionName: HelloWorld
            Tracing: active
    CDKMetadata:
        Type: 'AWS::CDK::Metadata'
        Properties:
            Modules: '@aws-cdk/assets=0.9.0,@aws-cdk/aws-cloudwatch=0.9.0,@aws-cdk/aws-codepipeline-api=0.9.0,@aws-cdk/aws-ec2=0.9.0,@aws-cdk/aws-elasticloadbalancing=0.9.0,@aws-cdk/aws-events=0.9.0,@aws-cdk/aws-iam=0.9.0,@aws-cdk/aws-kms=0.9.0,@aws-cdk/aws-lambda=0.9.0,@aws-cdk/aws-s3=0.9.0,@aws-cdk/aws-s3-notifications=0.9.0,@aws-cdk/aws-serverless=0.9.0,@aws-cdk/aws-sqs=0.9.0,@aws-cdk/cdk=0.9.0,@aws-cdk/cx-api=0.9.0,js-base64=2.4.5,poc-aws-cdk=0.1.0'

CDK References:

• https://awslabs.github.io/aws-cdk/refs/_aws-cdk_aws-sam.html#functionresource
• https://awslabs.github.io/aws-cdk/refs/_aws-cdk_aws-sam.html#functionresourceprops-interface
• https://awslabs.github.io/aws-cdk/refs/_aws-cdk_aws-sam.html#@aws-cdk/aws-sam.cloudformation.FunctionResource.ApiEventProperty

SAM References:

• https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
• https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#event-source-types
• https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#event-source-object
• https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api

[eladb]

Eventually, you should be able to achieve the same results you currently achieve with the SAM resources by simply using the AWS Construct Library.

The CDK already has support for Lambda via the @aws-cdk/aws-lambda module, and we are working on an API Gateway module (see #665) which will allow you to implement the above example like this:

const handler = new lambda.Function(this, 'HelloWorldHandler', {
  description: 'Greeting the world',
  code: apigw.Lambda.directory('./target'),
  handler: 'hello-world',
  runtime: lambda.Runtime.Go1x,
  tracing: lambda.Tracing.Active
});

const api = new apigw.RestApi(this, 'HelloWorldApi');
api.root.onMethod('ANY', handler);

Furthermore, we are looking at ways to allow people to use SAM CLI with CDK Apps, in order to enable local debugging of SAM apps written using the CDK (whether or not they use the SAM resources).

[jfuss]

@cpmech Circling back here. We released v0.21.0 earlier this week. This has support for reading and understanding AWS::ApiGateway::Methods, AWS::ApiGateway::RestApi, AWS::ApiGateway::Resource, and AWS::ApiGateway::Stage. This will allow you to do a cdk synth > template.yaml and then sam local start-api to test your functions.

@eladb Might be able to close this out. Could be useful to expand the docs though. I don’t have direct bandwidth to tackle a doc update right now though.