Python API

The oblako.services package. Each service is the local counterpart of an AWS service, reached through its normal boto3 client (get_client()) or native driver (connect()). Oblako is the platform handle that owns them all.

Platform

class oblako.services.platform.Oblako

Manage the full oblako service stack.

up()

Start all Docker-managed services.

Return type:

None

down()

Stop all Docker-managed services.

Return type:

None

status()

Return status of user-facing services (infra like moto is hidden).

Return type:

dict[str, str]

wait_ready(timeout=60.0)

Wait for all services to be ready.

Parameters:

timeout (float)

Return type:

dict[str, bool]

AI / ML

class oblako.services.bedrock.BedrockService(host_port=11434, runtime_port=8004, region=None)

Local Amazon Bedrock service powered by Ollama.

Parameters:

• host_port (int)

• runtime_port (int)

• region (str | None)

property url: str

Ollama engine URL.

pull_model(model=None)

Pull a model into the engine (defaults to the small qwen default).

Parameters:

model (str | None)

Return type:

None

list_models()

List locally available models.

Return type:

list[str]

start_runtime_server()

Start the local bedrock-runtime server in-process (idempotent).

get_client(autostart=True)

boto3 bedrock-runtime client backed by Ollama via BedrockAdapter.

Parameters:

autostart (bool)

get_control_client(autostart=True)

boto3 bedrock control-plane client (foundation models, batch jobs).

Parameters:

autostart (bool)

class oblako.services.sagemaker.SageMakerService

Wrapper around SageMaker SDK local mode.

SageMaker local mode uses Docker directly (no separate container needed). This class provides helpers for managing training images, checking status, and cleaning up local mode artifacts.

property client: docker.DockerClient

Return (or lazily create) the Docker client for the configured backend.

get_session()

Return a SageMaker LocalSession for local mode training/inference.

build_image(path, tag)

Build a training/inference Docker image.

Parameters:

• path (str)

• tag (str)

Return type:

str

list_training_containers()

List running SageMaker local mode containers.

Return type:

list[dict]

list_endpoint_containers()

List running SageMaker local endpoint containers.

Return type:

list[dict]

cleanup()

Remove stopped SageMaker local mode containers.

Return type:

int

image_exists(tag)

Check if a training/inference image exists locally.

Parameters:

tag (str)

Return type:

bool

ensure_notebook_image()

Build oblako’s slim notebook image (JupyterLab + boto3) if it’s absent.

Only builds the bundled image; a custom OBLAKO_NOTEBOOK_IMAGE is left to be pulled by the instance container as usual.

Return type:

str

create_domain(name='studio', instance_type='t3.medium', notebook_port=8889)

Create a Studio domain as a CloudFormation stack (S3 + EC2 + EBS).

The notebook instance is a real container (Jupyter image) publishing JupyterLab on notebook_port. Returns the domain status.

Parameters:

• name (str)

• instance_type (str)

• notebook_port (int)

Return type:

dict

domain_status(name='studio')

Return {domain, stack, status, artifactsBucket, instanceId} (status NONE if absent).

Parameters:

name (str)

Return type:

dict

launch_notebook(name='studio', port=8889)

Run JupyterLab inside the domain’s notebook instance (EBS as home, pre-wired).

boto3 in the kernel hits oblako’s services on the host via host.docker.internal — unmodified AWS code runs against oblako.

Parameters:

• name (str)

• port (int)

Return type:

dict

delete_domain(name='studio')

Tear down the domain’s CloudFormation stack (S3 bucket + EC2 + EBS).

Parameters:

name (str)

Return type:

None

class oblako.services.mlflow.MlflowService(host_port=5050, s3_endpoint='http://host.docker.internal:9000')

Local MLflow App container, pre-wired to S3Proxy for artifact storage.

Parameters:

• host_port (int)

• s3_endpoint (str)

property tracking_uri: str

Return the direct HTTP URL of the MLflow server (for the web UI).

property tracking_server_arn: str

Return the SageMaker MLflow tracking-server ARN.

This is the value you pass to mlflow.set_tracking_uri — exactly like real SageMaker-managed MLflow. The sagemaker-mlflow plugin resolves it to the server URL (via SAGEMAKER_MLFLOW_CUSTOM_ENDPOINT locally) and SigV4-signs the traffic.

property custom_endpoint: str

Return the value for SAGEMAKER_MLFLOW_CUSTOM_ENDPOINT.

Tells the sagemaker-mlflow plugin where to send tracking traffic when the URI is an ARN — locally, the MLflow container — so the ARN resolves without a SageMaker control plane.

ensure_image()

Build the MLflow image (and slim it if docker-slim is available).

Return type:

None

start()

Build the image (if needed), ensure the artifact bucket, then run.

Return type:

None

Storage & databases

class oblako.services.s3proxy.S3ProxyService(host_port=9000)

S3-compatible object storage service backed by S3Proxy.

Parameters:

host_port (int)

property endpoint_url: str

Return the S3Proxy endpoint URL.

get_client()

Return a boto3 S3 client pointing at this S3Proxy.

S3Proxy does not implement botocore’s default flexible checksums (x-amz-checksum-crc32 over aws-chunked), so keep checksum calculation “when_required” — otherwise uploads fail with 501 NotImplemented. (Real checksum support would mean switching the backend to MinIO.)

class oblako.services.dynamodb.DynamoDBService(host_port=8001)

DynamoDB Local service backed by the official Amazon Docker image.

Parameters:

host_port (int)

property endpoint_url: str

Return the DynamoDB Local endpoint URL.

get_resource()

Return a boto3 DynamoDB resource for higher-level API.

get_client(service='dynamodb', **overrides)

boto3 ‘dynamodb’ client pointed at this service’s endpoint.

Parameters:

service (str)

class oblako.services.kinesis.KinesisService(host_port=4567, shard_limit=100)

Local Kinesis Data Streams (kinesalite-backed).

Parameters:

• host_port (int)

• shard_limit (int)

property endpoint_url: str

Return the local Kinesis endpoint URL for boto3 clients.

get_client(service='kinesis', **overrides)

boto3 ‘kinesis’ client pointed at this service’s endpoint.

Parameters:

service (str)

class oblako.services.redshift.RedshiftService(host_port=5439, user='oblako', password='oblako', database='oblako', control_port=5500, data_port=8002, region=None)

Local Amazon Redshift, backed by the oblako/redshift image (no proxy).

Parameters:

• host_port (int)

• user (str)

• password (str)

• database (str)

• control_port (int)

• data_port (int)

• region (str | None)

connect()

Return a psycopg2 connection straight to the Redshift engine.

get_client()

boto3 redshift control-plane client (clusters/nodes via moto).

start_data_server()

Start the redshift-data server in-process (idempotent). Returns its URL.

get_data_client(autostart=True)

boto3 redshift-data client executing real SQL against the engine.

Parameters:

autostart (bool)

class oblako.services.rds.RdsService(engine='postgres', host_port=None, user='oblako', password='oblako', database='oblako', control_port=5500, data_port=8006, region=None)

Local Amazon RDS and Aurora service backed by a real PostgreSQL or MySQL engine.

Parameters:

• engine (str)

• host_port (int | None)

• user (str)

• password (str)

• database (str)

• control_port (int)

• data_port (int)

• region (str | None)

connect()

Return a DB connection to the engine (psycopg2 for postgres, pymysql for mysql).

get_client()

boto3 rds control-plane client (RDS instances + Aurora clusters, via moto).

seed(instances=None, clusters=None)

Idempotently (re)create RDS instances and Aurora clusters from a spec.

clusters entries may carry an "instances" list of member specs. Each dict is passed through as kwargs to create_db_cluster / create_db_instance. Safe to re-run after a moto restart.

Parameters:

• instances (list[dict] | None)

• clusters (list[dict] | None)

Return type:

dict

start_data_server()

Start the rds-data server in-process (idempotent). Returns its URL.

get_data_client(autostart=True)

boto3 rds-data client executing real SQL against the engine.

Parameters:

autostart (bool)

class oblako.services.iceberg.IcebergCatalogService(host_port=8181, s3_endpoint='http://host.docker.internal:9000', warehouse='s3://oblako-iceberg/')

Local Iceberg REST catalog backed by S3Proxy.

Parameters:

• host_port (int)

• s3_endpoint (str)

• warehouse (str)

property endpoint_url: str

REST catalog endpoint that pyiceberg / Spark Iceberg connect to.

Analytics

class oblako.services.trino.TrinoService(host_port=8485)

Local Trino, pre-wired with the Iceberg connector to oblako’s catalog + S3.

Parameters:

host_port (int)

property endpoint_url: str

Trino HTTP endpoint (clients submit SQL via /v1/statement).

query(sql, *, timeout=60.0)

Run a SQL query through Trino’s REST API. Returns {columns, rows} or {error}.

Parameters:

• sql (str)

• timeout (float)

Return type:

dict

class oblako.services.glue.GlueService

Per-job Glue 5 runner. Submit a PySpark script, get back logs + exit code.

property client

Return the docker-py client for the configured backend (docker/podman/colima).

ensure_image()

Pull the Glue 5 image (~5 GB) if it isn’t present locally.

Return type:

None

submit_job(script, *, args=None, env=None, timeout=1200)

Run a PySpark script in a Glue 5 container; return {exit_code, logs}.

The script is written to a tempdir mounted at /scripts/job.py. The container is given creds + endpoints to reach oblako’s S3Proxy and Iceberg REST catalog at host.docker.internal, and an S3A interceptor that strips the one header S3Proxy can’t handle (see _INTERCEPTOR_CLASS).

Parameters:

• script (str)

• args (list[str] | None)

• env (dict[str, str] | None)

• timeout (int)

Return type:

dict

run_workflow(name, steps, *, timeout=600)

Run a Glue workflow: a sequential pipeline of PySpark job steps.

Each step is {name, script}. Steps run in order, and a step runs only if every prior step SUCCEEDED — mirroring a Glue CONDITIONAL trigger gated on predecessor success. The first failure stops the pipeline; the rest are marked SKIPPED. Returns {name, status, steps:[{name, status, exitCode, logs}]}.

This covers the common sequential-ETL workflow. Full DAGs (parallel branches, crawlers, scheduled/event triggers) aren’t modelled yet.

Parameters:

• name (str)

• steps (list[dict])

• timeout (int)

Return type:

dict

class oblako.services.glue_catalog.GlueCatalogService(port=8486)

Local Glue Data Catalog (boto3 glue) bridged to the Iceberg REST catalog.

Parameters:

port (int)

property endpoint_url: str

Endpoint URL boto3 clients connect to.

start_server()

Start the in-process Glue-API shim (idempotent).

Return type:

str

get_client(autostart=True)

Return a boto3 glue client (auto-starts the shim if it isn’t running).

Parameters:

autostart (bool)

Orchestration, compute & management

class oblako.services.stepfunctions.StepFunctionsService(host_port=8083, lambda_endpoint='http://host.docker.internal:3001')

Step Functions Local service backed by the official Amazon image.

Parameters:

• host_port (int)

• lambda_endpoint (str)

write_mock_config(config)

Write the SFN Local mock configuration to the mounted file (hot-reloaded).

Parameters:

config (dict)

Return type:

None

start()

Seed the mock config from the bundled ML templates, then start the container.

Return type:

None

property endpoint_url: str

Return the Step Functions Local endpoint URL.

create_state_machine(name, definition, role_arn='arn:aws:iam::123456789012:role/DummyRole')

Create a state machine and return its ARN.

Parameters:

• name (str)

• definition (dict)

• role_arn (str)

Return type:

str

execute(state_machine_arn, input_data)

Start an execution and return the execution ARN.

Parameters:

• state_machine_arn (str)

• input_data (dict)

Return type:

str

get_client(service='stepfunctions', **overrides)

boto3 ‘stepfunctions’ client pointed at this service’s endpoint.

Parameters:

service (str)

class oblako.services.awslambda.LambdaService(moto)

AWS Lambda — control plane + invocation via moto + Docker.

Parameters:

moto (MotoService)

property endpoint_url: str

Moto serves Lambda at the same endpoint as every other AWS API.

get_iam_client()

boto3 IAM client pointed at moto (for the exec role).

ensure_exec_role(name='oblako-lambda-exec')

Create (idempotent) and return the ARN of the default Lambda exec role.

Parameters:

name (str)

Return type:

str

ensure_runtime_image(runtime, architecture='x86_64')

Pre-pull the runtime image for a given architecture (linux/amd64 or linux/arm64).

Real AWS Lambda defaults to x86_64. On Apple Silicon, Docker would pull the native arm64 manifest, which breaks layers built with x86_64 wheels (numpy, pandas, etc.). We pull the platform we want explicitly — moto then picks up the local image tag without caring about its arch.

Uses the official AWS Lambda images (Amazon Linux 2023, glibc 2.34) so modern wheels work — matches what MOTO_DOCKER_LAMBDA_IMAGE is set to in the moto container.

Parameters:

• runtime (str)

• architecture (str)

Return type:

None

start()

Bring moto up if it isn’t already (no own container).

Return type:

None

stop()

No-op — moto owns the lifecycle.

Return type:

None

wait_ready(timeout=5.0)

Defer readiness to moto.

Parameters:

timeout (float)

Return type:

bool

status()

Defer status to moto.

Return type:

str

get_client(service='lambda', **overrides)

boto3 ‘lambda’ client pointed at this service’s endpoint.

Parameters:

service (str)

class oblako.services.opensearch.OpenSearchService(host_port=9200)

OpenSearch service for vector search and RAG Knowledge Bases.

Parameters:

host_port (int)

property url: str

Return the OpenSearch base URL.

create_knn_index(index_name, dimension=1536)

Create a k-NN vector index (for RAG / Knowledge Bases).

Parameters:

• index_name (str)

• dimension (int)

Return type:

dict

class oblako.services.cloudformation.CloudFormationService(port=5601, region=None)

Manage the in-process CloudFormation server and hand out boto3 clients.

Parameters:

• port (int)

• region (str | None)

property endpoint_url: str

Return the HTTP endpoint URL for the local CloudFormation server.

start_server()

Start the CloudFormation server in-process (idempotent). Returns its URL.

Return type:

str

get_client(autostart=True)

boto3 cloudformation client whose stacks provision into oblako.

Parameters:

autostart (bool)

is_running()

Return True if the local CloudFormation server is already listening.

Return type:

bool

class oblako.services.iam.IamService(moto=None)

IAM/STS control plane (moto) plus oblako’s trust + authorization evaluator.

Parameters:

moto (MotoService | None)

property endpoint_url: str

Return the moto endpoint that backs the IAM/STS control plane.

create_user(name)

Create an IAM user and return its description.

Parameters:

name (str)

Return type:

dict

create_role(name, trust_policy)

Create an IAM role with the given trust policy and return its description.

Parameters:

• name (str)

• trust_policy (dict)

Return type:

dict

create_policy(name, document)

Create a customer-managed policy and return its description.

Parameters:

• name (str)

• document (dict)

Return type:

dict

attach_role_policy(role_name, policy_arn)

Attach a managed policy to a role.

Parameters:

• role_name (str)

• policy_arn (str)

Return type:

None

attach_user_policy(user_name, policy_arn)

Attach a managed policy to a user.

Parameters:

• user_name (str)

• policy_arn (str)

Return type:

None

gather_statements(principal_arn)

Collect all identity-policy statements (managed + inline) for a user/role ARN.

Parameters:

principal_arn (str)

Return type:

list

authorize(principal_arn, action, resource)

Return Allow/Deny/ImplicitDeny for the principal doing action on resource.

Parameters:

• principal_arn (str)

• action (str)

• resource (str)

Return type:

str

assume_role(role_arn, principal_arn, session_name='oblako-session')

Evaluate the role’s trust policy, then sts:AssumeRole if the principal is allowed.

Parameters:

• role_arn (str)

• principal_arn (str)

• session_name (str)

Return type:

dict

get_client(service='iam', **overrides)

boto3 ‘iam’ client pointed at this service’s endpoint.

Parameters:

service (str)

class oblako.services.ec2.Ec2Service(moto)

AWS EC2 — moto control plane + container-backed instances.

Parameters:

moto (MotoService)

property endpoint_url: str

Moto serves EC2 at the same endpoint as every other AWS API.

run_instance(image_id='ami-0abcdef1234567890', instance_type='t3.micro', *, backed=True, **kwargs)

Launch one instance: record it in moto, then back it with a container.

Returns the InstanceId. backed=False records control-plane metadata only (no container) — useful when Docker isn’t available.

Parameters:

• image_id (str)

• instance_type (str)

• backed (bool)

Return type:

str

stop_instance(instance_id)

Stop the instance (moto -> stopped; container stopped, EBS volume kept).

Parameters:

instance_id (str)

Return type:

None

start_instance(instance_id)

Start a stopped instance (moto -> running; container started).

Parameters:

instance_id (str)

Return type:

None

terminate_instance(instance_id)

Terminate the instance (moto -> terminated; container + EBS volume removed).

Parameters:

instance_id (str)

Return type:

None

instance_container(instance_id)

Return the backing container (or None if the instance isn’t backed).

Parameters:

instance_id (str)

list_instance_containers()

All oblako EC2 instance containers (running or stopped).

Return type:

list

start()

Bring moto up if it isn’t already (no own service container).

Return type:

None

stop()

No-op — moto owns the control plane; instances are managed per-id.

Return type:

None

wait_ready(timeout=5.0)

Defer readiness to moto.

Parameters:

timeout (float)

Return type:

bool

status()

Defer status to moto.

get_client(service='ec2', **overrides)

boto3 ‘ec2’ client pointed at this service’s endpoint.

Parameters:

service (str)

class oblako.services.appconfig.AppConfigService(port=8003)

Local AppConfig + AppConfigData, served by the in-process engine.

Parameters:

port (int)

property endpoint_url: str

Endpoint URL boto3 clients connect to.

start_server()

Start the in-process AppConfig server (idempotent). Returns its URL.

Return type:

str

get_client(autostart=True)

boto3 appconfig management client (applications, profiles, versions…).

Parameters:

autostart (bool)

get_data_client(autostart=True)

boto3 appconfigdata client (StartConfigurationSession / GetLatestConfiguration).

Parameters:

autostart (bool)

get_agent(autostart=True)

Return the bundled AppConfigClient agent, wired to oblako, for flag evaluation.

Parameters:

autostart (bool)

Container backends

The lifecycle layer behind every service: Docker, Apple container, or Kubernetes (selected with OBLAKO_CONTAINER_BACKEND).

Pluggable container backend so oblako isn’t hard-wired to Docker.

Service (see base.py) drives containers through a ContainerBackend instead of calling docker-py directly. Docker, Podman, and Colima all speak the Docker Engine API, so they share DockerBackend — the only difference is which socket it talks to (honoured via DOCKER_HOST or auto-detected per runtime). Kubernetes is a genuinely different control plane, so it gets its own backend, as does Apple’s container (macOS 26+), which has no Docker-API socket.

Select with OBLAKO_CONTAINER_BACKEND = docker (default) | podman | colima | kubernetes | apple. DOCKER_HOST always wins for the Docker-API runtimes.

class oblako.services.backends.ContainerBackend

Minimal container lifecycle interface a Service needs.

ensure_image(image)

Pull the image if it is not present locally.

Parameters:

image (str)

Return type:

None

build_image(image, context_dir)

Build an oblako-owned image from a Dockerfile context.

Parameters:

• image (str)

• context_dir (str)

Return type:

None

run(*, name, image, ports, environment, volumes, extra_hosts, command, working_dir, user)

Create and start a detached container with the given spec.

Return type:

None

status(name)

Return RUNNING, STOPPED, or ABSENT for the named container.

Parameters:

name (str)

Return type:

str

remove(name)

Force-remove the container if present.

Parameters:

name (str)

Return type:

None

stop(name)

Stop and remove the container (no-op if absent).

Parameters:

name (str)

Return type:

None

logs(name, tail=50)

Return the container’s recent logs.

Parameters:

• name (str)

• tail (int)

Return type:

str

class oblako.services.backends.DockerBackend(base_url=None)

Docker Engine API backend — also serves Podman and Colima via their sockets.

Parameters:

base_url (str | None)

property client

Lazily create the docker-py client, honouring DOCKER_HOST or the active context.

ensure_image(image)

Pull the image if it is not already present.

Parameters:

image (str)

Return type:

None

build_image(image, context_dir)

Build an image from a Dockerfile context (skips if already present).

Parameters:

• image (str)

• context_dir (str)

Return type:

None

run(*, name, image, ports, environment, volumes, extra_hosts, command, working_dir, user)

Create and start a detached container.

Return type:

None

status(name)

Return RUNNING/STOPPED/ABSENT for the container.

Parameters:

name (str)

Return type:

str

remove(name)

Force-remove the container if present.

Parameters:

name (str)

Return type:

None

stop(name)

Stop and remove the container (no-op if absent).

Parameters:

name (str)

Return type:

None

logs(name, tail=50)

Return recent logs, or empty string if the container is gone.

Parameters:

• name (str)

• tail (int)

Return type:

str

class oblako.services.backends.KubernetesBackend(namespace=None, kubectl='kubectl')

Run oblako services as Kubernetes workloads (e.g. on minikube), via kubectl.

Each Service maps to a Deployment + Service; kubectl port-forward binds localhost:host_port to the in-cluster Service so oblako’s boto3 clients work unchanged. Port-forwards live as long as the oblako process — after a restart, re-run start (or restart) on a service to re-establish them.

Parameters:

• namespace (str | None)

• kubectl (str)

ensure_image(image)

No image pre-pull: the cluster pulls it (use minikube image load for local images).

Parameters:

image (str)

Return type:

None

run(*, name, image, ports, environment, volumes, extra_hosts, command, working_dir, user)

Apply a Deployment + Service, wait for it, and port-forward each port.

Return type:

None

status(name)

Return RUNNING/STOPPED/ABSENT from the deployment’s ready replicas.

Parameters:

name (str)

Return type:

str

remove(name)

Delete the Deployment + Service and stop its port-forwards.

Parameters:

name (str)

Return type:

None

stop(name)

Stop the service (delete its workload + port-forwards).

Parameters:

name (str)

Return type:

None

logs(name, tail=50)

Return recent logs from the deployment’s pods.

Parameters:

• name (str)

• tail (int)

Return type:

str

class oblako.services.backends.AppleContainerBackend

Apple container backend (macOS 26+): Linux containers in lightweight VMs.

Shells out to the container CLI (there is no Python SDK). Each container runs in its own VM with an IP on a vmnet subnet, but -p host:container publishes to localhost exactly like Docker — so oblako’s fixed-endpoint contract holds unchanged. Two adaptations vs Docker: named volumes are mapped to host dirs (the CLI bind-mounts host paths), and since there is no host.docker.internal / –add-host, env values referencing it are rewritten to the vmnet gateway.

ensure_image(image)

Pre-pull the image (best effort; container run also auto-pulls).

Parameters:

image (str)

Return type:

None

build_image(image, context_dir)

Build an image from a Dockerfile context via container build.

Parameters:

• image (str)

• context_dir (str)

Return type:

None

run(*, name, image, ports, environment, volumes, extra_hosts, command, working_dir, user)

Create and start a detached container via container run.

Return type:

None

status(name)

Return RUNNING/STOPPED/ABSENT from container ls –format json.

Parameters:

name (str)

Return type:

str

remove(name)

Force-remove the container if present.

Parameters:

name (str)

Return type:

None

stop(name)

Stop and remove the container (no-op if absent).

Parameters:

name (str)

Return type:

None

logs(name, tail=50)

Return recent container logs, or empty string if unavailable.

Parameters:

• name (str)

• tail (int)

Return type:

str