Bindings

Bindings give functions managed data services without handling credentials: a KV store on Redis, object storage (S3), a Postgres database, or external credentials you bring. A binding belongs to the organization; you attach it to one or more of its projects and RunR injects the connection details as environment variables.

project "orders-api" ──attach (prefix ORDERS_)──▶ binding "orders-db" (postgres, shared)
project "reports"    ──attach (no prefix)──────▶ binding "orders-db"
                                                  binding "cache"     (kv)

• Binding types
• Environment variables
• Examples
• Lifecycle
• Region setup
• Quotas
• Usage and billing
• Permissions
• How it works
• API
• Configuration (Helm)
• Audit
• Testing

Binding types#

A binding of type kv, object or postgres lives in one region; it can be attached to projects of that region. External bindings can be attached to any project.

Settings#

Every role also gets idle_in_transaction_session_timeout = 60s.

Environment variables#

An attachment can carry an env prefix (upper case, ends with _): with ORDERS_ the project gets ORDERS_DATABASE_URL, ORDERS_PGHOST, … — that is how one project uses two bindings of the same type. Two attachments of a project cannot produce the same variable name; the Bindings tab previews the names while you type the prefix.

DATABASE_URL connects with sslmode=require (CloudNativePG serves TLS). S3_FORCE_PATH_STYLE is true for Garage — configure your S3 client for path-style addressing.

Precedence: the project's own variables — plain ones and secret variables (Secret <project>-secret-env, secretKeyRef entries) — are explicit env entries of the container and win over binding variables with the same name, which come through envFrom (Secret <project>-bindings). RunR-managed variables (RUNR_*) are never overridden by a binding.

Examples#

All examples use the variables without a prefix. With a prefix, read ORDERS_DATABASE_URL instead of DATABASE_URL and so on.

Python#

# requirements.txt: redis, psycopg[binary], boto3
import os
import boto3
import psycopg
import redis
from botocore.config import Config

kv = redis.Redis.from_url(os.environ["REDIS_URL"])
prefix = os.environ["KV_PREFIX"]

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY_ID"],
    aws_secret_access_key=os.environ["S3_SECRET_ACCESS_KEY"],
    region_name=os.environ["S3_REGION"],
    config=Config(s3={"addressing_style": "path"}),
)
bucket = os.environ["S3_BUCKET"]


def handler(event, context):
    hits = kv.incr(prefix + "hits")
    s3.put_object(Bucket=bucket, Key="last.txt", Body=str(hits).encode())
    with psycopg.connect(os.environ["DATABASE_URL"]) as db:
        db.execute("CREATE TABLE IF NOT EXISTS visits (at timestamptz DEFAULT now())")
        db.execute("INSERT INTO visits DEFAULT VALUES")
        total = db.execute("SELECT count(*) FROM visits").fetchone()[0]
    return {"statusCode": 200, "body": {"hits": hits, "visits": total}}

Node.js#

// package.json: "ioredis", "pg", "@aws-sdk/client-s3"
const Redis = require('ioredis')
const { Pool } = require('pg')
const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3')

const kv = new Redis(process.env.REDIS_URL)
const prefix = process.env.KV_PREFIX
const db = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 })
const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.S3_REGION,
  forcePathStyle: process.env.S3_FORCE_PATH_STYLE === 'true',
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  },
})

exports.handler = async () => {
  const hits = await kv.incr(`${prefix}hits`)
  await s3.send(new PutObjectCommand({ Bucket: process.env.S3_BUCKET, Key: 'last.txt', Body: String(hits) }))
  const { rows } = await db.query('SELECT now() AS at')
  return { statusCode: 200, body: { hits, at: rows[0].at } }
}

Keep max of the pool below the binding's connection_limit divided by the number of function instances you expect.

Go#

// go.mod: github.com/redis/go-redis/v9, github.com/jackc/pgx/v5, github.com/aws/aws-sdk-go-v2/service/s3
package main

import (
    "context"
    "os"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/redis/go-redis/v9"
)

func Handler(event interface{}, ctx interface{}) (interface{}, error) {
    c := context.Background()

    opt, _ := redis.ParseURL(os.Getenv("REDIS_URL"))
    kv := redis.NewClient(opt)
    hits, err := kv.Incr(c, os.Getenv("KV_PREFIX")+"hits").Result()
    if err != nil {
        return nil, err
    }

    pool, err := pgxpool.New(c, os.Getenv("DATABASE_URL"))
    if err != nil {
        return nil, err
    }
    defer pool.Close()
    var n int
    _ = pool.QueryRow(c, "SELECT 1").Scan(&n)

    client := s3.New(s3.Options{
        BaseEndpoint: aws.String(os.Getenv("S3_ENDPOINT")),
        Region:       os.Getenv("S3_REGION"),
        UsePathStyle: os.Getenv("S3_FORCE_PATH_STYLE") == "true",
        Credentials:  credentials.NewStaticCredentialsProvider(os.Getenv("S3_ACCESS_KEY_ID"), os.Getenv("S3_SECRET_ACCESS_KEY"), ""),
    })
    _, err = client.PutObject(c, &s3.PutObjectInput{
        Bucket: aws.String(os.Getenv("S3_BUCKET")),
        Key:    aws.String("last.txt"),
        Body:   strings.NewReader("hello"),
    })

    return map[string]interface{}{"statusCode": 200, "body": map[string]interface{}{"hits": hits}}, err
}

KV prefix rules#

A KV user may run every command on keys and channels under its prefix except administrative and dangerous commands (CONFIG, FLUSHALL, FLUSHDB, KEYS, DEBUG, …), SELECT, FUNCTION, SCRIPT FLUSH|KILL and the commands that would list names of other bindings: SCAN, RANDOMKEY, PUBSUB CHANNELS|NUMSUB|NUMPAT|SHARDCHANNELS|SHARDNUMSUB. Keep your own index (a set under the prefix) when you need to enumerate keys. Lua scripts run with the same key permissions. INFO stays allowed for client libraries' ready checks.

Lifecycle#

create ──▶ provisioning ──▶ ready ⇄ rotating
                              │ delete (type the name)
                              ▼
                          deleting ──restore──▶ ready
                              │ retention ends
                              ▼
                           purged (data and resources gone; usage records stay)

Create and attach#

• Project → Bindings → Create binding: creates a binding in the project's region and attaches it in one step (optionally with an env prefix).
• Project → Bindings → Attach existing: attaches a binding the organization already has.
• Settings → Data: every binding of the organization, its projects, status and usage.

Provisioning runs in the background (seconds; a dedicated Postgres cluster takes a few minutes). Attaching works right away: the variables arrive when the binding is ready.

When the attached set of a project changes, RunR updates the project's Secret <project>-bindings and rolls its running Knative Service to a new revision (a new runr.dev/bindings-hash annotation); scheduled functions read the Secret on their next run. Nothing needs to be redeployed.

A tenant with a data residency policy creates, restores and attaches kv, object and postgres bindings only in its allowed regions and data locations; anything else answers 422 (region_not_allowed) and is recorded as residency.denied. External bindings have no region and are not restricted.

Detach#

Detaching removes the variables from the project (rolling restart) and the project from the binding's NetworkPolicy. The binding and its data stay.

Rotate credentials#

Rotate issues new credentials and rolls every attached project onto them:

On a region Redis without ACL support and on external S3 endpoints without an admin API the credentials are the region's own; rotation then re-reads them.

Delete, retention and restore#

Deleting asks you to type the binding name. The binding is detached from every project at once, its access is revoked (KV user disabled and its connections closed, bucket key denied, Postgres role NOLOGIN, a dedicated cluster hibernated) and its data is kept for retentionDays (default 7). Until then Restore brings it back (attach it again afterwards). After the retention the hourly purge deletes the data and the resources: KV keys under the prefix and the user, the bucket with its objects and keys, the database and role (DROP DATABASE … WITH (FORCE)), or the dedicated cluster with its volumes.

Status, health and usage#

The binding list shows the lifecycle status. Status (GET /api/bindings/{id}/status) checks the binding on its data service: the Redis user, the bucket (objects, bytes, quota), the Postgres cluster (ready instances, phase). Usage is measured hourly — KV memory of the binding's keys, bucket size, database size — and shown next to the binding's limit.

Region setup#

Region data services are installed per region in Settings → Regions → (region) → Data services by users with regions.data_services.manage. They run in the namespace runr-data (bindings.namespace) behind NetworkPolicies. A region runs no data service until one is installed there: creating a kv, object or postgres binding is refused until the matching service is ready in its region (Postgres backups also need the object store); external bindings need none.

The managed KV Redis, Garage and the CloudNativePG clusters keep their data on volumes. They tolerate the dedicated-worker taint runr.dev/dedicated=projects:NoSchedule and prefer the nodes that are not dedicated workers: a node-bound volume keeps a pod on the node it was provisioned on, and that node may be selected as a dedicated worker later (architecture.md).

KV#

The managed KV Redis is separate from the queue-trigger Redis on purpose: queue consumers and the region demo may use that one without a password, which would give every pod full access to binding data.

Object storage#

Why Garage for the managed store:

RunR only talks to Garage's S3 and admin APIs; RunR itself stays MIT. Garage runs on one node with LMDB metadata; its volume (storage, default 20Gi) is the capacity of the layout RunR applies on the first start.

Postgres#

Installing Postgres in a region installs the CloudNativePG operator (Helm chart cnpg/cloudnative-pg, version bindings.postgres.cnpgChartVersion, namespace cnpg-system) and the shared cluster runr-pg-shared (instances and storage configurable; max_connections 200). PUBLIC may not connect to the cluster's default databases; each binding's database allows its own role only.

Backups (shared cluster: region setting; dedicated: per binding) go to the bucket runr-pg-backups of the region object store: a daily base backup and the WAL archive (barman-cloud), retention backupRetention (default 7d). Install the object store first.

Dedicated clusters pg-<binding> are created per binding: instances, storage per instance, connection limit (the operator manages the owner role), statement timeout.

Uninstalling a data service is refused while bindings of any organization use it.

Quotas#

Limits per organization (per tenant in the multi-tenant edition), counted from what bindings may grow to — their settings, not today's usage:

0 means unlimited. Defaults come from the Helm values (bindings.quotas); in the multi-tenant edition platform administrators set per-tenant limits in Settings → Tenants → (tenant) → Regions → Binding limits (GET/PUT /api/tenants/{tenant}/binding-quotas). GET /api/bindings/quota shows the organization's limits, claimed amounts and measured bytes.

Size limits are enforced as policy where the data service allows it: Garage bucket quotas, the KV user switched to read + delete above memory_mb, new Postgres sessions read-only above storage_gb (shared), the volume size (dedicated).

Usage and billing#

The hourly measurement books daily usage records per binding:

• storage GB-hours — measured size in GiB × hours since the previous measurement (at most 2 hours, gaps are not billed backwards);
• instance hours — running instances × hours, for dedicated Postgres clusters.

In the multi-tenant edition the usage aggregation prices them with the region's cost configuration (Settings → Billing → Configuration):

Binding costs are part of the tenant's usage cost and appear on its usage charge as one line per binding ("Binding: orders-db (Postgres, dedicated)", Billing).

Permissions#

Attaching, re-prefixing and detaching on a project also needs env.edit on that project: an attached binding's credentials are readable by the project's code. Built-in roles: Owner and Admin hold all four; Developer holds bindings.view and bindings.manage; Viewer and Billing (multi-tenant edition) hold bindings.view. See Permissions.

Credentials are stored encrypted and are never part of API responses; the Secret in the region and GET /api/bindings/{id}/credentials are the only places they appear.

How it works#

 project namespace (functions)                  data namespace runr-data
 ┌──────────────────────────────┐               ┌───────────────────────────────────────┐
 │ Knative Service orders-api   │               │ NetworkPolicy default deny            │
 │   envFrom: Secret            │  allowed by   │ NetworkPolicy runr-binding-orders-db… │
 │   orders-api-bindings ───────┼──────────────▶│   from: runr/project-id in […]        │
 │ Secret orders-api-bindings   │  the policy   │ runr-kv (Redis), runr-objects (Garage)│
 │   ORDERS_DATABASE_URL=…      │               │ runr-pg-shared / pg-<binding> (CNPG)  │
 └──────────────────────────────┘               └───────────────────────────────────────┘

• Secret per project — <project>-bindings in the region's project namespace holds every variable of the project's attachments. The function container references it with envFrom.secretRef (optional, so a pod starts while the Secret is written); the hook is the one line in the container spec builder (BindingEnv::apply).
• Rolling restart — attach, detach, rotation: the Secret is rewritten and the Knative Service's template annotation runr.dev/bindings-hash changes, which is a new revision.
• NetworkPolicies — the data namespace denies all ingress except from its own pods (operations, replication) and the CloudNativePG operator. Each binding adds a policy that lets pods of its attached projects reach its service port (6379, 3900, 5432). Isolation between bindings on a shared service comes from their credentials (ACL users, bucket keys, roles). A CNI without NetworkPolicy support (for example plain Flannel) does not enforce the policies.
• Operations inside the region — user, bucket, role and size operations run as short-lived pods in the data namespace (redis-cli, psql, rclone, the Garage admin API). Their credentials are mounted from a short-lived Secret, never placed in the pod spec or on a command line; pod and Secret are deleted afterwards.
• Background work — provisioning, rotation, suspend/resume and settings changes are queued jobs. Scheduled: usage measurement (hourly), purge of expired deletions (hourly), KV ACL reconcile on region Redis (every 10 minutes).

API#

The CLI covers the same calls (runr bindings, see CLI); AI agents use the bindings_list, binding_create and binding_attach tools of the RunR MCP server (AI agents).

Create a binding:

curl -X POST https://runr.example.com/api/bindings \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"orders-db","type":"postgres","plan":"shared","knative_region_id":"01J…",
       "settings":{"storage_gb":2,"connection_limit":10,"statement_timeout":"15s"}}'

Create and attach in one call (the binding lives in the project's region):

curl -X POST https://runr.example.com/api/projects/$PROJECT/bindings \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"env_prefix":"CACHE_","binding":{"name":"cache","type":"kv","settings":{"memory_mb":128}}}'

External binding:

curl -X POST https://runr.example.com/api/bindings \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"payments","type":"external","values":{"PAYMENTS_URL":"https://pay.example.com","PAYMENTS_TOKEN":"…"}}'

Install the region object store with an external S3 endpoint:

curl -X POST https://runr.example.com/api/knative-regions/$REGION/data-services/object \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"mode":"external","provider":"s3","endpoint":"https://s3.eu-central-1.amazonaws.com",
       "region":"eu-central-1","vendor":"AWS","path_style":false,"bucket_prefix":"acme-",
       "access_key_id":"AKIA…","secret_access_key":"…"}'

Credentials sent here are stored encrypted with the region service and never put into the queued installation job.

Configuration (Helm)#

bindings:
  namespace: runr-data
  retentionDays: 7
  rotationGraceSeconds: 600
  storageClass: ""
  quotas:
    maxBindings: 20
    kvMb: 1024
    objectGb: 100
    postgresGb: 50
    dedicatedPostgres: 2
  kv:
    maxmemoryMb: 512
    storage: 2Gi
  object:
    image: ghcr.io/brf-tech/runr/reqs/garage:v2.1.0
    storage: 20Gi
    s3Region: garage
  postgres:
    cnpgChartVersion: "0.26.0"
    image: ghcr.io/cloudnative-pg/postgresql:17.5
    sharedInstances: 1
    sharedStorage: 10Gi
    backupRetention: 7d

The values become BINDINGS_* environment variables of the API (api/config/bindings.php). The settings without a Helm value of their own are set via extraEnv: BINDINGS_KV_IMAGE (the managed KV Redis image), BINDINGS_OBJECT_META_STORAGE (Garage metadata volume, 1Gi), BINDINGS_CNPG_CHART_REPO and BINDINGS_CNPG_NAMESPACE (cnpg-system), BINDINGS_POSTGRES_BACKUP_SCHEDULE (0 0 3 * * *), BINDINGS_OPS_TIMEOUT (180 s per operation pod), BINDINGS_OPS_TOOLBOX_IMAGE, BINDINGS_OBJECT_CLIENT_IMAGE and BINDINGS_POLL_INTERVAL (3 s). Images of the data services and their operations (garage, rclone, python:3.12-slim, redis:7-alpine) are mirrored under ghcr.io/brf-tech/runr/reqs/ (runtime/ci.sh mirror-reqs); regions with a registry mirror pull Docker Hub names through it.

Audit#

The audit log (Security) records every binding request — with its result (success, denied, failure), actor, tenant and target, never with credential values:

Credentials (bindings.credentials, bindings.previous_credentials, binding_region_services.secrets) are secret columns encrypted at rest (App\Casts\Encrypted) and part of the key rotation of php artisan secrets:encrypt. Listeners can also subscribe to the domain event App\Events\BindingAudited (created, attached, detached, rotated, deleted, restored, purged, data service installed / removed).

Testing#

• API: php artisan test --filter=Binding (api/tests/Feature/Bindings, api/tests/Unit/Bindings) and the data service tests; operations in the region are faked (Tests\Concerns\FakesBindingOps).
• UI: npm test in vue/ (Bindings tab, Data page, region Data services) and npx playwright test e2e/bindings.spec.ts --project=mock (mocked API).
• Kind: runtime/ci.sh test-bindings installs the data services on a Kind cluster, creates one binding of each type, deploys a function that writes and reads each one, rotates, detaches, measures and purges.