Add an official Helm chart so OpenDJ can be deployed on any Kubernetes cluster

[vharseko]

Summary

Add an official Helm chart so OpenDJ can be deployed on any Kubernetes cluster, and test it in GitHub Actions on every change.

Motivation

Today the only orchestration artifact in the repo is an OpenShift Template (opendj-packages/opendj-openshift-template/opendj-openshift-template.yaml). It uses kind: Template, which is OpenShift-specific and cannot be applied with plain kubectl, and it is explicitly limited to a single replica ("Scaling to more than one replica is not supported"). There is no native, portable Kubernetes deployment path, and OpenDJ's core feature — multi-master replication — is not covered.

A Helm chart would give users a portable, parameterized, well-documented way to run OpenDJ on Kubernetes (including OpenShift), and would also let us cover multi-replica replication.

Proposal

Add a Helm chart under opendj-packages/opendj-helm/ providing:

• StatefulSet (based on the openidentityplatform/opendj image) with volumeClaimTemplates for the database, changelog, logs and config.
• Headless Service for stable pod DNS names, plus a client Service for ports 1389 / 1636 / 4444.
• Secret / ConfigMap for root DN, password and base DN.
• Replication bootstrap: an init/entrypoint step that registers each pod into the replication topology (dsreplication) using the stable pod DNS names, enabling replicas > 1.
• Liveness/Readiness probes (LDAP-based checks).
• TLS support: mounting keystore/certificates from a Secret for LDAPS (1636) and admin (4444).
• PodDisruptionBudget, anti-affinity / topologySpreadConstraints.
• Documentation (helm install example) to replace the current TODO: add urls.

Testing in CI

Add a dedicated workflow (triggered only on changes under the chart path) that:

• Lints changed charts with chart-testing (ct lint).
• Renders and validates manifests with helm template + kubeconform.
• Runs template unit tests with helm-unittest.
• Spins up a kind cluster and runs ct install, which installs the chart and executes Helm test hooks (a test pod that runs ldapsearch against the service to confirm LDAP responds).

Benefits

• Portable, kubectl/helm-native deployment on any Kubernetes distribution.
• Multi-replica replication support, unlike the current single-replica OpenShift template.
• Regression protection via automated chart tests on every PR.

Alternatives considered

• Kustomize or plain manifests — simpler but weaker parameterization than Helm.
• Keeping only the OpenShift template — not portable and single-replica only.

Vote to raise the priority 🖐️

[vharseko]

I went through the existing Kubernetes material for OpenDJ to see what the chart can build on:

• vladk1m0/opendj-helm-chart
• arhatdev/opendj on Artifact Hub
• the 2020 blog post
• Ensono/forgerock-k8s
• forgerock/forgeops

and whatever else a search of Artifact Hub, GitHub and the web turns up:

• Gluu's OpenDJ chart and gluufederation/opendj image
• Gluu's April 2024 write-up on OpenDJ replication in Kubernetes
• the Wren:DS image
• mvilche/opendj-openshift
• fsdrw08/helm-charts opendj
• itay47/opendj-helm
• ForgeRock/ds-operator
• Warren Strange's 2017 post on backups
• our own OpenShift template

Summary

None of them can be reused as a chart as is. Gluu is the one real prior art: it ran OpenDJ 4 with automatic replication in Kubernetes for years, and it also documented why it gave up on part of it. The others are useful as a list of what to take over as ideas and what to avoid. The biggest gaps turned out to be in our Docker image rather than in any chart, so I filed those first:

Issue	What it blocks in the chart
#1084 replicate.sh prints its environment, ROOT_PASSWORD included, to the container log	any replicas > 1 install: the password from the Secret ends up in kubectl logs
#1085 a freshly bootstrapped container ignores SIGTERM (bash as PID 1 on tail -f)	clean shutdown: the first pod lifetime always ends in SIGKILL after the grace period (measured: docker stop -t 20 takes 20 s, exit 137; a restarted container stops in 4 s, exit 143)
#1086 joining replication is one-shot, fixed-master (sleep 5, then a single dsreplication enable)	StatefulSet semantics: a -0 that loses its volume comes back as an empty, unreplicated server; a join that races the master is never retried
#1087 keystores from SECRET_VOLUME are copied only on the first start	the TLS bullet: a cert-manager renewal never reaches a server with a persistent volume
#1088 the image does not start under an arbitrary UID in group 0 (/opt/opendj belongs to group opendj)	OpenShift without anyuid: reproduced with docker run --user 1000650000:0, where setup fails on instance.loc / tmp/ and the container exits with code 98

I would fix these in the image before the chart, so that the chart stays a thin layer and plain docker run users get the same fixes. None of the fixes needs inventing: #1085 and #1088 are what the Wren:DS image already does, and #1086 follows Gluu's replicator (details in the issues).

Gluu: the prior art that matters

Gluu shipped OpenDJ as the LDAP store of its cloud-native edition, on its own fork of the same OpenDJ 4 code base (gluu-opendj4). The chart is Apache-2.0. The image's source repository is no longer public, but the scripts can be read in /app/scripts of gluufederation/opendj:4.5.5-1.

What to take over:

• The server is PID 1 (exec start-ds -N). The replication join runs in the background next to it on every start, not once inside the bootstrap.
• The join goes through any peer that holds data, not a fixed master. Exit code 5 of dsreplication enable ("already enabled") counts as success. initialize runs only when a sentinel entry is missing locally. Retries are bounded (10 × 10 s by default).
• Leaving is handled. A preStop hook runs dsreplication disable --disableAll, and a cleanup script removes a dead server from cn=admin data and from the replication-server lists.
• Passwords only through --*PasswordFile, and one PVC with subPaths for config, db, logs and ldif.

What not to take over:

• a HorizontalPodAutoscaler on the directory, enabled by default with up to 10 replicas on CPU;
• a tcpSocket readiness probe;
• a backup CronJob that sleeps 300 s and writes to one of six randomly numbered files.

Their April 2024 write-up explains why they withdrew multi-cluster (multi-region) replication in Kubernetes:

• changes that never synced and had to be forced by hand;
• replication lag that grew under autoscaling at 200–300 req/s, so pods could not shut down with unsent changes;
• recoveries that needed a whole region stopped.

They keep OpenDJ only for a single multi-AZ cluster. The chart should start from the same scope.

@moabu, you wrote that post and most of the Gluu OpenDJ chart, including the Serf and multi-regional work and the preStop hook. @iromli, you worked on the chart's probes. @yurem, you maintain gluu-opendj4. If you have a moment, three questions would help us a lot:

1. The changes that "would not sync in". Did you also see them within a single cluster, or only across regions? If you still have issue links, logs or a rough reproduction, we would like to check them against current OpenDJ. We have been fixing replication session edge cases in the replication server lately, and some of them may be the same thing.
2. The source of the gluufederation/opendj image. GluuFederation/docker-opendj is no longer public. Is it available somewhere, and under which license? Docker image: joining replication is one-shot, fixed-master and unchecked, which a StatefulSet cannot rely on #1086 follows the design of your ldap_replicator.py and deregister_peer.py, and we would rather credit and reuse than re-derive.
3. Fixes worth sharing. Does gluu-opendj4 carry replication or container-related fixes that would make sense upstream here? Conversely, fixes from this repository may be useful to you.

The sources

Source	State	Usable?
vladk1m0/opendj-helm-chart	2020, uses our image's MASTER_SERVER/OPENDJ_REPLICATION_TYPE	No license, so nothing can be copied. See the pitfalls below
arhatdev/opendj 0.0.2	2022, image 4.4.11, README is just helm install	The source is gone: the arhat-dev org is empty, the release .tgz returns 404, the chart repo does not respond. A dead listing
Blog post (2020)	minimal headless Service + StatefulSet, replicas: 1, no probes	Fine as the "hello world" in the chart README
Ensono/forgerock-k8s	archived copy of ForgeRock's 2017 chart	apps/v1beta1 (removed in Kubernetes 1.16), proprietary ForgeRock opendj:4.0.0 image, star topology to -0 like ours
forgeops	current, mature (Ping DS 7/8)	Good architecture to learn from, but its replication model does not port (below)
ForgeRock/ds-operator	2020–2024, operator for DS 7 (volume snapshots, LDIF backup/restore, kubectl scale)	Same DS 7+ dependencies as forgeops
Wren:DS image	current, CDDL	The first-start sequence (setup --doNotStart, init scripts, stop-ds, exec start-ds --nodetach), group-0 ownership, and an /bootstrap/init/*.ldif|*.sh hook are worth copying into our image
mvilche/opendj-openshift	2019, no license	Only as proof that chgrp -R 0 && chmod -R g=u is what OpenShift needs
fsdrw08/helm-charts opendj	2026, MIT, Bitnami-style	A single Pod with hostPorts for podman kube play, no replication. Its liveness idea (search cn=monitor for the userRoot backend) is worth noting
itay47/opendj-helm	2021	A verbatim fork of vladk1m0's chart
Warren Strange, 2017	backup cron in the container plus a sidecar that rsyncs the backup volume to cloud storage	The sidecar split is a reasonable pattern; the post never covers restore

Why forgeops' replication model does not port

forgeops gives every pod the same configuration and lets the servers find each other through bootstrap-replication-server: &{ds.bootstrap.replication.servers}, computed from the pod hostname. There is no pairwise dsreplication enable. That relies on DS 7+ features OpenDJ 4.x does not have:

• configuration expressions &{...};
• the bootstrap-replication-server property;
• the /healthy HTTP endpoint;
• PEM key/trust managers;
• dskeymgr deployment IDs;
• setup-profile, dsrepl disaster-recovery.

Also note that its docker-entrypoint.sh carries a proprietary Ping license, even though the repository as a whole is CDDL.

What is worth taking over as ideas:

• an idempotent init step keyed on "data/db already exists", with the main container only doing exec start-ds --nodetach;
• a startupProbe with a large failureThreshold, so a long import is not killed by liveness;
• topologySpreadConstraints on zone and hostname with ScheduleAnyway;
• a policy/v1 PDB, off by default;
• passwords mounted as files rather than env;
• the PVC spec passed through from values;
• a backup CronJob.

Pitfalls seen in vladk1m0's chart

• Readiness is a tcpSocket probe, so the pod turns Ready in the middle of the bootstrap. That is the exact problem Report the OpenDJ container healthy only once its bootstrap has succeeded #898 solved for the Docker HEALTHCHECK, which Kubernetes ignores. The chart has to repeat that check (the bootstrap marker plus ldapsearch) as its readiness probe.
• javaArgs go to JAVA_OPTS, which the OpenDJ scripts never read (they read OPENDJ_JAVA_ARGS). Had they been applied, -XX:+UseCGroupMemoryLimitForHeap would stop the JVM on the current Temurin 25 image (Unrecognized VM option). Use -XX:MaxRAMPercentage instead.
• The pod anti-affinity selects on an instance label that the pods do not carry, so it has no effect.
• The values ship internal defaults: imagePullSecret: mcs-registry, storageClass: hdd, and a plain-text password.
• It runs as runAsUser: 0. Our image runs as uid 1001. Use runAsUser/fsGroup: 1001, and leave fsGroup unset on OpenShift, which assigns its own. That only works once Docker image: does not start under an arbitrary UID in group 0, so OpenShift needs anyuid #1088 gives the files to group 0: today's chmod g=u covers group opendj, not the OpenShift UID.

Our own OpenShift template

opendj-packages/opendj-openshift-template has not changed since 2019. The release workflows still attach it to every release, but nothing tests it. It is the closest thing to the chart we already ship, so I went through it too (#1089):

• The replication parameters do nothing. OPENDJ_REPLICATION_TYPE is declared but never passed to the container, so replicate.sh never runs. MYHOSTNAME is set to the headless Service name, which resolves to every pod. The "Scaling to more than one replica is not supported" note is the honest consequence.
• The password goes in as a plain env value:. The Secret beside it is unused and malformed: its labels sit outside metadata, and kubeconform -strict rejects it.
• The Service has two selector keys, and the expose-uri annotation names a port that does not exist.
• An untagged image with imagePullPolicy: Always: a pod restart can silently upgrade the data to a new release.
• No probes, resources: {}, and terminationGracePeriodSeconds: 1800, which together with Docker image: a freshly bootstrapped container ignores SIGTERM and is killed without stopping the server #1085 means a 30-minute pod deletion.
• It needs anyuid because of Docker image: does not start under an arbitrary UID in group 0, so OpenShift needs anyuid #1088.

The chart should not inherit any of this, and it should come with the lesson that an untested manifest rots. Once the chart is in (Helm works on OpenShift too), I would retire the template rather than maintain both.

Proposed changes to the plan above

1. One PVC, not four. The image points instance.loc at /opt/opendj/data, so database, changelog, logs and config all live on one volume. Separate PVCs would need image changes first.
2. Probes: readiness repeats the image health check; liveness is a cheap TCP check; a startupProbe covers setup and sample-data import.
3. Headless Service with publishNotReadyAddresses: true, so peers resolve each other while they bootstrap, plus a separate client Service, as proposed.
4. Secrets: existingSecret support, no default password in values.yaml, empty storageClass by default.
5. Scaling: the first version supports a fixed replicas count chosen at install time, and says so in the README (vladk1m0's README is honest about this too). Scale-down needs dsreplication disable until Docker image: joining replication is one-shot, fixed-master and unchecked, which a StatefulSet cannot rely on #1086 covers leaving the topology. No HPA, and one cluster only: that is exactly where Gluu got burnt.
6. CI: besides ct install, run the install with replicas: 2 and a Helm test that writes an entry through -0 and reads it back from -1. An ldapsearch against the Service alone would pass with replication broken.