Skip to main content
Stackdome presents stacks, resources, releases, and application endpoints to users. In a self-hosted installation, a hub-and-spoke Kubernetes architecture implements that application model. You do not need these details to define or deploy an application; use them when you operate the infrastructure or diagnose reconciliation.
The architecture can address multiple clusters, which is why the diagram shows more than one spoke. During alpha, the product permits one connected cluster per organization. A fresh single-server install has already connected its local k3s cluster, so the diagram does not mean you can add a second cluster to that organization.

​
Components

  • Hub API server and dashboard. The API server accepts user, CLI, and dashboard requests, applies authorization and validation, and coordinates work on the connected cluster. The React dashboard is served by that same API-server binary.
  • PostgreSQL. The hub stores organizations, application definitions, releases, encrypted credentials, and the latest status it presents through the API and dashboard.
  • Spoke agent. Each connected cluster runs the stackdome-agent operator in the stackdome-control-plane namespace. It watches Stackdome custom resources and reconciles them into Kubernetes workloads and supporting objects.
  • Kubernetes custom resources. These carry desired application state from the hub to the agent and observed status back to the hub. They are an implementation interface, not the object model users author directly.
Youweb UI · REST APIHUB — ONE API SERVER YOU INSTALLAPI serverREST API · web UIPostgreSQLMANAGED CLUSTERstackdome-agentDeploymentsServicesIngressesVolumesMANAGED CLUSTERstackdome-agentDeploymentsServicesIngressesVolumeshub writes custom resourcesagent reports status back

​
Reconciliation paths

​
Desired state: hub to cluster

  1. A user, coding agent, or automation submits an application change through the CLI, dashboard, or REST API.
  2. The hub validates and stores the application definition and release state in PostgreSQL.
  3. The hub writes Stackdome custom resources into the organization’s connected cluster.
  4. stackdome-agent reconciles those resources into the Kubernetes objects that run the application.

​
Observed state: cluster to hub

  1. The agent observes builds, rollouts, networking, storage, and readiness in the cluster.
  2. It writes conditions and status onto the relevant custom resources.
  3. controller-runtime watchers in the hub observe status changes and update PostgreSQL.
  4. The API, CLI, and dashboard return the recorded release and resource state.
This is an eventually consistent loop. An accepted deploy means the desired state was recorded; a terminal release state such as Released or Failed tells you how reconciliation finished.

​
Implementation mapping

The dashboard and Stackfile stay application-facing. The agent performs the low-level mapping: Kubernetes remains the runtime source of truth for live workloads. PostgreSQL is the hub’s source of truth for users, application definitions, releases, encrypted connection data, and the status exposed through Stackdome interfaces.

​
Cluster boundary and permissions

The hub reaches a connected cluster with a service-account URL, CA certificate, and token. The single-server installer creates those credentials in stackdome-control-plane and grants the specific cluster-scoped operations required for Stackdome resources, workload namespaces and Secrets, logs, metrics, and supporting infrastructure. See Install Stackdome for the exact local role and its security warning, or Connect compute for the manual credential path.

Stacks and resources

Return to the application model you use in the CLI, Stackfile, and dashboard.