Adding serverless functionality to existing applications

The AWS Serverless Application Repository can provide new functionality to your existing applications, without needing to manage servers.

Often when you need to add new functionality to existing applications, it can involve deploying entire new versions, potentially requiring new servers or infrastructure. But in many cases you could use a serverless approach to add new features without needing to change an existing server-based application. In this blog post, I’ll show how to add file upload functionality to an existing site, with the new functionality being a component deployed via the AWS Serverless Application Repository (SAR).

There are many use-cases for business applications needing users to upload files, such as uploading receipts, images or PDF files, and it’s a common feature of websites. Many server-bound applications use a web-server as a proxy, passing the files through the server as a stepping stone to the final file storage. Typically this adds extra load on the web server but instead you can communicate directly to S3, and we can handle this functionality using a small serverless application to augment the existing website.

In this blog post, I am using the SAR to demonstrate how you can share self-contained units of functionality. With a SAR application, you can deliver and share serverless workloads across your teams to embed into your other applications. It’s a powerful way to create serverless components that can be used anywhere else in your applications.

Deploying the serverless application

The best way to understand the SAR is to deploy an application. I’ve built a sample application to demonstrate the process — the “S3 uploader application” — which creates all the resources needed to allow a website to upload a JPG file directly to an S3 bucket (with no web server as an intermediary).

To deploy this application:

1. Sign into your AWS Console.

2. Go to the Serverless Application Repository in the Services dropdown.

3. In the search bar, enter “Serverless-S3-Uploader” and you will see the application matched below.

4. Click the application’s title to open its detail page. Here you can see the application’s permissions, license and underlying CloudFormation template. In the case of public applications in the SAR, you can also browse the source code.

5. You can optionally update the Application Name in the Application settings card, otherwise click “Deploy” when you are ready. While the SAR is deploying the resources used by the application, you will see an informational banner across the top of the screen. Once the resources have been fully deployed, after a couple of minutes you will see the page below.

Testing the deployed application

The application has now been deployed in your AWS account — in this case, it provisions an upload bucket in Amazon S3, an Amazon API Gateway endpoint, an AWS Lambda function and the required permissions for these to interact.

To test the S3 uploader application:

1. First, click “View CloudFormation Stack” at the top of the Resources card. Now choose the Resources tab and click the link next to the ServerlessRestApi entry:

2. This opens the API Gateway console. Select Dashboard under the API on the left menu and copy the API’s URL:

3. Open this JSFiddle — this represents our existing web application. In the JavaScript panel, on line 6 you will see the constant API_ENDPOINT. Paste your API endpoint here, ensuring the string is wrapped with single quotes:

4. Click “Run” in the top menu.

5. In the output panel, click “Choose File” and select any JPG file from your computer.

6. Click the “Upload image” button and wait for the upload confirmation message.

7. Back in AWS Console, go to Amazon S3 in the services dropdown and you will see the SAR deployment created a bucket for this application.

8. Click on the bucket to view its contents. You will see the uploaded image as a new object.

There are two applications in this example — the front-end application running in JSFiddle, and the backend service deployed by the SAR, which interact as shown below:

Any static website, single-page application or traditional content management system could implement this endpoint as a file-uploading solution, instead of developing new functionality in a server-based backend. Being serverless, it has the benefit of scaling automatically, which makes it a perfect fit for high-traffic websites or sites with spiky or unpredictable demand.

Inside the S3 uploader SAR application

Download or clone the source code for this application to your local machine and open the directory in your favorite editor.

The main files in the repository include:

• README.md — provides the instructions for the application.
• package.json — lists the NPM packages are used by the application (only the AWS SDK in this case).
• app.js — the code for the Lambda function, which generates the Amazon S3 upload URL.
• template.yaml — the AWS Serverless Application Model (SAM) template defining the resources used by the application.
• packaged.yaml — the package used by SAR to launch and configure the application.

The template.yaml file is an important part of the repository, describing the AWS resources that will be deployed, together with the permissions needed. SAM will transform this YAML into a full CloudFormation template as part of the deployment process, but this initial format is shorter and easier to write, using pre-canned IAM template policies to simplify the boilerplate code required.

The packaged.yaml file is needed by the SAR. It’s created from the template.yaml input, but there’s a key difference — It contains the CodeUri, LicenseUrl and ReadmeUrl properties that point to an Amazon S3 bucket and objects containing the necessary artifacts. The SAR configuration is really a lightweight wrapper around a typical SAM template, and these properties are the difference between a SAM application and a SAR application.

Publishing and sharing your own applications

Once you know the differences between the template.yaml and packaged.yaml files, publishing is fairly straight-forward.

To publish an application:

1. Create a SAM application with a valid SAM template.yaml file.

2. Package the application using the SAM CLI using the command:

sam package — output-template-file packaged.yaml — s3-bucket my-unique-bucket-name).

3. Publish your application through the SAR console or SAM CLI, and configure your sharing options.

Published applications are initially private, so they can only be discovered and launched from the account that created the package. If you want to share your code with others, there are two sharing modes:

• Privately shareable: you can select which AWS account number(s) can discover and deploy the application in their SAR console.
• Public: make the application visible to everyone so anyone with an AWS account can deploy your application.

Public applications require a version number, a license and a listed source code repository, and are suited to open source or public domain works. Public apps can also be deployed in any AWS region, and SAR automatically copies the code repository from your source bucket to an Amazon S3 bucket in the target region.

Privately shared applications are ideal for teams, companies and teams working in collaboration. This mode allows you to develop components to share across your organizations and its products, making it easy for other groups to consume your serverless applications.

Conclusion

In this blog post I showed how to deploy applications from the Serverless Application Repository. In the example, we deployed an application that enables public file uploading of JPGs to a private Amazon S3 bucket, and saw how to integrate the API endpoint with an existing website application.

The SAR makes it easy to deploy standardized, versioned components to other AWS accounts in your teams, or publish code to the world as public applications. SAR applications can be small services or components that can be used in other serverless applications, or integrated into existing server-based workloads.