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.
What it creates
Section titled “What it creates”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.
Before the first apply
Section titled “Before the first apply”1. A database
Section titled “1. A database”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:
psql "postgresql://postgres:<password>@<host>:5432/postgres" \ -v owner_password='…' -v app_password='…' -v system_password='…' \ -f deploy/postgres/setup.sqlThis is the one step that needs psql on a machine that can reach the database.
2. Two secrets in Secrets Manager
Section titled “2. Two secrets in Secrets Manager”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.
3. Two images in ECR
Section titled “3. Two images in ECR”Push them to ECR in the instance’s account and region. Lambda takes single-platform images without attestations:
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:
tofu inittofu apply -var-file=instance.tfvarsThe 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.
Outputs
Section titled “Outputs”| 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 |
Deploy a new version
Section titled “Deploy a new version”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):
aws lambda invoke --function-name sreinsights-migrate --cli-read-timeout 900 /dev/stdoutIt is safe to run again, and twice at once.
Add a runner function
Section titled “Add a runner function”-
Add it to
runnersand apply. Therunnersoutput gives the function’s name and the ARN of its empty identity secret. -
On the Runners page, create a runner group that runs on An AWS Lambda function, with that function name and the region.
-
Connect function on the group gives you an
identitycommand. 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.
A function for your own jobs
Section titled “A function for your own jobs”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: localscript 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 |
Where the secrets are, and are not
Section titled “Where the secrets are, and are not”- 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-configurationand 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
migrationoutput, 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.
Reaching the database
Section titled “Reaching the database”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.
Database connections
Section titled “Database connections”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_concurrencycaps API instances, so connections can’t exceedcap × 2 × api_db_pool_size. Requests beyond the cap get429from 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.
Limits
Section titled “Limits”- 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 withtick_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.
Notifications to SNS
Section titled “Notifications to SNS”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”tofu init -backend=false && tofu validate && tofu testtofu 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.
Variables
Section titled “Variables”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.