12 — Deployment Playbooks¶

Purpose¶

This document explains how different users adopt URP without disrupting current workflows.

Universal deployment rule¶

Start in observe mode. Measure. Then enable exact-safe reductions. Only later enable semantic or approximate reductions with policy and verifiers.

Local developer playbook¶

Goal¶

Understand URP and reduce repeated local AI calls or test data.

Steps¶

Install CLI.
Run local manifest store.
Plan a file.
Run AI gateway against a test provider key.
Inspect manifest.
Inspect ledger.
Enable exact cache.

Commands¶

urp init
urp plan --kind byte_object --file sample.log
urp gateway ai --listen :8080 --provider-env OPENAI_API_KEY
urp ledger query --last 20

Success criteria¶

developer understands work units;
exact cache works;
no production data involved.

Startup playbook¶

Goal¶

Reduce AI and object storage costs quickly.

Deployment¶

Docker Compose
  urp-control
  urp-ai-gateway
  urp-s3-gateway
  postgres
  minio or cloud object backend

Steps¶

Put internal tools behind AI gateway.
Enable exact cache.
Measure repeated prompts.
Add context compiler for RAG app.
Put backup bucket behind object gateway.
Enable exact dedupe/compression.
Add dashboards.

Policies¶

semantic cache off by default;
exact cache same app only;
object dedupe same tenant only;
deletion disabled until reviewed.

Enterprise observe-only playbook¶

Goal¶

Discover savings without changing behavior.

Deployment¶

traffic mirror;
proxy in non-invasive mode;
read-only lakehouse scan;
AI request logs with redaction;
manifest store;
telemetry export.

Outputs¶

savings estimate;
risk classification;
duplicate map;
prompt waste report;
workload heat map;
policy recommendations.

Success criteria¶

no application behavior changes;
owners receive useful reports;
security signs off on next stage.

Enterprise exact-safe playbook¶

Goal¶

Enable safe savings for selected workloads.

Candidate workloads¶

backups;
container layers;
log archives;
duplicate objects;
generated reports;
repeated AI dev prompts.

Actions¶

whole-object dedupe;
content-defined chunking;
zstd compression;
exact prompt cache;
context dedupe in shadow mode.

Required tests¶

exact restore;
range read;
cache isolation;
policy denial;
failover.

AI platform playbook¶

Goal¶

Reduce model calls and prompt bloat.

Steps¶

Insert OpenAI-compatible gateway.
Run observe mode for all requests.
Report task classes and token waste.
Enable exact cache for deterministic internal assistants.
Enable context compiler for RAG apps.
Add model router in shadow mode.
Add verifiers.
Enable small-model route for accepted classes.
Pilot semantic cache.
Distill repeated workflows.

Required controls¶

source fingerprints;
freshness;
tenant isolation;
fallback model;
verifier logs;
redacted prompt storage.

Data platform playbook¶

Goal¶

Reduce lakehouse and stream waste.

Steps¶

Scan object store and catalog.
Identify duplicate files and tiny files.
Recommend compaction.
Run table-native compaction in dev.
Verify exact-logical results.
Enable snapshot-aware policy.
Add lifecycle rules.
Add stream archival reduction.

Do not¶

mutate table files outside transaction protocol;
drop raw data before retention review;
summarize regulated data silently.

Regulated enterprise playbook¶

Goal¶

Use URP safely under strict controls.

Defaults¶

exact_bytes global;
semantic reduction disabled;
cross-tenant cache disabled;
local-only manifest store;
encryption everywhere;
signed policy bundles;
legal hold integration;
manual approvals for lifecycle deletion.

Rollout¶

observe-only;
exact compression/dedupe for non-regulated data;
manifest and ledger audit review;
limited exact-logical table optimization;
semantic reduction only for approved non-record data.

Edge playbook¶

Goal¶

Reduce network and local AI calls.

Actions¶

compress before upload;
dedupe chunks locally;
cache repeated prompts locally;
summarize low-risk telemetry;
send manifests when online;
preserve raw incident data.

Constraints¶

policy cache expiry;
local key storage;
offline mode;
resource caps;
delayed ledger sync.

Kubernetes deployment¶

Components:

control-plane deployment;
optional local operator CRD and operator deployment;
gateway deployment;
worker deployment;
scheduler;
Postgres;
object store credentials;
config maps for policies;
secrets for keys;
service monitors.

Rollout:

kubectl apply -f examples/kubernetes/urp-control-plane.yaml
kubectl apply -f deployments/operator/urp-operator.yaml
kubectl apply -f deployments/kubernetes/urp-multi-region.yaml

Production readiness check¶

Before promoting a local or staging deployment, run:

PYTHONPATH=python python3 -m urp.cli admin readiness

The check uses an isolated local state by default and verifies restart persistence, exact rehydration, authenticated tenant isolation, signed approval gates, recursive redaction, local KMS roundtrip and key-material non-disclosure, range tamper detection, concurrent ledger integrity, backup restore/checksum/path safety, HA and Postgres declarations, versioned cloud object/KMS backends, on-prem and edge artifacts, operator implementation, multi-region topology, API contracts, and all-platform contract readiness.

Run the all-platform matrix:

PYTHONPATH=python python3 -m urp.cli platform matrix
PYTHONPATH=python python3 -m urp.cli platform validate --target all
PYTHONPATH=python python3 -m urp.cli platform validate --target aws --require-live

Targets are contract-ready when schemas, APIs, deployment artifacts, adapter expectations, and validation hooks exist. Targets are live-ready only when the needed credentials or environment bindings are present.

Cloud deployment patterns¶

AWS¶

S3 backend;
EKS;
RDS Postgres;
KMS;
CloudWatch/OpenTelemetry exporter;
IAM roles for service accounts.

Azure¶

Blob Storage backend;
AKS;
Azure Database for PostgreSQL;
Key Vault;
Monitor exporter.

Google Cloud¶

Cloud Storage backend;
GKE;
Cloud SQL;
Cloud KMS;
Cloud Monitoring exporter.

On-prem¶

MinIO/Ceph;
Kubernetes or systemd;
Postgres;
Vault/HSM;
local model server;
Prometheus/Grafana.

Migration plan¶

Existing object bucket¶

observe reads/writes;
build duplicate map;
select prefix;
enable exact-safe writes;
backfill old objects asynchronously;
verify sample restores;
update lifecycle.

Existing AI app¶

switch base URL to URP gateway;
run pass-through;
enable metrics;
enable exact cache;
enable context compiler;
shadow model router;
enforce router with fallback.

Existing lakehouse¶

catalog scan;
recommendations only;
dev table optimization;
snapshot verification;
production canary;
rollback test.

Rollback procedures¶

Object gateway rollback¶

switch DNS/endpoint to original object store;
keep manifest store read-only;
rehydrate affected objects if needed;
disable lifecycle jobs.

AI gateway rollback¶

switch base URL to provider;
disable semantic cache;
export compute manifests;
preserve ledger for audit.

Policy rollback¶

publish previous bundle;
mark bad bundle deprecated;
re-evaluate affected manifests;
emit rollback event.

Enterprise change management¶

Required artifacts:

architecture diagram;
threat model;
data flow;
policy defaults;
rollback plan;
SLOs;
test evidence;
owner signoff.

Adoption success checklist¶

observe mode data collected;
exact restore tested;
security policy approved;
metrics exported;
rollback tested;
owners trained;
cache isolation tested;
semantic features disabled or approved;
incident runbook written.

Ideal-state adoption¶

URP becomes part of platform golden paths:

new object buckets default through URP;
AI apps default through URP gateway;
batch jobs declare deadlines;
training jobs declare dataset manifests;
tables include URP optimization metadata;
developers inspect manifests in CI.