runtara-environment

Crates.ioruntara-environment
lib.rsruntara-environment
version1.4.1
created_at2025-12-30 07:03:00.811526+00
updated_at2026-01-10 20:16:53.938377+00
descriptionEnvironment server for runtara - image registry, OCI runner, and instance management
homepage
repositoryhttps://github.com/runtara/runtara
max_upload_size
id2012205
size670,825
Volodymyr Rudyi (volodymyrrudyi)

documentation

README

runtara-environment

License

Instance lifecycle management for Runtara. Handles image registration, OCI container execution, and wake scheduling for durable workflows.

Overview

This crate is the control plane for the Runtara platform, providing:

  • Image Registry: Store and manage compiled workflow binaries
  • Instance Lifecycle: Start, stop, and monitor workflow instances
  • OCI Container Runner: Execute workflows in isolated containers via crun
  • Wake Scheduler: Relaunch sleeping instances when their wake time arrives
  • Signal Proxying: Forward cancel/pause/resume signals to runtara-core

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         External Clients                                 │
│                    (runtara-management-sdk, CLI)                         │
└─────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                   runtara-environment (This Crate)                       │
│                         Port 8002                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Image     │  │  Instance   │  │    Wake     │  │  Container  │     │
│  │  Registry   │  │  Lifecycle  │  │  Scheduler  │  │   Runner    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────────────────────┘
          │                 │                              │
          │                 │ Proxy signals                │ Spawn
          │                 ▼                              ▼
          │       ┌───────────────────┐        ┌─────────────────────────┐
          │       │   runtara-core    │◄───────│   Workflow Instances    │
          │       │   Port 8001       │        │   (OCI containers)      │
          │       └───────────────────┘        └─────────────────────────┘
          │                 │
          ▼                 ▼
┌───────────────────────────────────────────────────────────────────────┐
│                           PostgreSQL                                   │
│              (Images, Instances, Checkpoints, Events)                  │
└───────────────────────────────────────────────────────────────────────┘

Running the Server

# Set required environment variables
export RUNTARA_DATABASE_URL=postgres://user:pass@localhost/runtara

# Run the server
cargo run -p runtara-environment

Environment Protocol (Port 8002)

External clients connect via QUIC using runtara-management-sdk. The protocol supports:

Image Operations

Operation Description
RegisterImage Register a new image (single-frame upload < 16MB)
RegisterImageStream Register a large image via streaming upload
ListImages List images with optional tenant filter and pagination
GetImage Get image details by ID
DeleteImage Delete an image

Instance Operations

Operation Description
StartInstance Start a new instance from an image
StopInstance Stop a running instance with grace period
ResumeInstance Resume a suspended instance
GetInstanceStatus Query instance status
ListInstances List instances with filtering and pagination

Signal Operations

Operation Description
SendSignal Send cancel/pause/resume signal to instance

Signals are proxied to runtara-core which stores them for the instance to poll.

Runner Types

Environment supports multiple execution backends:

Runner Description
OCI (default) Execute in OCI containers via crun
Mock In-memory testing runner

OCI Runner

The OCI runner:

  1. Creates OCI bundles from registered images
  2. Launches containers with crun
  3. Mounts instance I/O directories for input/output exchange
  4. Monitors container lifecycle and collects metrics

Instance I/O is exchanged via files:

  • Input: {DATA_DIR}/{tenant_id}/runs/{instance_id}/input.json
  • Output: {DATA_DIR}/{tenant_id}/runs/{instance_id}/output.json

Wake Scheduler

The wake scheduler handles durable sleep:

  1. Polls database for instances with sleep_until in the past
  2. Relaunches the container for each waking instance
  3. The SDK inside the container calculates remaining sleep time

This enables workflows to sleep for hours/days without holding resources.

Configuration

Core Settings

Variable Required Default Description
RUNTARA_DATABASE_URL Yes - PostgreSQL connection string
RUNTARA_ENV_QUIC_PORT No 8002 Environment QUIC server port
RUNTARA_CORE_ADDR No 127.0.0.1:8001 Address of runtara-core
DATA_DIR No .data Data directory for images and bundles
RUNTARA_SKIP_CERT_VERIFICATION No false Skip TLS verification (passed to instances)

OCI Runner Settings

Variable Required Default Description
BUNDLES_DIR No ${DATA_DIR}/bundles Directory for OCI bundles
EXECUTION_TIMEOUT_SECS No 300 Default execution timeout in seconds
USE_SYSTEMD_CGROUP No false Use systemd for cgroup management

Database

Environment shares the database with runtara-core. It manages:

  • instance_images: Maps instances to their source images
  • Image storage and metadata

Migrations are in migrations/.

Running Migrations

Migrations run automatically on server startup. For manual migration:

sqlx migrate run --source crates/runtara-environment/migrations

Testing

# Run unit tests
cargo test -p runtara-environment

# Run with database (integration tests)
TEST_DATABASE_URL=postgres://... cargo test -p runtara-environment

Modules

Module Description
config Server configuration from environment variables
db PostgreSQL persistence for images and instances
handlers Environment protocol request handlers
image_registry Image storage and retrieval
container_registry Running container tracking
instance_output Reading output.json from completed instances
runner Container/process execution backends
server QUIC server implementation
wake_scheduler Durable sleep wake scheduling

Related Crates

License

This project is licensed under AGPL-3.0-or-later.

Commit count: 0

cargo fmt