Skip to content

0009-rest-api-postgresql-trex-foundation.md

Latest commit

 

History

History
52 lines (36 loc) · 2.61 KB

0009-rest-api-postgresql-trex-foundation.md

File metadata and controls

52 lines (36 loc) · 2.61 KB
Raw

ADR-0009: REST API + PostgreSQL Foundation via rh-trex-ai

Status: Accepted Date: 2026-02-16 Deciders: Mark Turansky, Kevin Howell

Context

The original platform (ADR-0001) stored all business data as Kubernetes Custom Resources in etcd. Three problems emerged:

  1. etcd is not a relational database. Querying, indexing, and joins across CRDs require K8s list operations that do not scale.
  2. No API without Kubernetes. External consumers had an implicit dependency on Kubernetes internals via the stateless public-api proxy.
  3. Model drift. Type definitions were duplicated across Go backend, TypeScript frontend, and public-api DTOs with no single source of truth.

Decision

Adopt rh-trex-ai as the API framework. Business logic lives in per-resource plugins generated by TRex's code generators. Boilerplate (OIDC, DB, migrations, routing, event controllers, health, metrics) is inherited from upstream. OpenAPI specs are emitted per plugin and consumed by SDK generators.

Why rh-trex-ai

  • Battle-tested at scale behind api.openshift.com with years of Red Hat engineering
  • Code generator (--kind Foo --fields ...) produces complete CRUD plugins — boilerplate goes upstream, differentiated value stays in Ambient
  • OpenAPI spec is the single source of truth from which Go, Python, and TypeScript SDKs are generated
  • gRPC watch streaming added as a generator template — every resource type gets real-time change propagation
  • acpctl CLI follows oc / ocm / rosa verb-noun patterns

Consequences

Positive:

  • PostgreSQL as primary data store — proper indexing, joins, query scalability
  • Single OpenAPI spec → all SDKs — drift is structurally impossible
  • Additive rollout: V1 (Kubernetes-native) and V2 (REST/PostgreSQL) run in parallel

Negative:

  • rh-trex-ai is an upstream dependency — framework changes affect Ambient
  • Developers must learn the TRex plugin anatomy
  • Two API paths (V1 backend + V2 api-server) maintained during transition

Current State

Components on main:

  • components/ambient-api-server/ — REST + gRPC API server
  • components/ambient-sdk/ — Go + Python + TypeScript SDKs
  • components/ambient-cli/ — acpctl CLI

The control plane (ambient-control-plane) bridges the API server to Kubernetes for session execution but is not yet on main.

Links