Architecture

Host topology​

The jumpbox is the single administrative entry point. OMS installs and configures PostgreSQL, Ceph, Kubernetes, and the Codesphere platform from there. See Requirements and sizing for machine counts and sizing.

Infrastructure components​

• Kubernetes: Codesphere-managed clusters run k0s (pinned to a supported 1.31.x release) with Calico as the CNI. An existing Kubernetes cluster can be used instead; see Use an existing Kubernetes cluster.
• Storage: Ceph, installed and managed via cephadm on dedicated hosts — not Rook-managed Ceph. Inside the cluster, Rook connects to that Ceph cluster as an external cluster to provide the CSI drivers workloads use for persistent storage.
• PostgreSQL: either installed and managed by the installer (postgres.mode: install) or an external database you operate yourself (postgres.mode: external).
• Ingress and gateways: two Kubernetes Services expose Codesphere — the platform gateway (gateway-controller) and the workspace gateway (public-gateway-controller) — routed through Envoy Gateway (the Kubernetes Gateway API implementation) alongside ingress-nginx. See Gateway and load balancing.
• Certificates: cert-manager and trust-manager issue and distribute the cluster's TLS certificates; see Cluster ingress CA options.
• Load balancing: a cloud provider's Kubernetes load-balancer integration, or MetalLB where none exists; see Gateway and load balancing.
• Monitoring: Prometheus, Grafana, Loki, and Grafana Alloy, deployed and configured as described in Cluster monitoring.

Codesphere platform services​

The Codesphere platform itself is a set of services deployed into the codesphere namespace: frontend-gateway (the edge that routes incoming requests), ide-frontend (the web IDE UI), ide-service (IDE backend), auth-service (authentication and authorization), team-service (teams and organizations), workspace-service (workspace lifecycle), workspace-proxy (relays traffic into a running workspace), deployment-service (deployments and CI/CD), public-api-service (the public REST API), marketplace, payment-service, error-page-server, and otel-collector.

Workspaces themselves run in a separate workspaces namespace as workspace-agent containers, managed by workspace-service.

SSH access to workspaces​

ssh-workspace-proxy is a separate service that authenticates and routes SSH connections into running workspaces, exposed at the workspace SSH proxy address described in Requirements and sizing.

Delivery​

The installer package (downloaded via oms download package) contains the dependencies OMS installs directly, plus an Argo CD bootstrap that installs additional cluster components (including ssh-workspace-proxy) as Argo CD Applications. See Run the installer for the installation sequence and Install steps and profiles for the phases involved.