On-premises installation
The on-premises preview is available through Helm, Native Linux, Online, Bundled and Appliance installation modes.
Architecture
CloudGrange on-premises runs on Kubernetes and is deployed by Helm. Every installation mode ends at the same umbrella chart; they differ only in how much of the stack beneath it the installer builds.
Where no cluster exists, the installers deploy K3s — a single-binary, CNCF-conformant Kubernetes distribution that runs on one VM and can later grow to a multi-node HA control plane without re-platforming. If you already run Kubernetes, install the chart directly onto it.
The chart is published as an OCI artifact at oci://ghcr.io/cloudgrange/charts/cloudgrange and is also bundled inside each install artifact, so an air-gapped install never needs a chart registry at install time.
The Docker Compose stack used through
2609.0.0-preview.4is legacy. It remains reachable via--engine compose/-Engine Composefor one release cycle and is still the only engine supporting the fully offline Bundled mode. It will be retired.
Workloads
The chart deploys these workloads. First-party images are published under ghcr.io/cloudgrange/.
| Workload | Kind | Image | Role |
|---|---|---|---|
cloudgrange-api |
Deployment | ghcr.io/cloudgrange/cloudgrange-api |
Platform API |
cloudgrange-portal |
Deployment | ghcr.io/cloudgrange/cloudgrange-portal |
Web portal; runs non-root as uid 101 |
cloudgrange-relay |
Deployment + Service | ghcr.io/cloudgrange/cloudgrange-relay |
Relay for host agents. mTLS is planned but not implemented; the listener is plain HTTP inside the cluster, exposed over TLS on 8443 |
cloudgrange-postgres |
StatefulSet + PVC | postgres:17.11-alpine |
Database and the default PostgreSQL-encrypted secrets provider |
cloudgrange-keycloak |
Deployment | quay.io/keycloak/keycloak:26.6.4 |
Local identity provider |
cloudgrange-otel-collector |
Deployment | otel/opentelemetry-collector-contrib:0.160.0 |
Telemetry pipeline |
cloudgrange-prometheus |
Deployment + PVC | prom/prometheus:v3.14.0 |
Metrics |
cloudgrange-loki |
Deployment + PVC | grafana/loki:3.7.7 |
Logs |
cloudgrange-grafana |
Deployment + PVC | grafana/grafana:12.1.1 |
Dashboards |
cloudgrange-secrets-bootstrap |
Job (Helm pre-install hook) | alpine/k8s |
Generates the bootstrap secrets once, then ends Completed |
| cert-manager | Separate Helm release | quay.io/jetstack/cert-manager-* |
Issues the in-cluster TLS certificate |
cert-manager must be a separate release installed first: it ships CRDs that this chart's templates reference, and Helm validates every object in a release before applying any of it. A combined install fails with no matches for kind "ClusterIssuer". This is cert-manager's documented pattern, not a CloudGrange quirk.
Network exposure
| Port | Resource | Purpose |
|---|---|---|
| 443/tcp | Ingress (TLS) | Portal, API (/api/, /health/) and the cloudgrange Keycloak realm (/realms/cloudgrange/) |
| 80/tcp | Ingress controller | Bound by K3s Traefik. CloudGrange routes only HTTPS |
| 8443/tcp | Relay Service (TLS) | Relay agent API (/lan/v1/agents/) |
| 6443/tcp | Kubernetes API | K3s installs only; not a CloudGrange service |
Everything else stays on the cluster network with no host port: the API (8080), Keycloak (8080, including its master realm and admin console), PostgreSQL, Grafana, Prometheus, Loki and the OpenTelemetry collector. The self-signed certificate generated at install time should be replaced with a CA-signed one.
The ingress controller is not installed by the chart. On the bundled K3s paths, K3s's own Traefik is used (global.ingress.className: traefik, the default). On any other cluster set global.ingress.className to match your controller — nginx, public (microk8s), azure-application-gateway, alb — or the Ingress will not be claimed and the portal will be unreachable.
Secrets
A Helm pre-install hook Job generates the PostgreSQL, Keycloak admin, Keycloak API client, Grafana, relay enrollment and realm administrator secrets directly through the Kubernetes API, and only when they do not already exist. helm upgrade therefore never rotates a live database's password. Secrets live in Kubernetes Secrets, encrypted at rest by the cluster's etcd encryption provider. OpenBao and Entra ID are optional and not in the default deployment.
Data retention
PersistentVolumeClaims deliberately survive helm uninstall — that is Kubernetes' own default and it protects the database from a mistyped command. Purging data is a separate, explicit step; it is never automatic.
Install modes
| Mode | You provide | Installer builds | Offline |
|---|---|---|---|
| Helm | Any Kubernetes cluster | The chart only | No |
| Native Linux | An Ubuntu/Debian server | K3s + the chart | No |
| Online | Windows + Hyper-V | The VM, K3s, the chart | No |
| Bundled | Windows + Hyper-V | The VM + legacy Compose stack | Yes |
| Appliance | Windows + Hyper-V | Import a VHDX with K3s, chart and images pre-baked | Yes |
There is no signing yet; SHA-256 manifests check integrity only, not authenticity. The runtime agent runs as a Windows service on each Hyper-V host, not as a container.
See current product and release status.
Historical document at source revision 3ab3059afe25f11aad140c21d4f885749652b097 preserves earlier commands and rationale for that code revision. It is not current target architecture or release guidance.