Publishing serverless applications using the Amazon SAM CLI - Amazon Serverless Application Model
PrerequisitesPublishing a new applicationPublishing a new version of an existing applicationAdditional topics
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).

Publishing serverless applications using the Amazon SAM CLI

To make your Amazon SAM application available for others to find and deploy, you can use the Amazon SAM CLI to publish it to the Amazon Serverless Application Repository. To publish your application using the Amazon SAM CLI, you must define it using an Amazon SAM template. You also must have tested it locally or in the Amazon Cloud.

Follow the instructions in this topic to create a new application, create a new version of an existing application, or update the metadata of an existing application. (What you do depends on whether the application already exists in the Amazon Serverless Application Repository, and whether any application metadata is changing.) For more information about application metadata, see Amazon SAM template Metadata section properties.

Prerequisites

Before you publish an application to the Amazon Serverless Application Repository using the Amazon SAM CLI, you must have the following:

  • The Amazon SAM CLI installed. For more information, see Installing the Amazon SAM CLI. To determine whether the Amazon SAM CLI is installed, run the following command:

    sam --version

  • A valid Amazon SAM template.

  • Your application code and dependencies that the Amazon SAM template references.

  • A semantic version, required only to share your application publicly. This value can be as simple as 1.0.

  • A URL that points to your application's source code.

  • A README.md file. This file should describe how customers can use your application and how to configure it before deploying it in their own Amazon accounts.

  • A LICENSE.txt file, required only to share your application publicly.

  • If your application contains any nested applications, you must have already published them to the Amazon Serverless Application Repository.

  • A valid Amazon Simple Storage Service (Amazon S3) bucket policy that grants the service read permissions for artifacts that you upload to Amazon S3 when you package your application. To set up this policy, do the following:

    1. Open the Amazon S3 console at https://console.amazonaws.cn/s3/.

    2. Choose the name of the Amazon S3 bucket that you used to package your application.

    3. Choose Permissions.

    4. On the Permissions tab, under Bucket policy, choose Edit.

    5. On the Edit bucket policy page, paste the following policy statement into the Policy editor. In the policy statement, make sure to use your bucket name in the Resource element and your Amazon account ID in the Condition element. The expression in the Condition element ensures that Amazon Serverless Application Repository has permission to access only applications from the specified Amazon account. For more information about policy statements, see IAM JSON policy elements reference in the IAM User Guide.

      {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service":  "serverlessrepo.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::<your-bucket-name>/*",
            "Condition" : {
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                }
            }
        }
    ]
}

    6. Choose Save changes.

Publishing a new application

Step 1: Add a Metadata section to the Amazon SAM template

First, add a Metadata section to your Amazon SAM template. Provide the application information to be published to the Amazon Serverless Application Repository.

The following 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

Resources:
  HelloWorldFunction:
    Type: AWS::Lambda::Function
      Properties:
        ...
        CodeUri: source-code1
        ...

For more information about the Metadata section of the Amazon SAM template, see Amazon SAM template Metadata section properties.

Step 2: Package the application

Run the following Amazon SAM CLI command, which uploads the application's artifacts to Amazon S3 and outputs a new template file called packaged.yaml:

sam package --output-template-file packaged.yaml --s3-bucket <your-bucket-name>

You use the packaged.yaml template file in the next step to publish the application to the Amazon Serverless Application Repository. This file is similar to the original template file (template.yaml), but it has a key difference—the CodeUri, LicenseUrl, and ReadmeUrl properties point to the Amazon S3 bucket and objects that contain the respective artifacts.

The following snippet from an example packaged.yaml template file shows the CodeUri property:

MySampleFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: s3://bucketname/fbd77a3647a4f47a352fcObjectGUID

...

Step 3: Publish the application

To publish a private version of your Amazon SAM application to the Amazon Serverless Application Repository, run the following Amazon SAM CLI command:

sam publish --template packaged.yaml --region us-east-1

The output of the sam publish command includes a link to your application on the Amazon Serverless Application Repository. You can also go directly to the Amazon Serverless Application Repository landing page and search for your application.

Step 4: Share the application (optional)

By default, your application is set to private, so it isn't visible to other Amazon accounts. To share your application with others, you must either make it public or grant permission to a specific list of Amazon accounts.

For information about sharing your application using the Amazon CLI, see Amazon Serverless Application Repository Resource-Based Policy Examples in the Amazon Serverless Application Repository Developer Guide. For information on sharing your application using the Amazon Web Services Management Console, see Sharing an Application in the Amazon Serverless Application Repository Developer Guide.

Publishing a new version of an existing application

After you've published an application to the Amazon Serverless Application Repository, you might want to publish a new version of it. For example, you might have changed your Lambda function code or added a new component to your application architecture.

To update an application that you've previously published, publish the application again using the same process detailed previously. In the Metadata section of the Amazon SAM template file, provide the same application name that you originally published it with, but include a new SemanticVersion value.

For example, consider an application published with the name SampleApp and a SemanticVersion of 1.0.0. To update that application, the Amazon SAM template must have the application name SampleApp and a SemanticVersion of 1.0.1 (or anything other than 1.0.0).

Additional topics