Serverless Microstrate Plugin

A Serverless Framework plugin that enables deployment of serverless applications to the Microstrate platform.

Table of Contents

• Features
• Installation
• Setting Up Credentials
• Configuration
• Resources
• Commands
• Examples
• Migration from AWS

Features

• Native Microstrate Support: Deploy functions, KV stores, object storage, streams, and gateways to Microstrate
• AWS Migration: Easily migrate existing AWS projects to Microstrate
• Multiple Resource Types: Support for various Microstrate resources including:
  • Functions (compute)
  • KV Buckets (key-value storage)
  • Object Store Buckets
  • Streams (event streaming)
  • Gateways (API management)
• Gateway Mappings: Configure HTTP endpoints with rate limiting and traffic distribution

Installation

npm install --save-dev serverless-microstrate

Or if you're using Yarn:

yarn add --dev serverless-microstrate

Setting Up Credentials

1. Obtain Microstrate API Key

First, you'll need to obtain an API key from Microstrate. Visit the Microstrate Console to generate your API key.

2. Configure Credentials

Export Environment Variable (Recommended)

Set the MICROSTRATE_API_KEY environment variable:

export MICROSTRATE_API_KEY=your-api-key-here

serverless.yml Configuration

Add credentials directly to your serverless.yml:

provider:
name: microstratecredentials: ${env:MICROSTRATE_API_KEY}

3. Custom API URL (Optional)

If you're using a custom Microstrate deployment, you can specify the API URL:

export MICROSTRATE_URL=https://api.your-deployment.com

Configuration

Create a serverless.yml file in your project root:

service: my-microstrate-serviceplugins:
- serverless-microstratepackage:
individually: trueprovider:
name: microstrateregion: eu-west-2runtime: nodejs20.xarchitecture: arm64stage: ${opt:stage, 'dev'}memorySize: 1024timeout: 60credentials: ${env:MICROSTRATE_API_KEY}environment:
SERVICE: ${self:service}STAGE: ${self:provider.stage}functions:
hello:
handler: handler.hellodescription: Hello World functionmemorySize: 128timeout: 3environment:
FUNCTION_NAME: hellogateway:
- path: /api/hellomethod: postis_public: truelimit:
request: 100time: 1000resources:
Description: ${self:service} service infrastructureResources:
# KV StorageUserStore:
type: microstrate::kv::bucketdeletion_policy: retainproperties:
bucket: UserStoredescription: Store for user dataindexing:
mappings:
- field: userIdfield_type: text
- field: emailfield_type: text
- field: createdAtfield_type: number# Object StorageFileStorage:
type: microstrate::objectstore::bucketdeletion_policy: retainproperties:
bucket: FileStoragedescription: Storage for user filesmetadata:
purpose: user-uploads# Event StreamEventStream:
type: microstrate::streamdeletion_policy: retainproperties:
name: EventStreamdescription: Application event streamsubjects:
- user.>
- order.>max_consumers: 10max_msgs: 10000storage: filenum_replicas: 2# API GatewayPublicAPI:
type: microstrate::gatewaydeletion_policy: retainproperties:
name: PublicAPIdescription: Public API Gatewayactive: truelimit:
request: 1000time: 60

Resources

Functions

Functions are the compute units in Microstrate:

functions:
processOrder:
handler: orders.processmemorySize: 512timeout: 30environment:
QUEUE_URL: ${env:QUEUE_URL}gateway:
- path: /orders/processmethod: posttimeout: 120

KV Buckets

Key-value storage with indexing capabilities:

resources:
Resources:
OrdersDB:
type: microstrate::kv::bucketproperties:
bucket: orders-dbttl: 86400# 24 hoursindexing:
mappings:
- field: orderIdfield_type: text
- field: customerIdfield_type: text
- field: statusfield_type: text
- field: totalfield_type: number

Object Store Buckets

Object storage for files and large data:

resources:
Resources:
MediaBucket:
type: microstrate::objectstore::bucketproperties:
bucket: media-filescompression: truemax_bytes: 10485760# 10MBmetadata:
content-type: media

Streams

Event streaming for real-time data:

resources:
Resources:
ActivityStream:
type: microstrate::streamproperties:
name: activity-streamsubjects:
- user.login
- user.logout
- user.action.*max_msgs_per_subject: 1000retention: limitsstorage: file

Gateways

API gateway for managing HTTP endpoints:

resources:
Resources:
APIGateway:
type: microstrate::gatewayproperties:
name: api-gatewayactive: truelimit:
request: 5000time: 60timeout: 30

Commands

Deploy

Deploy your service to Microstrate:

serverless deploy

Deploy to a specific stage:

serverless deploy --stage production

Remove

Remove your service from Microstrate:

serverless remove

Remove from a specific stage:

serverless remove --stage production

Migrate

Migrate an existing AWS Serverless configuration to Microstrate:

serverless migrate

This command will:

1. Create a backup of your current serverless.yml
2. Convert AWS resources to Microstrate equivalents
3. Update function configurations
4. Migrate DynamoDB tables to KV buckets
5. Convert S3 buckets to Object Store buckets

Local Development

For local development and testing:

# Set debug mode for verbose outputexport DEBUG=TRUE
# Deploy with debug information
serverless deploy

Examples

Basic HTTP API

service: my-apiplugins:
- serverless-microstrateprovider:
name: microstrateruntime: nodejs20.xstage: ${opt:stage, 'dev'}credentials: ${env:MICROSTRATE_API_KEY}functions:
getUser:
handler: users.getgateway:
- path: /users/{id}method: getis_public: truecreateUser:
handler: users.creategateway:
- path: /usersmethod: postis_public: falselimit:
request: 10time: 60

Event-Driven Architecture

service: event-processorplugins:
- serverless-microstrateprovider:
name: microstrateruntime: nodejs20.xcredentials: ${env:MICROSTRATE_API_KEY}functions:
orderProcessor:
handler: processors.ordersenvironment:
STREAM_NAME: OrderStreamnotificationSender:
handler: processors.notificationsenvironment:
STREAM_NAME: OrderStreamresources:
Resources:
OrderStream:
type: microstrate::streamproperties:
name: OrderStreamsubjects:
- order.created
- order.updated
- order.completedmax_msgs: 100000storage: file

Microservice with Storage

service: user-serviceplugins:
- serverless-microstrateprovider:
name: microstrateruntime: nodejs20.xcredentials: ${env:MICROSTRATE_API_KEY}functions:
userAPI:
handler: api.handlergateway:
- path: /users/{proxy+}method: anyis_public: trueresources:
Resources:
UserData:
type: microstrate::kv::bucketproperties:
bucket: user-dataindexing:
mappings:
- field: emailfield_type: text
- field: usernamefield_type: textUserProfiles:
type: microstrate::objectstore::bucketproperties:
bucket: user-profilesmax_bytes: 5242880# 5MB

Migration from AWS

If you have an existing AWS Serverless project, the migration process is straightforward:

1. Install the plugin:

   npm install --save-dev serverless-microstrate

2. Run the migration command:

   serverless migrate

3. Review the migrated configuration:

   • Check the generated serverless.yml
   • Your original file is backed up as serverless.yml-backup.<timestamp>

4. Update environment variables:

   • Replace AWS credentials with Microstrate API key
   • Update any AWS-specific environment variables

5. Deploy to Microstrate:

   serverless deploy

Migration Mappings

AWS Resource	Microstrate Resource
AWS::Lambda::Function	microstrate::function
AWS::DynamoDB::Table	microstrate::kv::bucket
AWS::S3::Bucket	microstrate::objectstore::bucket
HTTP/API Gateway Events	microstrate::gateway + mappings

Post-Migration Checklist

• Update IAM roles/policies to Microstrate equivalents
• Modify AWS SDK calls to Microstrate APIs
• Update CloudWatch logging to Microstrate logging
• Adjust timeout and memory settings if needed
• Test all endpoints and functions
• Update CI/CD pipelines

Troubleshooting

Debug Mode

Enable debug mode for detailed logging:

export DEBUG=TRUE
serverless deploy

Common Issues

1. Authentication Error

   • Ensure MICROSTRATE_API_KEY is set correctly

2. Deployment Failures

   • Check resource names for conflicts
   • Verify memory and timeout limits
   • Ensure handler paths are correct

3. Migration Issues

   • Some AWS-specific features may not have direct equivalents
   • Review migration warnings in the output
   • Manually adjust configurations as needed

Support

• Documentation: https://docs.microstrate.io
• Issues: GitHub Issues