From 8ebe3ea0cae79765ff65f9681542f87534617eea Mon Sep 17 00:00:00 2001 From: Sanath Kumar Ramesh Date: Wed, 21 Dec 2016 14:50:23 -0800 Subject: [PATCH 1/5] Adding a HowTo Guide --- HOWTO.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 5 ++++ 2 files changed, 84 insertions(+) create mode 100644 HOWTO.md diff --git a/HOWTO.md b/HOWTO.md new file mode 100644 index 0000000000..f12a9118cb --- /dev/null +++ b/HOWTO.md @@ -0,0 +1,79 @@ +## How to Guide +AWS Serverless Application Model (AWS SAM) allows you to easily create and +manage resources used in your serverless application using AWS CloudFormation. +This document explains how to write SAM templates and deploy them to +AWS CloudFormation. + +## Writing SAM Template +Checkout the [latest specification](versions/2016-10-31.md) for details on how to write a SAM template + +## Packing Artifacts (Manual) +Before you can deploy a SAM template, you should first upload your Lambda +function code zip and API's OpenAPI File to S3. Set the `CodeUri` and +`DefinitionUri` properties to the S3 URI of uploaded files. +Now your template is ready to be deployed. + +``` +MyLambdaFunction: + Type: AWS::Serverless::Function + Properties: + CodeUri: s3:/// + ... + +MyApi: + Type: AWS::Serverless::Api + Properties: + DefinitionUri: s3:/// + ... +``` + +## Packing Artifacts (Automated) +`aws cloudformation package` [CLI command](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html) automates the above step by uploading +local artifacts, such as source code or OpenAPI file, to S3 bucket. The command +returns a copy of your template, replacing references to local artifacts with S3 location +where the command uploaded your artifacts. + +To use this command, set `CodeUri` property to be the path to your +source code folder/zip/jar and `DefinitionUri` property to be a path to +your OpenAPI file, as shown in the example below + +``` +MyLambdaFunction: + Type: AWS::Serverless::Function + Properties: + CodeUri: ./code + ... + +MyApi: + Type: AWS::Serverless::Api + Properties: + DefinitionUri: ./specs/swagger.yaml + ... +``` + +Run the following command to upload your artifacts to S3 and output a +packaged template that can be readily deployed to CloudFormation. +``` +aws cloudformation package \ + --template-file /path_to_template/template.json \ + --s3-bucket bucket-name \ + --output-template-file packaged-template.json +``` + + +## Deploying to AWS CloudFormation +SAM template is deployed to AWS CloudFormation by [creating a changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-create.html) \ +using the SAM template followed by [executing the changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-execute.html). Both the AWS Console +and AWS CLI provide commands to create and execute a changeset. + +Alternatively, you can use `aws cloudformation deploy` CLI command which +will do the changeset operations for you. The command will also wait until the +deployment completes and print debugging hints when the deployment fails. +Refer to the [documentation](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) for more details. Example usage: + +``` +aws cloudformation deploy \ + --template-file /path_to_template/packaged-template.json \ + --stack-name my-new-stack \ + --parameter-overrides Key1=Value1 Key2=Value2 +``` diff --git a/README.md b/README.md index df12eeda3b..79fa76a961 100644 --- a/README.md +++ b/README.md @@ -18,3 +18,8 @@ version. Each section should contain folders named per version to avoid confusion between the versions. + +## Usage and Examples +Checkout the [How-To Guide](HOWTO.md) and [examples folder](examples/) for +detailed instructions on how to write AWS SAM templates and deploy them +to AWS CloudFormation From 14d7e625ab17459992ff5d38ae54b6ee35cb790e Mon Sep 17 00:00:00 2001 From: Sanath Kumar Ramesh Date: Thu, 22 Dec 2016 11:18:52 -0800 Subject: [PATCH 2/5] Addressing comments to make the doc clear --- HOWTO.md | 62 +++++++++++++++++++++++++------------------------------- 1 file changed, 28 insertions(+), 34 deletions(-) diff --git a/HOWTO.md b/HOWTO.md index f12a9118cb..a90effd07b 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -1,4 +1,4 @@ -## How to Guide +# How to create serverless applications using AWS SAM AWS Serverless Application Model (AWS SAM) allows you to easily create and manage resources used in your serverless application using AWS CloudFormation. This document explains how to write SAM templates and deploy them to @@ -7,31 +7,11 @@ AWS CloudFormation. ## Writing SAM Template Checkout the [latest specification](versions/2016-10-31.md) for details on how to write a SAM template -## Packing Artifacts (Manual) +## Packing Artifacts Before you can deploy a SAM template, you should first upload your Lambda function code zip and API's OpenAPI File to S3. Set the `CodeUri` and -`DefinitionUri` properties to the S3 URI of uploaded files. -Now your template is ready to be deployed. - -``` -MyLambdaFunction: - Type: AWS::Serverless::Function - Properties: - CodeUri: s3:/// - ... - -MyApi: - Type: AWS::Serverless::Api - Properties: - DefinitionUri: s3:/// - ... -``` - -## Packing Artifacts (Automated) -`aws cloudformation package` [CLI command](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html) automates the above step by uploading -local artifacts, such as source code or OpenAPI file, to S3 bucket. The command -returns a copy of your template, replacing references to local artifacts with S3 location -where the command uploaded your artifacts. +`DefinitionUri` properties to the S3 URI of uploaded files. You +can choose to do this manually or use `aws cloudformation package` [CLI command](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html) to automate the task of uploading local artifacts to S3 bucket. The command returns a copy of your template, replacing references to local artifacts with S3 location where the command uploaded your artifacts. To use this command, set `CodeUri` property to be the path to your source code folder/zip/jar and `DefinitionUri` property to be a path to @@ -55,25 +35,39 @@ Run the following command to upload your artifacts to S3 and output a packaged template that can be readily deployed to CloudFormation. ``` aws cloudformation package \ - --template-file /path_to_template/template.json \ + --template-file /path_to_template/template.yaml \ --s3-bucket bucket-name \ --output-template-file packaged-template.json ``` +The packaged template will look something like this: +``` +MyLambdaFunction: + Type: AWS::Serverless::Function + Properties: + CodeUri: s3:/// + ... + +MyApi: + Type: AWS::Serverless::Api + Properties: + DefinitionUri: s3:/// + ... +``` + ## Deploying to AWS CloudFormation -SAM template is deployed to AWS CloudFormation by [creating a changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-create.html) \ -using the SAM template followed by [executing the changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-execute.html). Both the AWS Console -and AWS CLI provide commands to create and execute a changeset. +SAM template is deployed to AWS CloudFormation by [creating a changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-create.html) +using the SAM template followed by [executing the changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-execute.html). +Think of a ChangeSet as a diff between your current stack template and the new template that you are deploying. After you create a ChangeSet, you have the opportunity to examine the diff before executing it. Both the AWS Console and AWS CLI provide commands to create and execute a changeset. -Alternatively, you can use `aws cloudformation deploy` CLI command which -will do the changeset operations for you. The command will also wait until the -deployment completes and print debugging hints when the deployment fails. -Refer to the [documentation](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) for more details. Example usage: +Alternatively, you can use `aws cloudformation deploy` CLI command deploy the SAM template. Under-the-hood it creates and executes a changeset and waits until the deployment completes. It also print debugging hints when the deployment fails. Run the following command to deploy the packaged template to a stack called `my-new-stack`: ``` aws cloudformation deploy \ --template-file /path_to_template/packaged-template.json \ - --stack-name my-new-stack \ - --parameter-overrides Key1=Value1 Key2=Value2 + --stack-name my-new-stack + --capabilities CAPABILITY_IAM ``` + +Refer to the [documentation](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) for more details. \ No newline at end of file From 382436a2521558ffea06e684105ee847b1ebacac Mon Sep 17 00:00:00 2001 From: Sanath Kumar Ramesh Date: Thu, 22 Dec 2016 13:33:14 -0800 Subject: [PATCH 3/5] adding missing slash --- HOWTO.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/HOWTO.md b/HOWTO.md index a90effd07b..c41e9bba69 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -66,8 +66,8 @@ Alternatively, you can use `aws cloudformation deploy` CLI command deploy the SA ``` aws cloudformation deploy \ --template-file /path_to_template/packaged-template.json \ - --stack-name my-new-stack + --stack-name my-new-stack \ --capabilities CAPABILITY_IAM ``` -Refer to the [documentation](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) for more details. \ No newline at end of file +Refer to the [documentation](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) for more details. From 31fb8ba741b1209360d94a47c25960a76b29b4a9 Mon Sep 17 00:00:00 2001 From: Sanath Kumar Ramesh Date: Fri, 6 Jan 2017 11:07:07 -0800 Subject: [PATCH 4/5] adding a bit of introduction to CloudFormation --- HOWTO.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/HOWTO.md b/HOWTO.md index c41e9bba69..6377c71f1d 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -1,8 +1,18 @@ # How to create serverless applications using AWS SAM AWS Serverless Application Model (AWS SAM) allows you to easily create and manage resources used in your serverless application using AWS CloudFormation. -This document explains how to write SAM templates and deploy them to -AWS CloudFormation. +You can define your serverless application as a SAM template - a JSON or YAML +configuration file that describes Lambda function, API endpoints and +other resources in your application. Using nifty commands, you upload this +template to CloudFormation which creates all the individual resources and +groups them into a *CloudFormation Stack* for ease of management. +When you update your SAM template, you will re-deploy the changes to +this stack. AWS CloudFormation will take care of updating the individual +resources for you. + + +The remainder of document explains how to write SAM templates and +deploy them via AWS CloudFormation. ## Writing SAM Template Checkout the [latest specification](versions/2016-10-31.md) for details on how to write a SAM template From 3c1e7a9a753027a6945f8f01e3a42c0c3a561ba8 Mon Sep 17 00:00:00 2001 From: Sanath Kumar Ramesh Date: Mon, 9 Jan 2017 11:05:33 -0800 Subject: [PATCH 5/5] addressing minor comments --- HOWTO.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/HOWTO.md b/HOWTO.md index 6377c71f1d..d548b54d48 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -47,7 +47,7 @@ packaged template that can be readily deployed to CloudFormation. aws cloudformation package \ --template-file /path_to_template/template.yaml \ --s3-bucket bucket-name \ - --output-template-file packaged-template.json + --output-template-file packaged-template.yaml ``` The packaged template will look something like this: @@ -71,11 +71,11 @@ SAM template is deployed to AWS CloudFormation by [creating a changeset](http:// using the SAM template followed by [executing the changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-execute.html). Think of a ChangeSet as a diff between your current stack template and the new template that you are deploying. After you create a ChangeSet, you have the opportunity to examine the diff before executing it. Both the AWS Console and AWS CLI provide commands to create and execute a changeset. -Alternatively, you can use `aws cloudformation deploy` CLI command deploy the SAM template. Under-the-hood it creates and executes a changeset and waits until the deployment completes. It also print debugging hints when the deployment fails. Run the following command to deploy the packaged template to a stack called `my-new-stack`: +Alternatively, you can use `aws cloudformation deploy` CLI command to deploy the SAM template. Under-the-hood it creates and executes a changeset and waits until the deployment completes. It also prints debugging hints when the deployment fails. Run the following command to deploy the packaged template to a stack called `my-new-stack`: ``` aws cloudformation deploy \ - --template-file /path_to_template/packaged-template.json \ + --template-file /path_to_template/packaged-template.yaml \ --stack-name my-new-stack \ --capabilities CAPABILITY_IAM ```