Quick Start: Publishing Applications

This guide walks you through the steps to download, build, test and publish an example serverless application to the AWS Serverless Application Repository using AWS 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 AWS resources in the AWS Cloud.

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

4. Publish. Publish the application to the AWS Serverless Application Repository using sam publish. At the conclusion of this step, you're able to view your application in AWS Serverless Application Repository and deploy it to the AWS Cloud using AWS 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, AWS Lambda executes the function, which simply returns a hello world message.

The application has the following components:

• An AWS SAM template that defines two AWS 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:

• You must have an AWS account with an IAM user that has administrator permissions. See Set Up an AWS Account.

• You must have the AWS SAM CLI (command line interface) installed. See Installing the AWS SAM CLI.

• You must have version 1.16.77 or later of the AWS CLI installed. See Installing the AWS Command Line Interface.

Step 1: Initialize the Application

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

To initialize the application

1. Run the following command at an AWS 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 AWS 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. AWS 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 AWS 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 AWS SAM CLI to create a deployment package and a packaged AWS 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 AWS Lambda Developer Guide.

To create a Lambda deployment package

1. Add a Metadata section to your AWS SAM template file providing the required application information. For more information about the Metadata section of AWS SAM templates, see AWS SAM Template Metdata Section Properties in AWS 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 AWS 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 AWS 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 AWS Serverless Application Repository.

To publish the serverless application to the AWS Serverless Application Repository

• Execute the following command to publish the new application in AWS 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 AWS 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 AWS Serverless Application Repository – The output of the sam publish command will include a link to the AWS Serverless Application Repository directly to the detail page of your application. You can also go to the AWS 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 AWS Accounts. In order to share your application with others, you must either make it public or grant permission to a specific list of AWS Accounts. For information on sharing your application using the AWS CLI see AWS 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 AWS SAM templates, sam package and sam publish commands of AWS SAM CLI, see Publishing Applications Using AWS SAM CLI in the AWS Serverless Application Model Developer Guide.