ServerlessInsight

Full life cycle cross-provider serverless application management for your fast-growing business

Website • Documentation • Examples • 中文文档

</div>

ServerlessInsight is a powerful serverless framework for managing serverless applications across multiple cloud providers. It provides a unified interface to deploy, manage, and debug serverless functions and resources using Infrastructure as Code (IaC) principles.

Whether you're building on AWS, Alibaba Cloud, Huawei Cloud, or other providers, ServerlessInsight simplifies your development workflow with:

Multi-cloud support - Work with multiple cloud providers using a single tool
Infrastructure as Code - Define your serverless infrastructure in YAML
Local development - Test your functions locally before deploying
Type-safe templates - Validate your configurations before deployment

✨ Features

🌍 Multi-Cloud Provider Support - Deploy to Alibaba Cloud, Huawei Cloud, and more
📦 Unified Configuration - Single YAML format for all providers
🚀 Quick Deployment - Deploy serverless applications with a single command
🔍 Template Validation - Validate your IaC templates before deployment
🏠 Local Testing - Run and debug serverless functions locally
🔄 Template Generation - Generate provider-specific IaC templates
🌐 API Gateway Integration - Configure HTTP endpoints for your functions
🌐 Custom Domain Binding - Automatic domain binding with DNS verification for OSS and API Gateway
💾 Resource Management - Manage storage, databases, and other cloud resources
🔐 Security First - Built-in validation and security best practices
📊 Comprehensive Logging - Debug and monitor your applications

☁️ Supported Providers

ServerlessInsight supports the following cloud providers:

| Provider | Functions | API Gateway | Storage | Databases | Status | | ----------------- | ---------------- | -------------- | -------------- | ---------------- | ------- | | Alibaba Cloud | ✅ FC3 | ✅ API Gateway | ✅ OSS | ✅ RDS, OTS, ESS | Stable | | Tencent Cloud | ✅ SCF | 🚧 Coming Soon | ✅ COS | ✅ TDSQL-C | Stable | | Huawei Cloud | ✅ FunctionGraph | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon | Beta | | AWS | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned | | Azure | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned | | Google Cloud | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |

🚀 Getting Started

Prerequisites

Node.js 16.x or higher
Cloud provider credentials (Alibaba Cloud AccessKey, Huawei Cloud credentials, etc.)

Installation

Install ServerlessInsight globally using npm:

npm install -g @geek-fun/serverlessinsight

Verify the installation:

si --version

📚 Usage

# Validate your serverless configuration
si validate -f serverless.yml

# Generate deployment plan (see what will change)
si plan -f serverless.yml

# Deploy your serverless application
si deploy -f serverless.yml -s dev

# Run your application locally for debugging
si local -f serverless.yml -s local

# Show deployed resource information
si show -f serverless.yml

# Destroy the deployed stack
si destroy -f serverless.yml

💡 Examples

ServerlessInsight uses a simple YAML format to define your serverless infrastructure:

version: 0.0.1
provider:
  name: aliyun
  region: cn-hongkong

service: my-api-service

functions:
  hello_function:
    name: hello-world-fn
    code:
      runtime: nodejs18
      handler: index.handler
      path: ./src
    memory: 512
    timeout: 10
    environment:
      NODE_ENV: production

events:
  api_gateway:
    type: API_GATEWAY
    name: my-api-gateway
    triggers:
      - method: GET
        path: /api/hello
        backend: ${functions.hello_function}

For more examples, check out the samples directory:

API Gateway Example - Deploy functions with HTTP endpoints
Storage Example - Configure OSS buckets
Custom Domain Example - Configure OSS static website with custom domain binding
Database Example - Set up RDS databases
Table Store Example - Configure OTS table storage
Elasticsearch Example - Deploy Elasticsearch Serverless
GPU Functions Example - Deploy GPU-enabled functions
Huawei Cloud Example - Deploy to Huawei Cloud FunctionGraph

🔧 Local Development

# Clone and setup
git clone https://github.com/geek-fun/serverlessinsight.git
cd serverlessinsight
npm install

# Build and link for development
npm run build
npm link

# Run local development server
si local -f serverless.yml -s local

# Run tests
npm test

# Lint code
npm run lint:check

Local Testing with Buckets

When running the local development server, you can test bucket operations by accessing files through the LocalStack server:

# List all files in a bucket
curl http://localhost:4567/si_buckets/<bucket_key>/

# Access a specific file from a bucket
curl http://localhost:4567/si_buckets/<bucket_key>/path/to/file.html

# List files in a subdirectory
curl http://localhost:4567/si_buckets/<bucket_key>/subdir/

The bucket handler serves files from the directory specified in your bucket's website.code configuration.

Architecture

ServerlessInsight follows a functional client architecture that cleanly separates cloud provider SDKs from business logic:

Layered Design

┌─────────────────────────────────────────┐
│   Resource / Planner / Executor Layer   │  ← Provider-agnostic business logic
│   (Pure functions, no SDK imports)       │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         Functional Client Layer          │  ← Encapsulated SDK operations
│   (aliyunClient.ts, tencentClient.ts)   │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│      Cloud Provider SDKs                 │  ← @alicloud/*, tencentcloud-*
└─────────────────────────────────────────┘

Key Principles

Functional & Pure: All business logic uses pure functions with immutable data
SDK Encapsulation: Provider SDKs are accessed ONLY through client modules
Operation Functions: Clients expose high-level operation functions (e.g., createFunction, getFunction)
No Classes: Prefer type over interface, and functional patterns over classes
Minimal Side Effects: File I/O and other side effects are isolated at boundaries

Client Pattern Example

// ✅ Client exposes operation functions, not raw SDKs
export type AliyunClient = {
  fc3: {
    createFunction: (config: Fc3FunctionConfig, codeBase64: string) => Promise<void>;
    getFunction: (functionName: string) => Promise<Fc3FunctionInfo | null>;
    // ... other operations
  };
  // ... other services
};

// ✅ Resource layer uses clean client API
const client = createAliyunClient(context);
const codeBase64 = readFileAsBase64(codePath);
await client.fc3.createFunction(config, codeBase64);

This architecture enables:

Better Testing: Mock client operations instead of SDKs
Maintainability: Provider changes isolated to client layer
Type Safety: Strong typing throughout the stack
Code Reuse: Shared client operations across resources

🌐 Custom Domain Binding

ServerlessInsight provides automatic custom domain binding for OSS buckets and API Gateway with built-in DNS verification.

OSS Custom Domain Binding

When you configure a custom domain for an OSS bucket (static website hosting), ServerlessInsight automatically:

Binds the domain to your OSS bucket
Creates DNS CNAME records pointing to the correct OSS endpoint
Handles domain ownership verification via DNS TXT records when required by the cloud provider
Manages retry logic with DNS propagation polling for reliable binding

buckets:
  my_website:
    name: my-website-bucket
    security:
      acl: PUBLIC_READ
    website:
      code: ./dist
      domain: www.example.com # Custom domain binding
      index: index.html
      error_page: 404.html

Domain Ownership Verification Flow

When binding a custom domain that requires ownership verification:

┌─────────────────────────────────────────────────────────────────┐
│                    OSS Custom Domain Binding                     │
└─────────────────────

Serverlessinsight

Install / Use

README