Mohammed Ismaeel for AWS Community Builders

Posted on Nov 10 • Edited on Nov 13

How to Migrate from Serverless Framework to AWS SAM

#aws #serverless #cloudnative #tutorial

Abstract: Migrating from the Serverless Framework to AWS Serverless Application Model (SAM) can streamline your deployment processes by leveraging AWS-native tooling. This article provides a comprehensive guide on how to transition your serverless applications, highlighting the key differences between the two frameworks and offering step-by-step instructions to ensure a smooth migration.

Introduction

The Serverless Framework is a popular tool that allows developers to build and deploy serverless applications across multiple cloud providers. AWS Serverless Application Model (SAM) is an AWS-native framework specifically designed to simplify the development and deployment of serverless applications on AWS.

While the Serverless Framework offers multi-cloud capabilities, some organisations may prefer to migrate to AWS SAM to take advantage of deeper AWS service integrations, improved local testing capabilities, and streamlined deployment processes.

This article aims to guide you through the migration process from the Serverless Framework to AWS SAM, ensuring that your serverless applications continue to function after the transition.

Understanding Serverless Framework and AWS SAM

Serverless Framework
The Serverless Framework is a CLI tool that facilitates the development and deployment of serverless applications. It supports multiple cloud providers, including AWS, Azure, Google Cloud, and more.

Key Features:

Multi-cloud support
Plugin ecosystem for extended functionality
YAML-based configuration (serverless.yml)
Simplifies packaging and deployment processes

AWS SAM
AWS SAM is an open-source framework that extends AWS CloudFormation to provide a simplified way of defining and deploying serverless applications on AWS.

Key Features:

AWS-specific optimisations
YAML or JSON templates (template.yaml or template.yml)
Local debugging and testing with SAM CLI
Integration with AWS services and CI/CD pipelines

Reasons to Migrate to AWS SAM

AWS Native Tooling: Deep integration with AWS services and features.
Local Testing: Enhanced local testing capabilities using the SAM CLI.
Simplified Permissions: Easier management of IAM roles and policies.
Resource Connectors: Simplify resource permission configurations between serverless functions and other AWS resources.
Cost Efficiency: Potentially lower overhead by eliminating the need for third-party plugins. Active Development: Continuous updates and support from AWS.

Pre-Migration Considerations

Before starting the migration process:

Backup Your Codebase: Ensure that your existing code and configuration files are backed up.
Understand Feature Parity: Some features in the Serverless Framework may not have direct equivalents in AWS SAM.
Review Dependencies: Identify any plugins or custom resources that need to be addressed.
Update AWS CLI and SAM CLI: Ensure you have the latest versions installed.

Step-by-Step Migration Guide

1. Install AWS SAM CLI

Ensure that the AWS SAM CLI is installed and configured on your machine.

Installation Instructions:

Visit the AWS SAM CLI Installation Guide for platform-specific instructions.

2. Analyze Your Serverless Framework Configuration

Review your serverless.yml file to understand:

Functions and their triggers
Resources (e.g., DynamoDB tables, S3 buckets)
Environment variables
IAM roles and permissions
Plugins and custom settings

3. Create an AWS SAM Template

Create a new template.yaml file in the root directory of your project.

yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >-
  Your Serverless Application migrated to AWS SAM

Globals:
  Function:
    Runtime: nodejs14.x
    Timeout: 10
    MemorySize: 128

Resources:
  # Resources will be defined here

4. Refactor Function Definitions

Map each function from serverless.yml to AWS SAM format.

Serverless Framework Example:
yaml

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handlers/helloWorld.handler
      Runtime: nodejs14.x
      Events:
        HelloWorldApi:
          Type: Api
          Properties:
            Path: /hello
            Method: get

5. Update Resource Definitions

Translate custom resources defined in serverless.yml to AWS SAM.

Serverless Framework Example:
yaml

resources:
  Resources:
    MyTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: my-table
        AttributeDefinitions:
          - AttributeName: id
            AttributeType: S
        KeySchema:
          - AttributeName: id
            KeyType: HASH
        BillingMode: PAY_PER_REQUEST

AWS SAM Equivalent:
yaml

Resources:
  MyTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: my-table
      AttributeDefinitions:
        - AttributeName: id
          AttributeType: S
      KeySchema:
        - AttributeName: id
          KeyType: HASH
      BillingMode: PAY_PER_REQUEST

6. Simplify Connections with Resource Connectors

Use AWS SAM resource connectors to define the permissions and environment variables needed for your Lambda functions to access other resources.

Connecting a Lambda Function to a DynamoDB Table:

Instead of manually specifying IAM policies and environment variables, you can use the Connectors property.

yaml

Resources:
  MyTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: my-table
      AttributeDefinitions:
        - AttributeName: id
          AttributeType: S
      KeySchema:
        - AttributeName: id
          KeyType: HASH
      BillingMode: PAY_PER_REQUEST

  GetItemFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handlers/getItem.handler
      Runtime: nodejs14.x
      Connectors:
        MyConn:
          Properties:
            Destination:
              Id: MyTable
            Permissions:
              - Read

Explanation:

The Connectors property automatically sets up the necessary IAM policies and environment variables (TABLE_NAME) for the GetItemFunction to interact with MyTable.
This reduces manual configuration and potential errors.

7. Modify Environment Variables and IAM Roles

Define environment variables and IAM roles within your function properties.

Environment Variables:

Properties:
  Environment:
    Variables:
      TABLE_NAME: my-table

IAM Roles:

AWS SAM can automatically generate roles, or you can define them explicitly.

Properties:
  Policies:
    - DynamoDBReadPolicy:
        TableName: my-table

8. Test Locally with SAM CLI

AWS SAM allows local testing of Lambda functions and API Gateway.

Start the API Locally:


sam local start-api
sam local invoke HelloWorldFunction

9. Deploy Your Application

Use the sam deploy command to package and deploy your application.

Guided Deployment:

Copy code
sam deploy --guided

Specify Parameters: Provide stack name, AWS region, and permissions preferences.

10. Validate the Migration

Test Endpoints: Ensure all APIs and functions are working as expected.
Check Resources: Verify that all resources have been created properly.
Monitor Logs: Use AWS CloudWatch to monitor function logs for errors.
Best Practices
Use Parameters and Mappings: Make your templates reusable across environments.
Organize Templates: Break down large templates into nested stacks if necessary.
Version Control: Keep your SAM templates under version control.
Automate Deployments: Integrate SAM deployment commands into your CI/CD pipeline.

Common Pitfalls and How to Avoid Them

Unsupported Plugins: Serverless Framework plugins may not have direct equivalents in AWS SAM. Identify critical plugins and find AWS-native solutions.
Naming Conflicts: Be cautious of resource naming to avoid conflicts during deployment.
Environment Differences: Ensure that environment variables and configurations match between the two frameworks.
IAM Permissions: Double-check IAM policies to ensure functions have the necessary permissions.
Resource Connector Limitations: Be aware that resource connectors support specific resource types. Consult the AWS SAM documentation for supported connections.

Conclusion

Migrating from the Serverless Framework to AWS SAM allows you to leverage AWS's native tooling and services more effectively. While the migration requires careful planning and refactoring of your configuration files, the benefits of improved integration, testing capabilities, and streamlined deployments can significantly enhance your serverless application's performance and maintainability.

References

DEV Community