Skip to main content

The mental model (20 minutes)

If you internalize this page, the rest of the docs slot into place. It's the conceptual spine of DevsPortal.

The one paragraph​

DevsPortal is a layer on top of Kubernetes that lets developers express what they need (a service, with these endpoints, depending on that database) while platform engineers control how it runs (which base templates, resource limits, environments, and policies). Everything is a Kubernetes resource reconciled by controllers, so nothing is hidden — the platform augments Kubernetes rather than masking it.

The central split​

This separation is the whole point:

Developers ("builders") work with…Platform engineers define…
Project, Component, Workload, Endpoint, Dependency, ResourceComponentType, Trait, ResourceType, Workflow, Environment, DeploymentPipeline
what their app is and needshow apps deploy, and the guardrails

A developer picks a ComponentType (a golden-path template) the way you pick a project template — they fill in a few parameters and never touch the underlying Kubernetes YAML. The platform engineer authored that template once.

From intent to running app​

Memorize this chain — it recurs everywhere:

Project ─▶ Component (picks a ComponentType) ─▶ Workload (image, endpoints, deps)
   ─▶ build (Workflow) or prebuilt image
   ─▶ ComponentRelease (immutable snapshot)
   ─▶ ReleaseBinding (per Environment, with overrides)
   ─▶ RenderedRelease (real K8s resources on a Data plane)
   ─▶ promote the same release: dev ─▶ staging ─▶ prod

The key insight: a release is an immutable snapshot. Promotion moves the same tested artifact across environments; only per-environment overrides change. No drift.

The planes (the runtime)​

Four planes, one job each:

  • Control plane — the brain: API, controllers, the source-of-truth resources, and the hub that other planes dial into.
  • Data plane — where apps actually run (your endpoints on {fedshi.apps}).
  • Workflow plane — where builds happen.
  • Observability plane — where logs/metrics/traces are collected.

Analogy: the control plane is the conductor holding the score (desired state); the data plane is the orchestra playing; the workflow plane is rehearsal (turning sheet music into something playable); the observability plane is the recording you review afterward.

Why it's not a black box​

Every abstraction is a real Kubernetes resource. A platform engineer can always kubectl get the rendered Deployment behind a Component. That transparency is the deliberate difference from closed PaaS/IDP products — and it's why teams keep full control while developers get simplicity.

Next: see it for real in the Hands-on lab, or read the fuller Concepts.