Documentation
The kind of doc your platform-engineering lead can forward to procurement without editorializing. Every claim is dated and specific. The full engineering version of this doc lives in our repository; this page is the shape your buyer needs.
In short
These are the rules the engineering team commits to before any release cuts. We violate one only with a deprecation runway and an announcement.
Rule 1
Your configuration is safe. Contracts, policies, sources, agents, keys, kill switches, custom rules, blueprints, retention settings, threat findings, and recommendations all live on the control plane. The proxy holds them in memory and re-pulls on every sync. Upgrading the proxy throws nothing away.
Rule 2
Your credentials are safe. They live in your secrets layer (env vars, 1Password, AWS Secrets Manager, HashiCorp Vault) and never enter the proxy disk. The proxy reads them at startup; rolling the container re-reads them.
Rule 3
Your audit data is safe. Audit rollups, threat findings, anomaly history, and lineage events all sit in your control plane Postgres. Append-only at the database level (BEFORE-trigger enforcement). A proxy upgrade does not touch this table.
Rule 4
Rolling restarts are non-disruptive. Kubernetes, ECS, and Docker Compose all support rolling replacement; the proxy stays serving requests during the swap when you run two or more replicas.
Rule 5
Version skew is tolerated. Pre-v0.2.0 callers, mixed-version fleets, and control plane / proxy version drift all work within bounded compatibility windows.
Rule 6
We tell you when you are behind. When a new proxy version ships, the control plane advertises latestProxyVersion on /sync/keys. The proxy compares against its own version and self-flags. The console shows a banner. No surprise EOL announcements.
State preservation
Single rule: if the proxy lost it, the next /sync pull restores it. The proxy is intentionally stateless; every load-bearing piece of configuration lives somewhere else.
| Layer | Where it lives | What survives |
|---|---|---|
| Org settings | Control plane Postgres org row | Trust enforcement, anomaly enforcement, PII detection thresholds, tokenization TTL, audit retention, image DLP toggle, LLM egress mode, intelligence sharing. |
| Sources and credentials | Connection metadata: control plane. Secrets: your env vars or vault. | Postgres, MySQL, MongoDB, S3 plus LLM vendor keys (Anthropic, OpenAI, Gemini). Proxy re-reads at startup. |
| Data contracts | Control plane data_contract table | Active plus draft plus deprecated plus retired versions. Bumping the proxy does not touch this table. |
| Policies and custom rules | Control plane policy, pii_custom_recognizer, and llm_custom_rule tables | Per-source role times column matrix, operator-authored regex patterns (data side and LLM egress side). |
| Agents, keys, kill switches | Control plane api_key and kill_switch tables | Per-key role, IP allowlist, signing-enrolled state, kill switches with reasons and expiry. |
| Audit data | Control plane Postgres (audit_rollup, column_access_rollup, column_denial_rollup) | Append-only at the DB level. Configurable retention per org. Operator-deletable via the retention cron only; no other code path can mutate audit rows. |
| Threats, anomalies, recommendations | Control plane tables | Triage state, dismissals, evidence payloads, accepted/dismissed status all preserved. |
| Trust scores | Control plane trust_score plus 30-day history | Current composite and component scores plus the rolling change log. |
| Blueprints and notifications | Control plane tables | Applied blueprint history with snapshot bodies. Notification channels (Slack, PagerDuty, email, SIEM sinks) plus their consecutive-failure counters. |
| Token store | YOUR Postgres (DATADAM_TOKEN_STORE_URL). Lives in your network, not the proxy filesystem. | Reversible token map for tokenize mode. Encrypted at rest with per-source AES-256-GCM. Proxy upgrade does not touch this DB. |
Single rule
If the proxy lost it, the next /sync pull restores it. If the proxy never had it (credentials, vendor keys), your secret-management layer restores it. Nothing about a proxy version bump touches state.
Rollout
The proxy is stateless and the readiness probe is gated on the first sync completing. Rolling-update friendly on every supported orchestrator.
helm upgrade datadam-proxy oci://ghcr.io/mydatadam/charts/datadam-proxy --version <new> --reuse-values
Downtime: None at 2+ replicas. The chart sets strategy.type=RollingUpdate with maxUnavailable=0; replicas swap one at a time. Single-replica deployments see brief downtime during the swap.
docker compose pull proxy ; docker compose up -d proxy
Downtime: Single-replica deployments see <90s during readiness probe. Multi-replica setups behind a load balancer see none.
docker pull ghcr.io/mydatadam/datadam-proxy:vX.Y.Z ; docker stop datadam-proxy ; docker rm datadam-proxy ; docker run -d ghcr.io/mydatadam/datadam-proxy:vX.Y.Z
Downtime: Equals the gap between docker stop and the new container reporting /readyz. Typically 5 to 20 seconds.
Version compatibility
Mixed-version fleets and minor version skew between proxy and control plane are first-class supported. Forward compatibility is a hard rule.
| State | Supported |
|---|---|
| Proxy v0.2.x or v0.3.x against current control plane | Yes. Current stable. CVE patches and feature support. |
| Mixed versions in one org fleet | Yes. Each /sync independently. Control plane treats each proxy as a separate registration. |
| Proxy running ahead of control plane (newer image) | Yes. The proxy treats unknown fields as no-ops. Forward compatibility is a hard rule. |
| Proxy running behind control plane (older image) | Yes. The control plane omits fields the older proxy does not understand. The console banner flags the proxy as outdated. |
| DATADAM_DISABLE_SYNC=true (air-gap deployment) | Allowed. Policy frozen at last successful sync. Operator pulls and applies image bumps manually. Documented for regulated customers. |
Deprecation rules
When we DO deprecate something, the announcement lives in a changelog entry, a proxy_warning row on the control plane, an email to the operator listed on the org, and the console banner. No surprise behavior changes.
New fields on /sync/keys or /proxy/sync/telemetry are additive. Renames or removals get a 2-version deprecation window: deprecated in version N, removed in N+2.
CPU and GPU versions of the proxy stay supported until a 2-version deprecation window names a replacement. Configuration knobs do not disappear between minor versions.
Old env var names keep working for at least 2 versions after the new name ships. The proxy warns on first use of the old name so operators have runway.
Control plane migrations are append-only and additive. Renames implemented as add-new plus dual-write plus read-new plus drop-old over 3+ migrations. No data ever lost on a migration.
Bearer key format, signing scheme, request envelope all carry a 4-version deprecation window. The proxy supports the old AND new auth paths during the transition.
Default flips for trust enforcement, image DLP, redaction behavior, and similar load-bearing settings happen on major versions only and require an explicit changelog entry. Minor versions are additive-only.
How we notify
Every /sync/keys call carries the control plane's advertised latestProxyVersion. The proxy compares against its own version and self-flags via a proxy_outdated warning. The console shows a banner above the fold. The operator never has to remember to check.
Persistent until every proxy in the fleet is on the latest version. Shows the comparison ("v0.2.0 to v0.2.5") so the operator knows exactly how far behind each proxy is.
Major version releases and security CVE patches go to the operator email on the org. Subject line names the CVE. Body links to the release notes.
Every release at github.com/mydatadam/datadam-proxy/releases. Per-version release notes including behavioral changes, image checksums, and provenance attestations.
Every upgrade is your decision, on your timeline, against your change-control process. We tell you. You decide when to ship.
Custom retention beyond 365 days. Custom OCR engine integrations. BAA or DPA terms. Per-region data residency. Extended-support contracts for air-gap deployments. Email support@mydatadam.com and we will work through your specifics.