How DevsPortal works

DevsPortal is built on a multi-plane architecture that separates concerns of control, runtime, workflows, and observability. A unified API surface ties them together so the whole is greater than any combination of standalone tools.

The planes

Plane	What it does	Required?
Control plane	The brain. Hosts the API server, controllers, and the cluster gateway; stores all platform/app state as Kubernetes resources. Where the developer portal and identity live.	Yes
Data plane	Where applications actually run. One or more clusters that host workloads, enforce network policies, and route traffic through gateways.	Recommended
Workflow plane	Where CI and builds execute (Argo Workflows by default). Turns source or images into deployable workloads.	Optional
Observability plane	Collects logs, metrics, and traces from the other planes and exposes a query/alert API.	Optional

In the Fedshi reference instance, all four planes run in a single GKE cluster — a common, cost-effective topology. The architecture also supports spreading planes across clusters and clouds; see Architecture.

How the planes connect

A crucial design choice: every other plane connects outbound to the control plane's cluster gateway over mutually-authenticated TLS. The control plane never reaches into the other clusters.

                          ┌─────────────────────────┐
                          │      Control plane       │
   developers ── portal ──▶  API · controllers ·     │
   developers ── CLI ─────▶  cluster gateway (hub)   │
                          └───────────▲──────────────┘
                          outbound mTLS│ (wss) from each plane
              ┌───────────────┬────────┴────────┬───────────────┐
              │               │                 │               │
        ┌─────▼─────┐   ┌─────▼─────┐     ┌─────▼─────┐   (more data planes,
        │  Data     │   │ Workflow  │     │Observ-    │    other clusters/clouds)
        │  plane(s) │   │ plane(s)  │     │ability    │
        └───────────┘   └───────────┘     └───────────┘

This "agent dials home" model means you can place planes in restricted networks, different regions, or different clouds without exposing their Kubernetes APIs to each other. Adding a remote data plane later doesn't change the control plane's posture.

Kubernetes as the system of record

Everything in DevsPortal — the platform's configuration and every application's desired state — is a Kubernetes custom resource. Controllers in the control plane continuously reconcile desired state into reality.

Two consequences:

1. Native GitOps. Because state is declarative Kubernetes resources, you can manage it with kubectl, with a GitOps tool like Flux, or through the portal/CLI — the control plane doesn't care which.
2. Transparency. Platform engineers can always inspect the underlying resources with standard tooling. Nothing is hidden.

From developer intent to running workload

The abstractions are what make the platform feel simple to developers:

1. A developer creates a Component inside a Project, choosing a ComponentType (a template: web service, worker, cron job…) and setting a few parameters.
2. A Workload describes the runtime contract — container image, endpoints, dependencies.
3. The platform builds the component (Workflow plane) or takes a prebuilt image.
4. Deploying to an Environment binds the release to that environment's overrides and renders the final Kubernetes resources onto the target Data plane.
5. The developer promotes the same release through a DeploymentPipeline (dev → staging → prod), with per-environment configuration.
6. Logs, metrics, and traces flow back through the Observability plane, queryable from the portal.

Platform engineers control how all of this happens by authoring ComponentTypes, Traits, ResourceTypes, Workflows, Environments, and pipelines — once — so developers express only what they need.

Next: the Architecture deep dive and the Concepts that name each of these building blocks.