Requirements
What the cluster needs: Kubernetes version, network policies, ingress, DNS, TLS, storage, OIDC and a registry.
Harthelm runs on any conformant Kubernetes cluster that meets the requirements below. The chart's preflight Job checks most of them before anything is installed and fails with a list of what is missing, so you can try an install and read the list.
The cluster
| Requirement | Needed for | Notes |
|---|---|---|
| Kubernetes 1.31 or newer | everything | The chart's kubeVersion. The admission guard is a ValidatingAdmissionPolicy (GA since 1.30). |
A CNI that enforces NetworkPolicy, endPort included | isolation of teams and of the platform | Without enforcement the policies exist but do nothing. Without endPort a port range collapses to its first port and workspaces lose the internet. helm test proves both, see Network policies. |
| Cluster DNS selectable by pod labels | name resolution in every Harthelm pod | Harthelm allows DNS only to the pods selected by networkPolicy.dns and teams.network.dns (default: k8s-app: kube-dns in kube-system). Node-local DNS caches on link-local addresses need extra care, see the GKE and AKS tracks. |
| An Ingress controller or a Gateway API implementation inside the cluster | the console and every workspace URL | WebSockets must pass (IDE, terminals). Core and the router accept traffic only from pods, so a cloud load balancer that sends straight to pod IPs is dropped; put it in front of an in-cluster controller instead. |
| cert-manager | certificates for the edge, custom domains and in-cluster TLS | Recommended. Tested with v1.21. |
| CloudNativePG operator | the bundled platform database and the managed PostgreSQL for users | Tested with operator 1.30.1 (Helm chart cloudnative-pg 0.29.1), installed in cnpg-system. Not needed with an external database and the PostgreSQL provider switched off. |
| A StorageClass for workspace volumes | workspaces | ReadWriteMany, or ReadWriteOnce with every pod of a workspace on one node. The volume root must be writable by a non-root UID in group 0 without fsGroup. See Storage. |
| A StorageClass for block volumes | databases, the managed services' volumes, the backup volume | Any ReadWriteOnce class. The managed services' pods need the class to apply their fsGroup, see Storage. |
Names and certificates
| Requirement | Notes |
|---|---|
| Two DNS names: the console host and a wildcard for the workspace domain | platform.host (console.example.com) and platform.workspaceDomain (*.example.net). They must be different registrable domains, so a workspace can never set cookies for the console. |
| A TLS certificate for each, the workspace one a wildcard | From cert-manager with a DNS-01 issuer, or Secrets you provide. See DNS and TLS. |
Outside the cluster
| Requirement | Notes |
|---|---|
| An OIDC provider | Authorization code flow with PKCE and a confidential client, a groups claim and email_verified. See Sign-in. Without one, only the break-glass admin can sign in. |
| A registry the nodes pull from | Five Harthelm images, pinned by digest. Mirror them when your nodes cannot reach the release's registry, see Air-gapped installs. |
| A licence | A licence file for this installation, or a trial licence for an evaluation; checked offline. See Licence. |
| Optional: a Git provider | Workspaces from Git repositories. This release supports Gitea, see Git providers. Without one, workspaces start empty. |
| Optional: an SMTP relay | Invitation mails and the licence reminders. Without one the console shows each invitation link to copy, see Mail. |
Capacity
The platform pods request about 0.3 CPU and 600 MiB together:
| Pod | CPU request | Memory request |
|---|---|---|
| core | 100m | 192Mi |
| router (2 replicas) | 25m each | 48Mi each |
| bundled database | 100m | 256Mi |
| workspace archive receiver | 50m | 64Mi |
Short-lived Jobs (preflight, backups) come on top. A workspace's IDE on the default plan IDE S is limited to
0.5 CPU and 1.5 GiB and requests 20 % of the CPU and 50 % of the memory (workspaces.sizing); services use their
plans the same way, while a managed service requests its whole plan. The default team quota (teams.quota: 2 CPU and 4 GiB requests, 8 GiB memory limits, 50 GiB
storage) fits about five IDE S per team.
Install permissions
Installing needs cluster admin in practice: the chart creates ClusterRoles, ClusterRoleBindings and a ValidatingAdmissionPolicy with its binding. Permissions lists what each component gets.