[doc] Updated deployment guidance for SAM

[mattcorey]

AWS SAM seems to have evolved since the documentation and examples have been written, and we could benefit from guidance in taking advantage of features like Makefile builds, 'sam sync' and 'sam local start-api'

I've created a Makefile build that works reasonably well, and takes advantage of incremental builds, but it doesn't work with the 'sam sync' command (it continuously builds and deploys).

Below is my template.yaml and Makefile - with this, I can use the following commands:

• sam build
• sam deploy
• sam local start-api

template.yaml:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: SAM Template for APIGateway Lambda Example

Resources:
  # Lambda function
  # .build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/LinksService/LinksService.zip
  LinksService:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: makefile
    Properties:
      CodeUri: .
      Timeout: 60
      Handler: swift.bootstrap  # ignored by the Swift runtime
      Runtime: provided.al2
      MemorySize: 512
      Architectures:
        - arm64
      Environment:
        Variables:
          # by default, AWS Lambda runtime produces no log
          # use `LOG_LEVEL: debug` for for lifecycle and event handling information
          # use `LOG_LEVEL: trace` for detailed input event information
          LOG_LEVEL: debug
      Events:
        HttpApiEvent:
          Type: HttpApi

Outputs:
  # print API Gateway endpoint
  APIGatewayEndpoint:
    Description: API Gateway endpoint URL
    Value: !Sub "https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com"

Makefile (changing into the WORKING_DIR each time to use incremental builds - sam build creates a new temp directory with each build):

	WORKING_DIR = $(PWD)

build-LinksService:
	cd $(WORKING_DIR) && swift build
	cd $(WORKING_DIR) && swift package archive --allow-network-connections docker
	mv $(WORKING_DIR)/.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/LinksService/* $(ARTIFACTS_DIR)

[sebsto]

Thank you for having submitted this. I agree that we should document how to nicely integrate with sam native way of managing the build. Makefile is indeed part of the solution.
I have developed SAM Makefile for Swift last year (see https://github.com/swift-server-community/aws-lambda-swift-sam-template/blob/main/templates/api-to-lambda/%7B%7Bcookiecutter.__project_name%7D%7D/Makefile)

I will modify the doc and the example code to ensure this use case is correctly supported and documented.