Skip to content
§1

lambda2eks user guide

Lambda functions to EKS, handler unchanged.

lambda2eks reads a SAM or CloudFormation template, or your deployed functions, and writes everything each function needs to run on Kubernetes: a container build, manifests, IAM policies, the AWS resources that replace Lambda triggers, and a cut-over plan with a rollback for every step. An AI model reads each function’s code and makes the decisions a rule cannot make safely. Your handler runs as it is.

§2

Install

Python 3.10 and an API key.

You need Python 3.10 or later, Docker to build images, and kubectl for an EKS cluster with KEDA installed. The AI review uses Claude through the Anthropic API, or open models through Together AI.

git clone https://github.com/andrewbakercloudscale/lambda2eks.git && cd lambda2eks
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[aws,postgres]'
export ANTHROPIC_API_KEY=...     # or TOGETHER_API_KEY=... for open models
§3

Migrate a function

From a template, or from the account.

From a SAM or CloudFormation template:

lambda2eks from-template template.yaml --registry 123456789012.dkr.ecr.eu-west-1.amazonaws.com

From functions already deployed. It makes read only AWS calls and downloads the code Lambda runs:

lambda2eks from-aws orders-api order-worker --region eu-west-1

Each function gets a folder:

out/orders-api/
  Dockerfile, build.sh, src/      the build, your handler unchanged
  k8s/                            kubectl apply -k k8s/
  helm/                           the same objects as a chart (--format helm)
  iam/                            trust policy and worker policy
  infra/resources.yaml            bridge queues, DLQs, lease table (CloudFormation)
  cutover/CUTOVER.md              one trigger at a time, each with a rollback
  ai/review.json, ai/patches/     the AI review and suggested fixes
  MIGRATION.md                    decisions, findings, placeholders to fill
out/SUMMARY.md                    every function, its readiness and blockers

Build and apply. Nothing moves yet: queue and stream workers start paused, CronJobs start suspended and SNS subscriptions stay off until you cut over. Add --live for a new install with no Lambda to replace.

cd out/orders-api
bash build.sh                # build and push the image
kubectl apply -k k8s/        # workers start paused, CronJobs suspended

Useful options: --format helm for a chart, --iam irsa instead of EKS Pod Identity, --certificate-arn for HTTPS on the ALB, and --provider together for open models.

§4

How triggers map

Every trigger keeps its event.

The image is the AWS Lambda base image for your runtime (Python 3, Node.js 18 and later). A small shim takes the place of the Lambda runtime: it builds the event your handler expects, provides the context object, enforces the timeout and converts the response.

  • API Gateway (REST, HTTP API) and function URLs

    A Deployment, Service, ALB Ingress, autoscaler and disruption budget. The shim builds the same event, version 1.0 or 2.0, with path parameters.

  • SQS

    A worker that KEDA scales to zero. Batch size, partial batch failures and visibility timeout behave as on Lambda.

  • EventBridge schedules

    A CronJob, in UTC, with two retries like an asynchronous Lambda.

  • EventBridge Scheduler

    A CronJob in the schedule's own time zone, with the same event Scheduler sends. A one time at() schedule becomes a single run; a year filter is checked by the shim.

  • Step Functions tasks

    A worker that polls a Step Functions activity, so it needs no ingress. It sends heartbeats and returns the result or the error type, so Retry and Catch still work. Express machines and waitForTaskToken stay on Lambda.

  • S3 notifications and SNS

    A new SQS bridge queue with a dead letter queue. The worker rebuilds the exact S3 or SNS event, so the handler sees what it always saw. Prefix, suffix and filter policies are copied.

  • Kinesis and DynamoDB Streams

    A consumer that shares shards between replicas with leases in a DynamoDB table, checkpoints each shard and reads parents before children. Retries and batch splitting as on Lambda.

  • No trigger

    A service that answers the Lambda Invoke API path, for callers that invoke the function directly.

  • Anything else

    Reported, with advice from the review.

§5

The AI review

The decisions that need the code.

The rules make a starting plan with the same limits as Lambda. The model then gets the function’s configuration, that plan and the source, and answers in JSON:

  • Concurrency per pod

    Lambda never runs two requests in one process. More is safe only if the handler has no shared mutable state, and useful only if the work waits on I/O.

  • CPU and memory

    Lambda ties CPU to memory. The right size depends on what the code does.

  • Secrets

    Which environment variables are secrets, from their names, the shape of their values and how the code uses them.

  • IAM actions

    The AWS calls the code makes, for a least privilege policy.

  • Findings and patches

    Lambda only features, cold start work, writes outside /tmp, consumers that are not idempotent. Patches go to ai/patches/ for you to review; nothing is applied to your code.

Guard rails:

  • Every AI change has bounds (concurrency 1 to 64, for example) and the report shows it next to the rule value and the reason.
  • The review can add a secret but never remove one the rules found.
  • Values that look like credentials are redacted before anything is sent. .env files and vendored packages are never sent.
  • A finding that cites a file the model was not shown is marked [UNVERIFIED].
  • The answer is checked against a JSON schema. If the review fails, the run fails; rules only output needs --no-ai.
§6

Cut over

One trigger at a time, each with a rollback.

cutover/CUTOVER.md has the commands for each function, with the real queue, rule and mapping names filled in.

  • HTTP

    Route 53 weighted records, moved in steps with cutover/route53-weights.sh set 10, set 50, finish, or rollback.

  • SQS

    Unpause the worker, then disable the Lambda event source mapping.

  • S3

    Point the bucket notification at the bridge queue.

  • SNS

    Subscribe the bridge queue, then remove the Lambda subscription. Expect a few duplicates in the overlap.

  • Streams

    Start the consumer at LATEST beside the Lambda, wait for its iterator age to settle, then disable the mapping.

  • Schedules

    Disable the rule, then unsuspend the CronJob.

  • Scheduler

    Disable the schedule with update-schedule, then unsuspend the CronJob.

  • Step Functions

    Save the definition, then update the state machine so its Task states call the activity. Rollback puts the saved definition back.

§7

Tested on real AWS

Eleven of AWS’s own samples, 11 of 11.

Eleven sample functions written by AWS were deployed to a real account, checked on Lambda, migrated with from-aws and checked again on Kubernetes, against the same queues, streams, buckets and topics. The run found five bugs in lambda2eks, all fixed, and one in an AWS sample. The harness is in the repository under examples/aws-samples/.

  • HTTP API (payload 2.0)

    Lambda PASS · EKS PASS

  • REST API, Python with requests

    Lambda PASS · EKS PASS

  • Function URL, AWS_IAM

    Lambda PASS · EKS PASS, but see Problems

  • SQS

    Lambda PASS · EKS PASS

  • SNS

    Lambda PASS · EKS PASS, through a bridge queue

  • DynamoDB stream

    Lambda PASS · EKS PASS, with shard leases

  • Kinesis

    Lambda PASS after fixing the sample · EKS PASS

  • EventBridge rate(1 minute)

    Lambda PASS · EKS PASS, as a CronJob

  • S3 with a suffix filter

    Lambda PASS · EKS PASS, through a bridge queue

  • EventBridge Scheduler rate(1 minute)

    Lambda PASS · EKS PASS, as a CronJob with the same event

  • Step Functions Standard workflow

    Lambda PASS · EKS PASS, through an activity worker

§8

DynamoDB to PostgreSQL

Take the table with you.

lambda2eks ddb2pg moves a DynamoDB table to any PostgreSQL and keeps it in step from the table’s stream until you switch the code over. Tested end to end with an insert, an update and a delete made after the backfill: all three arrived.

lambda2eks ddb2pg plan Orders --out ddb2pg
lambda2eks ddb2pg apply    --database-url "$PG" --schema ddb2pg/orders.schema.json
lambda2eks ddb2pg backfill --database-url "$PG" --schema ddb2pg/orders.schema.json
lambda2eks ddb2pg sync     --database-url "$PG" --schema ddb2pg/orders.schema.json
lambda2eks ddb2pg verify   --database-url "$PG" --schema ddb2pg/orders.schema.json
lambda2eks ddb2pg rewrite  ./src --schema ddb2pg/orders.schema.json
  • plan

    Scans a sample of the table and writes a schema: typed columns for keys, index attributes and attributes that always have one type, with every item kept whole in a doc jsonb column. Single table designs get a view per entity (USER#, ORDER#) from the partition or sort key.

  • apply

    Creates the table, indexes and views in any PostgreSQL.

  • backfill

    A parallel Scan into PostgreSQL.

  • sync

    Reads the DynamoDB stream from its checkpoint, kept in PostgreSQL, until you cut over. Inserts, updates and deletes all apply, parents before children.

  • verify

    Compares counts and a sample of items.

  • rewrite

    AI patches that replace DynamoDB calls in your code with SQL, for you to review.

An attribute with more than one type stays in doc only, and is reported. DynamoDB TTL becomes a note: schedule the delete yourself.

§9

Not migrated

What it reports instead.

The report lists the ones that apply to each function, with a plan.

  • Layers, extensions and VPC configuration
  • FilterCriteria, ParallelizationFactor above 1 and tumbling windows
  • Provisioned concurrency, destinations and asynchronous dead letter queues
  • API Gateway authorizers, throttling and CORS
  • Step Functions Express machines, waitForTaskToken and JSONata states
§10

Problems

If something is not right.

  • The function URL accepted an unsigned request

    AWS_IAM authorisation belongs to the function URL and does not exist on an Ingress. Put an authenticating proxy or ALB OIDC in front, or keep the function URL.

  • The run exits 1 with "AI review failed"

    Check the API key and the model id. To generate without the review, add --no-ai; the report says the settings are rules only.

  • A stream or queue pod was OOM killed

    On Lambda the poller runs outside the function; in a pod it shares the memory. lambda2eks adds 64 Mi for queue workers and 96 Mi for stream consumers. If yours still runs out, raise memory in MIGRATION.md and the manifests.

  • A second from-aws run no longer sees the S3 trigger

    After cut-over the bucket notifies the bridge queue, not the Lambda. Keep the output of the first run.

  • The image build cannot reach the package registry

    from-aws downloads the package Lambda ran, dependencies included, and builds it as it is. A template build installs dependencies, so it needs your registry.

  • Something else

    Open an issue on GitHub with MIGRATION.md and the command you ran.