py-serverless-kit

Write your Python functions once. Deploy them to any of 10 clouds, or to your own machine, by changing one line of YAML.

py-serverless-kit (CLI: pskit) is a Serverless-Framework-style toolkit built on Terraform. Your handlers use one small, provider-neutral API (Event, Context, Response). A pskit.yml file says which cloud they run on and what triggers them: HTTP, schedules, queues, storage, topics. The same file can also define workflows in the style of Step Functions. pskit deploy generates Terraform for the chosen cloud, applies it, and builds an HTML dashboard of everything you deployed.

# app/handlers.py - identical on AWS, Azure, GCP, Alibaba, Oracle, IBM, DigitalOcean, Tencent, Huawei, Cloudflare, and on premises
from py_serverless_kit import Event, Context, NotFound

def get_order(event: Event, ctx: Context):
    order = ORDERS.get(event.http.path_params["id"])
    if order is None:
        raise NotFound("no such order")      # -> HTTP 404 JSON on every cloud
    return order                              # -> HTTP 200 JSON

# pskit.yml
service: orders
provider:
  name: aws          # <- change to gcp, azure, onprem, ... and redeploy. That's the migration.
  region: us-east-1
functions:
  get-order:
    handler: app.handlers.get_order
    events:
      - http: GET /orders/{id}

pskit deploy                      # terraform apply on AWS
pskit deploy --provider gcp       # same code, Google Cloud Functions
pskit dashboard --open            # every function, trigger, URL and resource id
pskit studio --open               # or build all of the above in a web UI instead of YAML

Why

Teams that build on AWS Lambda and Step Functions end up with code full of API Gateway event parsing, SQS record loops and hand-written ASL. When the business needs another cloud, every function has to be rewritten. py-serverless-kit fixes this at both layers:

Features

• 10 clouds and an on-premises host: AWS Lambda, Azure Functions, Google Cloud Functions (gen2), Alibaba Function Compute, Oracle Functions, IBM Code Engine, DigitalOcean Functions, Tencent SCF, Huawei FunctionGraph, Cloudflare Workers, plus a process on your own machine or a remote server (onprem: local, SSH/SCP of one archive with a .pem, or Docker — the image is built locally, Docker is installed on the server when it is missing, and deploy waits until the host is healthy — or a bundled CPython when the server has no Python).
• Python, JavaScript or TypeScript: set runtime: nodejs20 and write handlers in JS/TS with the same Event/Context API; pskit compiles TypeScript and bundles npm dependencies (docs/nodejs.md).
• Triggers: HTTP (path params, CORS, auth), schedules (rate/cron, translated into each cloud's cron dialect), queues, object storage, pub/sub topics, and direct function-to-function invoke().
• Workflows: task / choice / wait / pass / parallel / map / succeed / fail with retry and catch. Native on AWS and GCP; an embedded engine on the other clouds; runnable locally with pskit workflow run. Every run returns an execution_id; pskit workflow start|executions|status|cancel and the dashboard list, follow and cancel runs (on premises, Step Functions, Cloud Workflows).
• Resources: a resources: section for buckets, queues, topics, databases, caches or any service, created by pskit or attached as external. Handlers read them with resource("name") on every cloud. On premises, queues can live in Redis and storage in MinIO / any S3-compatible store.
• Terraform underneath: real, reviewable main.tf.json, any backend (S3, GCS, azurerm, ...), works with OpenTofu. Escape hatches: terraform.extra, ${tf:...} references, per-function options.
• Config that scales: extends:, per-provider providers: blocks, per-stage stages: blocks, and ${env:}, ${opt:}, ${self:}, ${file()} variables.
• Local dev: pskit dev (hot-reloading HTTP server), pskit invoke with synthetic queue/storage/schedule events, and a LocalRunner for pytest.
• Studio: pskit studio builds the project in a web UI instead of YAML. It covers provider cards for all 11 targets, an AWS-console-style function wizard whose trigger list follows what the provider supports, a visual workflow builder, resources with an on-prem driver picker (every built-in driver plus custom classes) and Browse account pickers for existing queues and buckets. It also has a built-in code editor or full VS Code (code-server, pulled into Docker on demand) and deploy/invoke with live logs.
• Dashboard: a self-contained React page listing every deployment, function, trigger, endpoint, ARN/id, console link, workflow and resource. pskit dashboard --serve adds live on-prem logs and stats and workflow executions (start, follow, cancel). pskit logs -f tails an on-prem host from the terminal.
• Production details: deterministic artifacts (no redeploy when nothing changed), partial batch failures (BatchResult), structured JSON logs, consistent HTTP error mapping, stack traces hidden from clients, a stdlib-only runtime (no extra dependencies inside your function), and hooks (before_deploy, ...).

Supported providers

Run pskit providers for the live matrix. If a config uses a trigger the target cloud can't support, pskit validate fails with a clear message instead of deploying something half-working.

Maturity, honestly stated: the Terraform generated for every provider is checked with terraform validate against the real provider plugins (in CI, too). The stable providers cover the most surface area. beta and experimental providers follow vendor docs for event payloads that validate can't check, so try them on a non-production account first. See docs/providers.md for each provider's details and limits.

Install

pip install py-serverless-kit

You also need Terraform ≥ 1.5 (or OpenTofu) on your PATH, plus credentials for your cloud. See Getting started.

Quick start

pskit init my-api --provider aws --template full   # templates: http | events | workflow | full
cd my-api
pskit dev                                          # http://127.0.0.1:3000/hello
pskit invoke -f hello --path "/hello?name=Ada"
pskit workflow run order-pipeline -i '{"amount": 42}'
pskit deploy --stage dev
pskit info
pskit dashboard --open
pskit remove --stage dev

Move to another cloud

Change provider.name, or keep one file with per-cloud blocks:

provider:
  name: aws
  region: us-east-1
providers:              # applied only when that provider is selected
  gcp:   {region: europe-west1, options: {project: my-project}}
  azure: {region: westeurope, options: {subscription_id: "${env:ARM_SUBSCRIPTION_ID}"}}

pskit deploy --provider gcp
pskit deploy --provider azure --stage prod

Triggers at a glance

functions:
  api:
    handler: app.api.handle
    events:
      - http: {method: POST, path: /orders, cors: true}
      - http: GET /orders/{id}
  nightly:
    handler: app.jobs.nightly
    events:
      - schedule: {cron: "0 2 * * *", input: {report: daily}, timezone: Europe/Berlin}
  worker:
    handler: app.jobs.process
    timeout: 60
    events:
      - queue: {name: orders, batch_size: 10, dead_letter: orders-dlq}
  thumbnails:
    handler: app.media.on_upload
    events:
      - storage: {bucket: my-uploads-bucket, events: [created], suffix: .jpg}
  audit:
    handler: app.audit.on_event
    events:
      - topic: order-events

from py_serverless_kit import BatchResult, Event, Context

def process(event: Event, ctx: Context):
    result = BatchResult()               # retry only failed messages where the cloud supports it
    for record in event.records:
        try:
            handle(record.json())
        except Exception:
            result.fail(record)
    return result

Workflows (portable Step Functions)

workflows:
  order-pipeline:
    start_at: Validate
    states:
      Validate:
        type: task
        function: validate-order
        retry: [{errors: [TimeoutError], max_attempts: 3, backoff_rate: 2}]
        catch: [{errors: [ValueError], next: Rejected}]
        next: Route
      Route:
        type: choice
        choices: [{variable: "$.amount", gt: 1000, next: ManualReview}]
        default: Charge
      ManualReview: {type: wait, seconds: 3600, next: Charge}
      Charge: {type: task, function: charge-order, end: true}
      Rejected: {type: fail, error: OrderRejected}

The same definition becomes AWS Step Functions on AWS, Google Cloud Workflows on GCP, and an embedded orchestrator function on the other clouds. pskit workflow show order-pipeline --format asl prints the generated ASL.

How it works

 pskit.yml ──► config loader ──► provider validation ──► packager ──────────► artifact.zip
 (extends, providers:,          (capabilities,           (your code + stdlib-only
  stages:, ${vars})              limits, runtimes)        runtime + manifest + shim)
                                        │
                                        ▼
                              provider renderer ──► .pskit/<provider>-<stage>/main.tf.json
                                                              │ terraform init / apply
                                                              ▼
                                       deployment.json ──► dashboard/index.html

 At runtime:  cloud event ──► shim ──► runtime.adapters.<cloud> ──► Event ──► your handler
              your result ──► Response / raw value ──► adapter ──► native cloud response

More: docs/architecture.md.

Examples

Eighteen runnable examples live in examples/. They are tested in CI.

Documentation

Contributing & releasing

• Contributor guide: deploy_docs/CONTRIBUTING.md
• Quick PyPI release guide: deploy_docs/How_to_deploy.md
• Publishing to PyPI (step by step): deploy_docs/PUBLISHING_TO_PYPI.md
• Security policy: SECURITY.md

Author

Created and maintained by Asif Khan @ Kavion.ai.

Source code, issues and releases: https://github.com/ak9347128658/serverless_kit

License

MIT, see LICENSE.