Skip to main content

Architecture

This page goes deeper than How it works. For the authoritative, code-level engine architecture, see the upstream Control Plane Operator architecture docs.

The five planes​

DevsPortal separates responsibilities into planes that scale and fail independently.

Control plane (required)​

The orchestration core. It runs in its own Kubernetes cluster and contains:

  • API server — exposes the OpenAPI-v3 platform API; handles authentication (OAuth2/OIDC via an identity provider) and authorization (role-based + attribute-based access control).
  • Controller manager — watches the custom resources and reconciles desired state into actual state.
  • Cluster gateway — the hub. Every other plane establishes an outbound, mutually-authenticated TLS WebSocket connection here, so the control plane can drive them without ever reaching inbound into their clusters.
  • All platform and developer CRDs — the system of record.

The developer portal (Backstage) and the identity provider sit alongside the control plane in the experience layer.

Data plane (one or more)​

Where workloads run. Each data plane is a Kubernetes cluster that:

  • Runs the Deployments, StatefulSets, Jobs, and CronJobs rendered from components.
  • Enforces isolation with namespaces and network policies.
  • Routes traffic through directional gateways (see Runtime: cells).
  • Runs a cluster agent that dials home to the control-plane gateway.

Data planes can span regions and clouds. Adding one is how you scale or meet data-residency/compliance requirements.

Where CI and builds execute, using Argo Workflows by default (swappable). It builds container images and produces workloads, then notifies the control plane. You can also skip it and integrate an external CI system (GitHub Actions, GitLab CI, Jenkins) that publishes workloads through the API.

Collects logs, metrics, and traces from all planes. The reference instance uses OpenSearch (logs + traces) and Prometheus (metrics), exposed through an Observer API. Backends are pluggable via an adapter pattern.

Experience layer​

How humans and machines interact with the platform: the Backstage portal, the occ CLI, the OpenAPI surfaces, and MCP servers for AI assistants. The same authorization engine governs all of them equally.

Connectivity model​

All planes connect outbound to the control-plane cluster gateway over mTLS. The control plane holds the trust root; each plane's agent presents a client certificate. This hub-and-spoke model:

  • Removes the need to expose any plane's Kubernetes API to another.
  • Works across NAT, firewalls, regions, and clouds.
  • Keeps the security posture identical whether planes are co-located (as in the Fedshi instance) or fully distributed.

The data model: immutable releases​

The platform turns developer intent into running workloads through immutable snapshots:

Component  ──snapshot──▶  ComponentRelease   (immutable: exact config at a point in time)
                                │
                          ReleaseBinding      (binds the release to an Environment +
                                │              applies that env's overrides)
                                ▼
                          RenderedRelease     (the final Kubernetes resources applied
                                               to the target Data plane)

Because a ComponentRelease is immutable, the same release can be promoted from dev to staging to prod with confidence that nothing drifted — only the per-environment overrides (resource limits, replicas, secrets) change. Resources (databases, queues) follow the same pattern with ResourceRelease and ResourceReleaseBinding.

Runtime: the cell model​

At runtime, each Project becomes a cell — a secure, isolated boundary created with a Kubernetes namespace plus network policies. Components inside a cell communicate freely; traffic crossing the cell boundary must pass through structured gateways:

  • Northbound ingress — public internet → cell (external APIs/users); TLS termination, DNS routing, load balancing.
  • Southbound egress — cell → external internet (third-party APIs); credential injection, egress filtering.
  • Westbound ingress — other cells/org → cell (internal APIs); service discovery, org-wide policy.
  • Eastbound egress — cell → other cells/services; dependency tracking.

This aligns organizational boundaries (a Project / team) with physical infrastructure boundaries (namespace + network policy), which is what makes multi-tenancy safe.

Topology in the reference instance​

The Fedshi instance runs all planes in one GKE cluster with public hostnames per plane:

This single-cluster topology is the simplest production-capable layout. Splitting planes across clusters later is additive — see Operator: architecture & topology.