Quick Start: Publishing Applications - Amazon Serverless Application Repository
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Quick Start: Publishing Applications

This guide walks you through the steps to download, build, test and publish an example serverless application to the Amazon Serverless Application Repository using Amazon SAM CLI. You can use this example application as a starting point for developing and publishing your own serverless application.

Overview

The following steps outline how to download, build and publish a sample serverless application:

  1. Initialize. Download a sample application from template using sam init.

  2. Test Locally. Test the application locally using sam local invoke and/or sam local start-api. Note that with these commands, even though your Lambda function is invoked locally, it reads from and writes to Amazon resources in the Amazon Cloud.

  3. Package. When you're satisfied with your Lambda function, bundle the Lambda function, Amazon SAM template, and any dependencies into an Amazon CloudFormation deployment package using sam package. In this step you will also include information about the application that will be uploaded to Amazon Serverless Application Repository.

  4. Publish. Publish the application to the Amazon Serverless Application Repository using sam publish. At the conclusion of this step, you're able to view your application in Amazon Serverless Application Repository and deploy it to the Amazon Cloud using Amazon Serverless Application Repository.

The example Hello World Application in the next section walks you through these steps in building and publishing a serverless application.

Hello World Application

In this exercise, you download and test a Hello World serverless application that represents a simple API backend. It has an Amazon API Gateway endpoint that supports a GET operation and a Lambda function. When a GET request is sent to the endpoint, API Gateway invokes the Lambda function. Then, Amazon Lambda executes the function, which simply returns a hello world message.

The application has the following components:

  • An Amazon SAM template that defines two Amazon resources for the Hello World application: an API Gateway service with a GET operation, and a Lambda function. The template also defines the mapping between the API Gateway GET operation and the Lambda function.

  • Application code that's written in Python.

Before You Begin

Make sure that you have the required setup for this exercise:

Step 1: Initialize the Application

In this section, you download the sample application, which consists of an Amazon SAM template and application code.

To initialize the application
  1. Run the following command at an Amazon SAM CLI command prompt.

    sam init --runtime python3.6
  2. Review the contents of the directory that the command created (sam-app/):

    • template.yaml – Defines two Amazon resources that the Hello World application needs: a Lambda function and an API Gateway endpoint that supports a GET operation. The template also defines mapping between the two resources.

    • Content related to the Hello World application code:

      • hello_world/ directory – Contains the application code, which returns hello world when you run it.

    Note

    For this exercise, the application code is written in Python, and you specify the runtime in the init command. Amazon Lambda supports additional languages for creating application code. If you specify another supported runtime, the init command provides the Hello World code in the specified language, and a README.md file that you can follow along for that language. For information about supported runtimes, see Lambda Execution Environment and Available Libraries.

Step 2: Test the Application Locally

Now that you have the Amazon SAM application on your local machine, follow the steps below to test it locally.

To test the application locally
  1. Start the API Gateway endpoint locally. You must run the following command from the directory that contains the template.yaml file.

    sam-app> sam local start-api --region us-east-1

    The command returns an API Gateway endpoint, which you can send requests to for local testing.

  2. Test the application. Copy the API Gateway endpoint URL, paste it in the browser, and choose Enter. An example API Gateway endpoint URL is http://127.0.0.1:3000/hello.

    API Gateway locally invokes the Lambda function that the endpoint is mapped to. The Lambda function executes in the local Docker container and returns hello world. API Gateway returns a response to the browser that contains the text.

Exercise: Change the message string

After successfully testing the sample application, you can experiment with making a simple modification: change the message string that's returned.

  1. Edit the /hello_world/app.py file to change the message string from 'hello world' to 'Hello World!'.

  2. Reload the test URL in your browser and observe the new string.

You will notice that your new code is loaded dynamically, without your having restart the sam local process.

Step 3: Package the Application

After testing your application locally, you use the Amazon SAM CLI to create a deployment package and a packaged Amazon SAM template.

Note

In the following steps, you create a .zip file for the contents of the hello_world/ directory, which contains the application code. This .zip file is the deployment package for your serverless application. For more information, see Creating a Deployment Package (Python) in the Amazon Lambda Developer Guide.

To create a Lambda deployment package
  1. Add a Metadata section to your Amazon SAM template file providing the required application information. For more information about the Metadata section of Amazon SAM templates, see Amazon SAM Template Metdata Section Properties in Amazon Serverless Application Model Developer Guide.

    Here is an example Metadata section:

    Metadata: AWS::ServerlessRepo::Application: Name: my-app Description: hello world Author: user1 SpdxLicenseId: Apache-2.0 LicenseUrl: LICENSE.txt ReadmeUrl: README.md Labels: ['tests'] HomePageUrl: https://github.com/user1/my-app-project SemanticVersion: 0.0.1 SourceCodeUrl: https://github.com/user1/my-app-project

    The LicenseUrl and ReadmeUrl properties can either be references to local files (as in the example above), or they can be links to Amazon S3 buckets that already host these artifacts.

  2. Create an S3 bucket in the location where you want to save the packaged code. If you want to use an existing S3 bucket, skip this step.

    sam-app> aws s3 mb s3://bucketname
  3. Create the Lambda function deployment package by running the following package Amazon SAM CLI command.

    sam-app> sam package \ --template-file template.yaml \ --output-template-file packaged.yaml \ --s3-bucket bucketname

    The command does the following:

    • Zips the contents of the aws-sam/hello_world/ directory and uploads it to Amazon S3.

    • Uploads the deployment package, README file, and LICENSE file to the Amazon S3 bucket specified by the --s3-bucket option.

    • Outputs a new template file, called packaged.yaml, which you use in the next step to publish the application to Amazon Serverless Application Repository. The packaged.yaml template file is similar to the original template file (template.yaml), but has a key difference—the CodeUri, LicenseUrl, and ReadmeUrl properties point to the Amazon S3 bucket and objects that contains the respective artifacts. The following snippet from an example packaged.yaml template file shows the CodeUri property:

      HelloWorldFunction: Type: AWS::Serverless::Function # For more information about function resources, see https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction Properties: CodeUri: s3://bucketname/fbd77a3647a4f47a352fcObjectGUID ...

Step 4: Publish the Application

Now that you've created the deployment package, you use it to publish the application to Amazon Serverless Application Repository.

To publish the serverless application to the Amazon Serverless Application Repository
  • Execute the following command to publish the new application in Amazon Serverless Application Repository with the first version created as 0.0.1.

    sam-app> sam publish \ --template packaged.yaml \ --region us-east-1
Note

The application will be created as private by default. You must share the application before other Amazon accounts will be allowed to view and deploy your application. See Next Steps below for more details about sharing your application.

Next Steps

Now that you have published your sample application, following are a few things you might want to do with it.

  • View Your Application in Amazon Serverless Application Repository – The output of the sam publish command will include a link to the Amazon Serverless Application Repository directly to the detail page of your application. You can also go to the Amazon Serverless Application Repository landing page and search for your application.

  • Share Your Application – Because your application is set to private by default, it is not visible to other Amazon Accounts. In order to share your application with others, you must either make it public or grant permission to a specific list of Amazon Accounts. For information on sharing your application using the Amazon CLI see Amazon Serverless Application Repository Application Policy Examples. For information on sharing your application using the console see Sharing an Application.

More Information

For more information about the Metadata section of Amazon SAM templates, sam package and sam publish commands of Amazon SAM CLI, see Publishing Applications Using Amazon SAM CLI in the Amazon Serverless Application Model Developer Guide.