The chart at deploy/helm/opencluster is not a complete OpenCluster installation. It
deploys the control plane only. You must supply PostgreSQL, ingress, and TLS
termination. A separately deployed browser console is optional and needs same-origin routing.
Prerequisites
You need Kubernetes, Helm 3, a reachable PostgreSQL database, outbound HTTPS access to
the selected model provider, and two Secrets:
opencluster-database with key postgres-dsn;opencluster-credentials with keys bootstrap-token, sealing-key, and model-key.
The shipped chart names these Secret keys bootstrap-token and sealing-key; they supply
the administrator bootstrap token and 32-byte credential-encryption key respectively.
The bootstrap token must be at least 32 characters and the encryption key exactly 32 bytes.
Do not put their values in Helm values or command history.
Install
Create a values file with the public URL, released image, model provider, and model:
Install from a checkout of the matching release:
Verify
The rollout proves only that the control-plane component is ready. The installation is
usable only after ingress routes /api/v1, /webhooks/v1,
/healthz, and /readyz to the HTTP Service on the configured public origin. Verify both
probes through that route:
Both commands must succeed before the deployment accepts user traffic.
Optional Relay listener
Set relay.enabled=true, provide at least one relay.spkiPins value, and name a TLS
Secret in relay.tls.existingSecret. The Secret must contain the configured certificate
and private-key keys. Expose the Relay port only to customer Relays; they initiate the
connection and pin the control-plane public key.
Resources and upgrades
The chart intentionally ships no generic CPU or memory requests. Set requests and limits
from measured Investigation concurrency and provider workloads before production. OSS
v0.1 does not publish a qualified in-place upgrade path. Do not infer compatibility from
image or chart tags; see Feature availability.
Back up PostgreSQL, disable any autoscaler that could restart old replicas, scale the old
Deployment to zero, and wait for every old Pod to terminate. Do not use a rolling upgrade
or run mixed versions against one database. The current ledgered baseline migrates only
when retained user Message attribution agrees with each Conversation source, every
retained nonempty Investigation question has assigned user Messages, and any nonempty
Postmortem reviewer is the UUID of an existing User. A failed check rolls back the migration
without changing the old schema; repair the data with the old version or restore the backup
before retrying. Unknown or unledgered pre-release schemas still
require a fresh application database and complete setup.
Update API clients before the new Pods start. Conversations now expose source (web or
slack) instead of surface and have no lifecycle state; Message roles are user and
assistant, attribution uses authorId and authorName, and replies are assistant Messages
rather than Turn answers. Final hypotheses have no ID or exploring status; Investigation event envelopes use
schemaVersion: 2 with seven compact payloads.
Common failure and recovery
If the rollout stalls, inspect
kubectl --namespace opencluster describe deployment/opencluster-opencluster and the
control-plane Pod logs. Correct missing Secret keys, database reachability, or model
provider configuration, then rerun the Helm command. A ready Pod does not compensate for
missing ingress or TLS routing.
Next step
After ingress and TLS routing are verified, use the API to create the first User
and Organization and continue with the Quickstart.
