Skip to content

Serverless on AWS

This page shows how to run an SREInsights instance in your own AWS account with no server that stays up: the control plane as AWS Lambda functions, Postgres on RDS, and Lambda runner groups for the runs. The repository’s deploy/aws-serverless/ folder is an OpenTofu configuration (Terraform reads it too) that creates it.

You need access to the SREInsights repository, which is private: ask the SREInsights team.

One image, deploy/Dockerfile.lambda, makes three functions that differ only in their handler:

Resource What it does
<name>-api function, and an API Gateway HTTP API in front of it The API, the runner protocol and the web app. Handler lambda.http
<name>-tick function, and an EventBridge rule every minute The background work: scheduler, runner dispatch, alert evaluation, notifications, reports. Handler lambda.tick
<name>-migrate function Database migrations and the seed. Handler lambda.migrate. Invoked during apply for each new image. Also runs the operator commands
One IAM role per function Each may write its own log group and read the secrets it is told to. The API and tick roles may also invoke functions named <name>-runner-* in this account and region, and nothing else
Three log groups Kept for log_retention_days
<name>-runner-<key> functions (optional, runners) Runner functions for Lambda runner groups, each with its role, log group, and an empty secret for its identity

It does not create the database, the ECR repositories, the secrets’ values, a VPC or DNS records. Those are yours, and they come first.

Create Postgres 14 or newer on RDS. Then run deploy/postgres/setup.sql once, as the master user, to create the database and its three roles:

Terminal window
psql "postgresql://postgres:<password>@<host>:5432/postgres" \
-v owner_password='…' -v app_password='…' -v system_password='…' \
-f deploy/postgres/setup.sql

This is the one step that needs psql on a machine that can reach the database.

Each secret is a JSON object, what the console calls key/value pairs:

// runtime: read by all three functions
{
"DATABASE_URL": "postgresql://sreinsights_app:…@<host>:5432/sreinsights?sslmode=require",
"SYSTEM_DATABASE_URL": "postgresql://sreinsights_system:…@<host>:5432/sreinsights?sslmode=require",
"SREINSIGHTS_SESSION_SECRET": "<at least 32 characters>",
"SREINSIGHTS_MASTER_KEY": "<openssl rand -base64 32>"
}
// owner: read by the migrate function only
{ "DATABASE_OWNER_URL": "postgresql://sreinsights_owner:…@<host>:5432/sreinsights?sslmode=require" }

Add ADAM_API_KEY to the runtime secret if you use ADAM.

Push them to ECR in the instance’s account and region. Lambda takes single-platform images without attestations:

Terminal window
docker buildx build --platform linux/arm64 --provenance=false -f deploy/Dockerfile.lambda \
-t 123456789012.dkr.ecr.us-east-1.amazonaws.com/sreinsights-lambda:2026-11-22.1 --push .
docker buildx build --platform linux/arm64 --provenance=false -f deploy/Dockerfile.runner-lambda \
-t 123456789012.dkr.ecr.us-east-1.amazonaws.com/sreinsights-runner-lambda:2026-11-22.1 --push .

Use a new tag for every build. A function keeps running the image it was created from, so moving a tag changes nothing. This configuration updates the functions only when server_image_uri changes.

Write an instance.tfvars:

name = "sreinsights"
server_image_uri = "123456789012.dkr.ecr.us-east-1.amazonaws.com/sreinsights-lambda:2026-11-22.1"
runtime_secret_arns = ["arn:aws:secretsmanager:us-east-1:123456789012:secret:sreinsights/runtime-AbCdEf"]
owner_secret_arn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:sreinsights/owner-AbCdEf"
# Optional: your own domain (needs an ACM certificate in this region, and a DNS record you create)
# custom_domain = { domain_name = "sre.example.com", certificate_arn = "arn:aws:acm:us-east-1:123456789012:certificate/…" }
# Optional: runner functions
# runners = { jobs = { image_uri = "123456789012.dkr.ecr.us-east-1.amazonaws.com/sreinsights-runner-lambda:2026-11-22.1" } }

Then:

Terminal window
tofu init
tofu apply -var-file=instance.tfvars

The url output is where the instance answers. Sign up there to create the first user and organization.

Keep the state in a backend of your own, for example an S3 bucket with versioning. This folder configures none.

Output What it is
url Where people and runners reach the instance
api_endpoint The HTTP API’s own address. Switched off when custom_domain is set without keep_default_endpoint
custom_domain_target What your domain’s DNS record points at, as an alias or CNAME, with custom_domain
functions The names of the api, tick and migrate functions
migration What the last migrate invocation reported: the last lines the migrations and the seed printed
runner_function_prefix <name>-runner-. The control plane may invoke functions whose names start with this, in this account and region, and no others
runners Each runner function’s name (to give its Lambda runner group) and the ARN of its identity secret
api_policy_attachments The extra policies attached to the API function’s role, by the names in api_policy_arns

Push the new image under a new tag, change server_image_uri, and apply. The configuration fixes the order: the migrate function gets the new image and is invoked; only when it succeeds do the API and tick functions get it. A failed migration fails the apply and leaves the old version serving.

To run migrations yourself (with run_migrations = false, or to read what they print):

Terminal window
aws lambda invoke --function-name sreinsights-migrate --cli-read-timeout 900 /dev/stdout

It is safe to run again, and twice at once.

  1. Add it to runners and apply. The runners output gives the function’s name and the ARN of its empty identity secret.

  2. On the Runners page, create a runner group that runs on An AWS Lambda function, with that function name and the region.

  3. Connect function on the group gives you an identity command. Run it, and store the line it prints in the secret:

    Terminal window
    aws secretsmanager put-secret-value --secret-id <identity_secret_arn> --secret-string "sri1.…"

The identity is made on the machine that runs identity and goes straight into the secret. It never passes through this configuration. See Set up a Lambda runner and Runner settings.

Use an image that extends the runner image (the header of deploy/Dockerfile.runner-lambda shows how), policy_arns for what the jobs may reach in AWS, and script_env_passthrough so their scripts can use those policies at all:

runners = {
jobs = {
image_uri = "123456789012.dkr.ecr.us-east-1.amazonaws.com/acme-jobs:2026-11-22.1"
policy_arns = ["arn:aws:iam::123456789012:policy/acme-jobs-secrets"]
# A function's role exists only as these variables, and a script inherits none of them unless listed.
script_env_passthrough = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_REGION"]
}
}

A job script can then read its provider credentials and database password from Secrets Manager as the function’s role, and nothing secret sits in a monitor. Give jobs a function of their own rather than adding this to the one that runs ordinary checks, because:

  • Every runtime: local script on that function can do everything the role can, not only the script you had in mind.
  • The role can also read the function’s own identity secret. The runner never hands a script the identity or the secret’s name, but a script holding the role’s credentials can ask Secrets Manager for it. Treat whoever can save a script monitor on that runner group as trusted with the runner.

script_env_passthrough refuses connection secrets (SREINSIGHTS_SECRET_*), the registration token and the runner identity variables.

Each entry in runners takes:

Field Type Default What it does
image_uri string Required The runner image in ECR
timeout_s number 900 The function’s time limit
memory_mb number 1024 The function’s memory
ephemeral_storage_mb number 512 The function’s /tmp, from 512 to 10240. Jobs that stage or sort files there need more
environment map(string) {} More settings for the runner. See Runner settings
in_vpc bool false Run this function in the instance’s vpc
policy_arns list(string) [] More IAM policies for the function’s role
script_env_passthrough list(string) [] Variables of the function that runtime: local scripts inherit
  • Not in the state, not in the functions’ configuration. The functions get the secrets’ ARNs (SREINSIGHTS_CONFIG_SECRETS, SREINSIGHTS_RUNNER_IDENTITY_SECRET) and read the values with their own role when an instance starts. tofu show, aws lambda get-function-configuration and the Lambda console show ARNs only.
  • The cost of that: one Secrets Manager call on each cold start, and a function in a VPC needs a route to Secrets Manager.
  • Rotation: a running instance keeps the values it read. After you change a secret, publish any change to the functions, or wait for AWS to recycle their instances. There is no hot reload.
  • What is in the state: the migration output, the last lines the migrations and the seed printed. They name the database host and the migrations, and no credential.
  • Logs: the server redacts tokens, cookies and passwords from request logs.

Functions run outside any VPC unless you set vpc. Choose one:

Functions outside a VPC (default) Functions in your VPC (vpc = { … })
Database Needs a public address: RDS “publicly accessible”, its security group open on 5432, because functions have no fixed addresses Private. Its security group admits the functions’ security group
What protects it TLS (sslmode=require, and rds.force_ssl) and the three passwords The network, then the same
What the functions need Nothing more A route out: they call the Lambda API to wake runner functions, Secrets Manager, and your notification services. That means a NAT gateway, billed by the hour whether used or not
Cost No extra A NAT gateway costs more per month than everything else here together, at small scale

Neither is wrong: it is a choice between exposure and cost.

Each warm function instance keeps its own connection pools: up to api_db_pool_size (2) for each of the two roles in an API instance, and tick_db_pool_size (5) in the tick function. Lambda starts another API instance whenever all are busy, so connections grow with traffic bursts. A frozen instance keeps its connections until AWS recycles it.

  • A small instance class allows on the order of a hundred connections. With the defaults that is some twenty API instances at once.
  • api_reserved_concurrency caps API instances, so connections can’t exceed cap × 2 × api_db_pool_size. Requests beyond the cap get 429 from Lambda. An account with a low concurrency quota may not be able to reserve any; raise the quota first.
  • RDS Proxy is worth adding when bursts regularly reach that cap, or when the database is shared with other applications and must not be starved. Put its endpoint in the three URLs. Prisma uses prepared statements, which pin a session to a connection, so the proxy absorbs connection storms and failovers but multiplexes less than for other clients. It is also billed by the hour.
  • Schedules resolve to the minute. No monitor or report can be saved with an interval under 60 seconds (SCHEDULE_TOO_FREQUENT), or under the tick’s interval if you make it slower with tick_minutes. A run starts up to a minute late. A schedule saved at 30 seconds on a server instance keeps working after a move, and runs once a minute.
  • The scheduler notices things at a tick. A run nobody took (no_runner), a lost lease, a runner group gone offline and a silence that ended are each seen up to a minute later than on a server.
  • Cold starts. A function instance that starts from nothing loads the image, reads its secrets and opens its first database connection before it answers. Expect a first request after a quiet spell to take seconds. The tick runs every minute, so it stays warm; the API function doesn’t unless it has traffic. Provisioned concurrency removes the wait and is billed by the hour.
  • A request has 29 seconds and 6 MB. The HTTP API gives up after 30 seconds, and Lambda refuses a larger request or response (SREInsights answers RESPONSE_TOO_LARGE). ADAM waits for the model inside the request, so a slow answer fails at the gateway.
  • Polling runners work, but are not what this is for. A lease poll is answered at once instead of being held for 25 seconds, because a held poll keeps a function running and billed. The runner waits out the rest of its poll itself, so a run waits up to 25 seconds for a polling runner, and each runner makes about 3,500 requests a day. Don’t point an older runner image at a serverless instance: it asks again at once, without pause. Use Lambda runner groups, which lease the one run they were woken for.
  • A notice can wait a minute if clocks disagree. A notification’s due time is stamped by the function’s clock and compared with the database’s. Beyond a quarter-second pause, the notice goes out at the next tick.

These are AWS list prices for a US region as the SREInsights README states them. Check them against AWS’s pricing pages before you budget.

  • The database is the floor. The smallest RDS instance with 20 GB of storage is roughly $15 a month, and is the one thing always on.
  • The tick is 43,200 invocations a month of well under a second each when there is nothing to do: inside Lambda’s free allowance, and under a dollar a month outside it.
  • Requests cost about $1 per million at the HTTP API, plus the function’s time.
  • Runs on a runner function cost their duration at the function’s memory. A one-minute run at 1 GB is about a tenth of a cent.
  • Secrets are $0.40 each a month. Logs are billed by volume.
  • A NAT gateway changes the picture. You need one only if the functions run inside a VPC, and it costs roughly $35 a month before traffic: more than everything else together.

A notification channel on an aws_sns connection publishes with the functions’ own role. List the topics in sns_topic_arns: the API and tick functions get sns:Publish on exactly those, and nothing else does. Empty (the default), no function may publish. See Notifications.

Check the configuration without an account

Section titled “Check the configuration without an account”
Terminal window
tofu init -backend=false && tofu validate && tofu test

tofu test plans the configuration against a mock provider: it reads no account and creates nothing. It checks the template’s own logic: which function may read which secret, what the control plane may invoke, and that the tick’s rate and the server’s schedule floor stay the same number.

The important inputs from variables.tf:

Variable Type Default What it does
name string sreinsights Names every resource, and is the prefix of the runner functions (<name>-runner-…), the only functions the control plane may invoke. 2 to 31 lower-case letters, digits and hyphens, starting with a letter
server_image_uri string Required The control plane image from deploy/Dockerfile.lambda, in ECR in this account and region. A new value is what makes a deploy
runtime_secret_arns list(string) Required Secrets holding DATABASE_URL, SYSTEM_DATABASE_URL, SREINSIGHTS_SESSION_SECRET, SREINSIGHTS_MASTER_KEY and optionally ADAM_API_KEY. At least one
owner_secret_arn string Required The secret holding DATABASE_OWNER_URL. Only the migrate function may read it
base_url string The custom domain, else the HTTP API’s address SREINSIGHTS_BASE_URL
custom_domain object null { domain_name, certificate_arn, keep_default_endpoint }. Serves the instance on your domain, with an ACM certificate in this region. The HTTP API’s own address is switched off unless keep_default_endpoint is true
environment map(string) {} More settings that are not secrets, for example { LOG_LEVEL = "debug" }. See Environment variables
lambda_runners bool true Lets the instance’s organizations create Lambda runner groups (SREINSIGHTS_LAMBDA_RUNNERS)
runners map(object) {} Runner functions to create. See A function for your own jobs
vpc object null { subnet_ids, security_group_ids }. Runs the functions in a VPC. See Reaching the database
architecture string arm64 arm64 or x86_64: what the images were built for
api_memory_mb number 1024 Memory of the API function. More memory is also more CPU, which shortens cold starts
api_timeout_s number 29 The API function’s time limit, from 10 to 29
api_reserved_concurrency number -1 The most API function instances at once, or -1 for no limit of its own. Bounds database connections
api_db_pool_size number 2 Database connections per role in each API instance
api_throttle object { rate = 50, burst = 100 } Requests per second, and in a burst, before the HTTP API answers 429
api_policy_arns map(string) {} More IAM policies for the API function’s role only, by a name you choose, for example to write store tokens (SREINSIGHTS_STORE_CONNECT)
tick_minutes number 1 How often the background work runs, a whole number from 1 to 60. No monitor or report can run more often
tick_memory_mb number 1024 Memory of the tick function
tick_timeout_s number 120 The tick function’s time limit. Keep a margin above tick_budget_s
tick_budget_s number 50 No round of background work starts later than this into a tick
tick_db_pool_size number 5 Database connections in the tick function. It sends notifications ten at a time
run_migrations bool true Invoke the migrate function during apply whenever server_image_uri changes. false: invoke it yourself
sns_topic_arns list(string) [] SNS topics aws_sns channels publish to
connection_import_secret_arns list(string) [] Secrets the migrate function may read for connections import. Empty except while importing
secrets_kms_key_arns list(string) [] KMS keys the secrets are encrypted with, when not the account’s default key for Secrets Manager
log_retention_days number 30 How long the functions’ logs are kept
tags map(string) {} Tags for every resource

The configuration sets these server settings itself: SREINSIGHTS_SERVERLESS=true, SREINSIGHTS_BASE_URL, SREINSIGHTS_LAMBDA_RUNNERS, SREINSIGHTS_LAMBDA_FUNCTION_PREFIXES (the instance’s <name>-runner-), SREINSIGHTS_TICK_INTERVAL_S, SREINSIGHTS_TICK_BUDGET_MS, SREINSIGHTS_CONFIG_SECRETS and SREINSIGHTS_DB_POOL_SIZE.