Install Xberg Enterprise with Helm
Xberg Enterprise is commercially licensed. The Helm chart is a public download; the Enterprise service images are private, and you receive registry credentials for them with your agreement. A chart archive does not grant rights to use the software, so read the bundled LICENSE and your commercial agreement. To arrange access, contact contact@xberg.io.
Enterprise runs as separate services on your cluster: an API, a backend for projects and members, RAG, workers that scale to zero with KEDA, and webhook delivery. They share PostgreSQL, NATS JetStream and object storage. For a single container instead, use Xberg Pro. See Architecture for how the services fit together.
The install has seven steps, and each ends with a check. Do not continue until the check passes.
- Prepare the cluster
- Get the chart
- Prepare the database
- Create the Secrets
- Configure the values
- Install and verify
- Create a project and an API key
Prerequisites
Section titled “Prerequisites”- Helm 4,
kubectl,yqandcurlon the machine that runs the install, and a Kubernetes version within Helm’s support matrix. Any distribution works: EKS, GKE, AKS or on-premises. - Nodes on
linux/amd64orlinux/arm64. The api, backend, worker, webhook, rag and pro images are published for both under one tag, so mixed pools need no per-node tag. The GPU worker,worker-gpu, islinux/amd64only. Schedule it on amd64 nodes, for example withworkerGpu.nodeSelector."kubernetes.io/arch": amd64. - PostgreSQL 15 to 18 (managed or self-hosted) with pgvector 0.8.0 or newer.
pgvectorscaleis optional; see PostgreSQL extensions. psqland the GNUtimeoutcommand on the install machine, which must reach the database, for the bootstrap.- Authenticated NATS JetStream 2.10 or newer. Enable the bundled NATS dependency, or provide your own.
- Persistent object storage: GCS, S3, Azure Blob Storage or an S3-compatible store such as RustFS.
- Registry credentials for the product images, supplied through
imagePullSecretsor node identity. - KEDA, either preinstalled or bundled, and Argo Rollouts or the native Deployment adapter; see Deployment adapter.
- Prometheus Operator, if you want
ServiceMonitorresources. Istio is optional.
The chart does not provision cloud accounts, DNS, buckets or IAM. For external KEDA, install its CRDs and operator first, then set keda.enabled=false and keda.crdsPreinstalled=true. For bundled KEDA, install first with keda.enabled=true and keda.crdsPreinstalled=false, and upgrade with keda.crdsPreinstalled=true once its CRDs and operator are ready. Without keda.crdsPreinstalled=true, the chart renders no ScaledObject.
Check. KEDA and the Rollouts controller (if you use it) are ready:
kubectl get crd scaledobjects.keda.shkubectl get crd rollouts.argoproj.iokubectl get nodes -o wideThe first command lists the ScaledObject CRD unless you let the chart bundle KEDA. The second lists the Rollout CRD when you use Argo Rollouts. The nodes report Ready.
Deployment adapter
Section titled “Deployment adapter”The default deployment.adapter=argo-rollouts renders every service as an Argo Rollout. You must install the Rollouts CRDs and controller before the chart, even when both worker tiers are disabled. For a fresh installation without Argo, set the native adapter:
deployment: adapter: native native: strategy: RollingUpdateNative rolling updates keep maxUnavailable: 0 and maxSurge: 1, so provide spare capacity for the replacement pod. HPA and KEDA are optional: disable a component’s autoscaler to use its fixed replicaCount. When KEDA CRDs are unavailable, native workloads keep their configured replica counts.
Existing installations keep the argo-rollouts default and their canary strategies. deployment.argoRollouts.crdsPreinstalled=true asserts that you installed both the Rollouts CRDs and the controller. The chart does not install them. Switching an installed release between adapters needs a separate staged migration, so do not change only the value on a serving release. The adapter setting does not provide blue/green lifecycle support and rejects it.
Migration hooks quiesce workloads before schema changes under both adapters. Native rolling updates alone do not provide online database migrations or uninterrupted upgrades.
Chart and images
Section titled “Chart and images”Pull the chart from the public registry. Set VERSION to the release named in your agreement, or the latest published release. Download the chart and render the default values:
export ENTERPRISE_CHART=oci://us-central1-docker.pkg.dev/xberg-public-assets/helm-charts/xberg-enterpriseexport VERSION=REPLACE_WITH_RELEASE_VERSIONhelm pull "$ENTERPRISE_CHART" --version "$VERSION" --untarexport ENTERPRISE_CHART_DIR="$PWD/xberg-enterprise"helm show values "$ENTERPRISE_CHART_DIR" > values.yamlIf you received an archive file, extract it with tar -xzf in the working directory instead of helm pull. Keep the extracted chart for the bootstrap files, installation and upgrades.
Each released archive pins the enabled first-party workloads to exact image digests. When you mirror the images, override each repository together with the digest of the copied artifact, and apply the same rule to the migration and utility images. The migration images default to the public ghcr.io/xberg-io/xberg-enterprise-migration-pgschema and ghcr.io/xberg-io/xberg-enterprise-migration-psql repositories and pull anonymously. A private mirror needs its own credentials and repository overrides.
The service image repositories carry no registry host. Set api.image.repository and its siblings to the registry you pull from, and configure imagePullSecrets or node identity for it. Chart download access does not authorize product-image pulls. For a registry Secret:
kubectl create namespace xberg-enterprisekubectl -n xberg-enterprise create secret docker-registry xberg-registry \ --docker-server=REPLACE_WITH_REGISTRY_HOST \ --docker-username=REPLACE_WITH_USERNAME \ --docker-password=REPLACE_WITH_PASSWORDThen list it in values.yaml as imagePullSecrets: [{name: xberg-registry}]. Set tests.images.{curl,postgres,nats,kubectl}.repository and tag or digest for the test images. Test pods use the release imagePullSecrets. Enabled third-party dependencies have their own image settings under their nested values. For the optional Chrome dependency, set chrome.imagePullSecrets when its image mirror needs a registry Secret.
Check. The chart is extracted and its version matches the delivery:
helm show chart "$ENTERPRISE_CHART_DIR" | grep -E '^(name|version):'test -f "$ENTERPRISE_CHART_DIR/charts/_distribution/files/pro-db-bootstrap.sh" && echo OKThe chart reports name: xberg-enterprise and your version, and the second command prints OK.
PostgreSQL extensions
Section titled “PostgreSQL extensions”Enterprise uses four extensions on every deployment, plus one optional extension for the recommended vector index method. The migration Job installs all of them. The optional one sits in a tolerant block, so its absence does not abort the migration.
| Extension | Purpose |
|---|---|
uuid-ossp |
UUID generation primitives |
pgcrypto |
Cryptographic hashing primitives |
btree_gin |
Composite indexes used by audit queries |
pgvector |
Vector types and similarity-search operators |
pgvectorscale (optional) |
StreamingDiskANN index for billion-vector collections |
Without pgvectorscale, set vectorstore.defaultIndexMethod: "hnsw" (environment variable XBERG_VECTORSTORE_DEFAULT_INDEX_METHOD=hnsw) so new collections default to HNSW. The pgvector extension itself supports HNSW, and it is comfortable up to roughly 10 million vectors per index. When pgvectorscale is missing, the migration Job emits a notice and continues. pgvectorscale supports PostgreSQL 13 to 17.
On managed databases:
- Google Cloud SQL has
pgvectorpreinstalled.pgvectorscaleis not available, so pinhnsw, or move to AlloyDB or self-hosted TimescaleDB for billion-scale workloads. - AWS RDS and Aurora manage extensions through parameter groups. Ask AWS to confirm
pgvectorscalefor your engine version. - Azure Database for PostgreSQL enables extensions in the portal or through Terraform.
pgvectoris on the allow-list.
On self-hosted PostgreSQL, the timescale/timescaledb-ha:pg17-all image bundles both extensions, or you can install pgvectorscale from the TimescaleDB package repository.
Database bootstrap
Section titled “Database bootstrap”Use a dedicated PostgreSQL server or cluster for each independently administered Xberg deployment. Separate databases or custom login names do not isolate the fixed Xberg capability roles. Do not install independent Pro and Enterprise releases on the same PostgreSQL server, because migrations and rollbacks change shared role memberships. A separate PostgreSQL instance is enough; a separate Kubernetes cluster is not required.
For a fresh installation, create an empty dedicated database and run the bundled bootstrap once as its PostgreSQL administrator. It completes the schema, the role graph and the vector-index setup before the restricted Helm hooks run. The bootstrap supports both products.
It reads the complete asset directory charts/_distribution/files of the extracted chart. Keep the assets there, because copying them into the chart’s runtime files/ directory would exceed Helm’s release storage limit.
Supply PGHOST, PGPORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD and eight role password variables through your secret manager. The administrator password and the eight role passwords must all be distinct:
POSTGRES_APPLICATION_PASSWORDPOSTGRES_MAINTENANCE_PASSWORDPOSTGRES_SCHEMA_OWNER_PASSWORDPOSTGRES_MIGRATION_PASSWORDPOSTGRES_ROLE_ADMIN_PASSWORDPOSTGRES_INDEX_WORKER_PASSWORDPOSTGRES_VECTOR_BROKER_PASSWORDPOSTGRES_PHYSICAL_MIGRATION_PASSWORD
export PGPASSWORD="$POSTGRES_PASSWORD"export PRO_DB_BOOTSTRAP_MODE=standardexport PRO_DB_BOOTSTRAP_PHASE=allexport PRO_DB_INITIALIZE_SCHEMA=trueexport PRO_DB_DEFER_CLAIMS_ENABLE=trueexport SCHEMA_DIRECTORY="$ENTERPRISE_CHART_DIR/charts/_distribution/files"sh "$SCHEMA_DIRECTORY/pro-db-bootstrap.sh"export MIGRATION_PLAN_DATABASE=xberg_schema_planexport PLANNING_DATABASE_BOOTSTRAP=trueexport PLANNING_EXTENSIONS_FILE="$SCHEMA_DIRECTORY/extensions-prepare.sql"export DATABASE_URL="postgresql://${POSTGRES_USER}@${PGHOST}:${PGPORT}/${POSTGRES_DB}"export MIGRATION_DATABASE_URL="postgresql://xberg_schema_migrator@${PGHOST}:${PGPORT}/${POSTGRES_DB}"sh "$SCHEMA_DIRECTORY/prepare-schema-planning-database.sh"The script detects a true superuser or a restricted administrator on PostgreSQL 16 or newer, and creates eight logins: xberg_app, xberg_maintenance_login, xberg_index_worker_login, xberg_vector_index_broker_login, xberg_physical_migration_login, xberg_schema_login, xberg_role_admin and xberg_schema_migrator. An install that creates Secrets and skips this step fails in the maintenance-role hook.
Use this procedure only on an empty database. For an existing installation, keep its data and follow Upgrade and rollback. Do not replay PRO_DB_INITIALIZE_SCHEMA=true.
The requirements for a restricted administrator are the same as in the Pro Helm guide. Managed-database specifics are in Cloud SQL and AWS storage.
Keep administrator, schema-owner and physical-migration credentials out of runtime workloads. The role-admin Secret holds the restricted xberg_role_admin login.
New installs default to migrations.planningDatabaseBootstrap=false. An upgrade that uses --reuse-values and stored the former true default needs --set migrations.planningDatabaseBootstrap=false once. Explicit bootstrap needs the one-shot migrations.planningDatabaseBootstrapDatabaseUrlSecret. Never reuse a runtime, migration or role-admin Secret for it.
Check. The scripts finish without an error message, and the application login connects:
PGPASSWORD="$POSTGRES_APPLICATION_PASSWORD" \ psql -h "$PGHOST" -p "$PGPORT" -U xberg_app -d "$POSTGRES_DB" -c 'SELECT current_user'psql prints xberg_app.
Secrets and configuration
Section titled “Secrets and configuration”Set secrets.create=false and create the Secrets before installation. The render stops at the first selector it cannot resolve, so create all of them first. Use this example as a starting point:
secrets: create: false databaseUrlSecret: name: xberg-enterprise-secrets key: database-urlglobal: maintenance: databaseUrlSecret: name: xberg-enterprise-secrets key: maintenance-database-url natsCredentials: create: false existingSecret: xberg-natsmigrations: planningDatabaseBootstrap: false databaseUrlSecret: name: xberg-schema-migrator key: database-url roleAdminDatabaseUrlSecret: name: xberg-role-admin key: database-urlvectorIndexWorker: logins: worker: xberg_index_worker_login migration: xberg_schema_migrator broker: xberg_vector_index_broker_login physicalMigration: xberg_physical_migration_login databaseUrlSecret: name: xberg-index-worker key: database-urltests: enabled: true| Secret | Selected by | Keys |
|---|---|---|
| Platform | the fixed name <release>-xberg-enterprise-secrets, or secrets.databaseUrlSecret and global.maintenance.databaseUrlSecret |
database-url, maintenance-database-url, jwt-secret (32 characters or more) |
| NATS | global.natsCredentials.existingSecret, with create: false |
nats-api-password, nats-worker-password, nats-backend-password, nats-rag-password, nats-webhook-password, nats-bootstrap-password |
| Schema migrator | migrations.databaseUrlSecret |
the key you name |
| Role admin | migrations.roleAdminDatabaseUrlSecret |
the key you name |
| Vector-index worker | vectorIndexWorker.databaseUrlSecret |
the key you name |
| Vector-index broker | vectorIndexWorker.brokerDatabaseUrlSecret |
the key you name |
| Physical migration | vectorIndexWorker.physicalMigrationDatabaseUrlSecret |
the key you name |
Create each Secret with kubectl create secret generic, for example:
kubectl -n xberg-enterprise create secret generic xberg-enterprise-secrets \ --from-literal=database-url='postgresql://xberg_app:REPLACE_APPLICATION_PASSWORD@postgres.example.com:5432/xberg' \ --from-literal=maintenance-database-url='postgresql://xberg_maintenance_login:REPLACE_MAINTENANCE_PASSWORD@postgres.example.com:5432/xberg' \ --from-literal=jwt-secret="$(openssl rand -hex 32)"Percent-encode passwords in URLs and use TLS as your database provider requires. Never use administrator URLs for runtime services. Each URL must resolve to its own login.
On the secrets.create: false path the chart cannot see the URLs, so it compares Secret names instead, which does not prove the logins are distinct. With secrets.create: true, the chart refuses a vector-index URL that repeats the application, schema-owner, role-admin or maintenance URL.
Separate Secrets keep the application and schema-owner credential, the maintenance credential and the role-admin credential apart, so Secret-level RBAC and rotation scope independently:
- The role-admin credential runs only the capability-role init step.
- The schema-owner URL applies extensions and schema, and rebuilds exact grants afterward.
- The application and maintenance URLs must resolve to distinct logins with only their matching capability membership.
To rotate the maintenance credential, publish the new URL, bump global.maintenance.credentialRevision and roll every consumer. Revoke the old login only after all old pods are gone and it has no active sessions.
Check. The Secrets exist:
kubectl -n xberg-enterprise get secretsThe list shows every Secret named in the table, plus xberg-registry if you use a registry Secret.
Use distinct, nonempty UTF-8 NATS passwords without NUL. The server and provisioning Job receive the bootstrap credential, and runtime workloads receive only their own. Existing Secrets, including those managed by External Secrets Operator, must contain the bootstrap key.
NATS reserves passwords that begin with $2a$, $2b$, $2x$ or $2y$ followed by two digits and $ for bcrypt hashes, and the chart rejects that syntax at startup. A Secret change needs a restart of the server and clients, because their credentials are injected as environment variables.
For external NATS, set nats.enabled=false and global.natsUrl to its full client URL, for example tls://broker.example.com:4443. For KEDA, also set global.natsMonitoringUrl. Apply the permission ConfigMap rendered with your deployment values to that server, and keep the per-service identities.
The API image runs api --bootstrap-nats <manifest-path> in a bounded provisioning Job before runtime workloads become ready. It creates the shared streams, buckets and durable consumers. Runtime services verify existing resources and cannot administer JetStream.
The bundled dependency enables the optional natsBox diagnostic client. Give it a separate diagnostic identity, or set nats.natsBox.enabled=false to omit it.
When you upgrade an existing installation:
- Add the bootstrap credential to the server and Secret.
- Run the provisioning command against the existing resources.
- Resolve any incompatible resource configuration, then apply the restrictive broker permissions and new runtime images together.
Keep existing messages and consumers. Do not delete streams to bypass a configuration mismatch.
Object storage
Section titled “Object storage”Set STORAGE_PROVIDER and STORAGE_BUCKET under api.env, under worker.env and, when it is enabled, under workerGpu.env. The RAG service reads api.env and takes rag.env as an override. The api, worker and worker-gpu services default to STORAGE_PROVIDER: gcs with an empty bucket, and the render stops and names the component and the value it wants. STORAGE_PROVIDER accepts gcs, s3, azure or fs. Use s3 with an S3-compatible endpoint for RustFS. See Storage and AWS storage.
Network policies
Section titled “Network policies”With <component>.networkPolicy.enabled: true, the chart’s egress rules cover same-namespace dependencies, cluster DNS and public HTTPS.
- The
worker,workerGpuandwebhookspolicies also admit public TCP 80, because crawl seeds and webhook receivers answer on plain HTTP. - The
backendpolicy admits it too, for test webhook deliveries and for every other public client in the backend: OIDC discovery and JWKS, the OAuth token and revocation client and the Google Drive connector.
<component>.networkPolicy.publicEgressPorts sets the ports. An unset or null key keeps TCP 443 and 80, so helm upgrade --reuse-values from an older chart keeps public egress. Only an empty list renders no public rule.
A PostgreSQL, NATS, identity provider or object store outside the release namespace needs a supplemental NetworkPolicy of your own that names its exact destination CIDRs and ports. Without one, every service that needs the database exits with Failed to acquire database role validation connection: Timed out in bb8. Keep those policies in your deployment repository and verify connectivity before rollout.
For SFTP source connectors, also add the destination under backend.networkPolicy.extraEgress, worker.networkPolicy.extraEgress and workerGpu.networkPolicy.extraEgress.
Observability export
Section titled “Observability export”OTLP export is off by default, while local logs and Prometheus metrics stay available. To enable export, set global.observability.otlpEndpoint to your collector’s OTLP/gRPC URL. For an in-cluster collector with network policies enabled, also set global.observability.namespace to its namespace (TCP 4317). The chart does not install a collector. See Observability.
Customization checkpoints
Section titled “Customization checkpoints”Set these values before you deploy:
| Value | Purpose |
|---|---|
global.domain, global.backendDomain |
Primary API domain and web console and backend domain |
global.environment |
Environment name, production or development |
api.hosts, backend.hosts |
Optional host aliases routed by Istio; they default to the global domains |
istio.gateway.hosts |
Every hostname the Istio Gateway accepts; must include all api.hosts and backend.hosts entries |
{api,backend,worker,webhooks}.image.repository and .tag |
Image registry, name and tag for each service |
api.ingress.className, .annotations, .tls |
Ingress class, per-ingress annotations and TLS |
worker.keda.maxReplicas |
Maximum worker replicas (default 50) |
webhooks.keda.maxReplicas |
Maximum webhook replicas (default 10) |
frontend.enabled |
Deploy the web console (default false) |
global.authAllowedEmailDomains |
Email domains that may sign in. Room invitations go only to these domains |
api.env.OPENAPI_CONTACT_URL, api.env.OPENAPI_CONTACT_EMAIL |
Contact details in the generated OpenAPI document. The same keys work under backend.env |
When the web console is on, it shares a host with the control plane and the data plane:
- The web console Ingress owns
/. backend.ingressowns the control-plane paths (/auth/config,/auth/login,/auth/account,/auth/profile,/healthz,/readyz,/api-doc).backend.gatewayApiPaths: trueforwards the data-plane prefixes inbackend.apiGatewayPathPrefixesto the api Service.
Serve the web console host over HTTPS, because the OIDC client uses crypto.subtle, which browsers withhold outside a secure context.
The chart authenticates REST calls with JWTs signed by a key from a Secret with no default. Grafana is not part of the chart, and its authentication belongs to the Grafana instance you run.
Security headers, CORS and rate limits
Section titled “Security headers, CORS and rate limits”The api and backend services send the same security headers as Pro and default to no CORS headers. Set CORS_ALLOWED_ORIGINS, RATE_LIMIT_BURST and RATE_LIMIT_PER_SECS under api.env and backend.env to change the defaults. Set LOGIN_RATE_LIMIT_BURST and LOGIN_RATE_LIMIT_PER_SECS under backend.env. The api service mounts no login route and ignores them. The values mean the same as in Pro configuration.
Worker engine threads
Section titled “Worker engine threads”Set worker.env.WORKER_ENGINE_MAX_THREADS, or workerGpu.env.WORKER_ENGINE_MAX_THREADS for the GPU tier, to a positive whole number to limit the threads used to extract one document. This setting is separate from WORKER_CONCURRENCY, which controls how many documents a worker processes at once. 0 or an invalid value prevents the worker from starting.
When unset, the engine derives its budget from the worker pod’s CPU limit, or the smaller of the available CPU count and eight without a limit. Peak memory grows with the thread budget on multi-page scans, so raise the pod’s memory limit when you raise it.
For model caches, offline clusters and disconnected installs, see Air-gapped installation and RAG configuration.
Check. The values render without errors:
helm lint --strict "$ENTERPRISE_CHART_DIR" -f values.yamlhelm template xberg-enterprise "$ENTERPRISE_CHART_DIR" \ -n xberg-enterprise -f values.yaml > rendered.yaml && echo OKhelm lint reports 0 chart(s) failed, and the second command prints OK. Store rendered.yaml securely, because chart-created Secrets appear in it.
Install and verify
Section titled “Install and verify”Install the chart and check the workloads for your adapter. Run these commands with shell error checking enabled:
set -ehelm upgrade --install xberg-enterprise "$ENTERPRISE_CHART_DIR" \ -n xberg-enterprise -f values.yaml --server-side=false --wait=legacy --wait-for-jobs --timeout 110madapter="$(yq -r '.deployment.adapter // "argo-rollouts"' values.yaml)"case "$adapter" in native) deployments="$(kubectl get deployments.apps -n xberg-enterprise \ -l app.kubernetes.io/instance=xberg-enterprise -o name)" [ -n "$deployments" ] || { echo 'No Deployments found for this release' >&2; exit 1; } for deployment in $deployments; do kubectl rollout status "$deployment" -n xberg-enterprise --timeout=15m done ;; argo-rollouts) rollouts="$(kubectl get rollouts.argoproj.io -n xberg-enterprise \ -l app.kubernetes.io/instance=xberg-enterprise -o name)" [ -n "$rollouts" ] || { echo 'No Rollouts found for this release' >&2; exit 1; } for rollout in $rollouts; do generation="$(kubectl get "$rollout" -n xberg-enterprise -o jsonpath='{.metadata.generation}')" kubectl wait "$rollout" -n xberg-enterprise \ --for="jsonpath={.status.observedGeneration}=$generation" --timeout=15m kubectl wait "$rollout" -n xberg-enterprise --for=jsonpath='{.status.phase}'=Healthy --timeout=15m done ;; *) echo 'Unsupported deployment adapter' >&2; exit 1 ;;esachelm test xberg-enterprise -n xberg-enterprise --logs --timeout 5mHelm 4’s default watcher cannot interpret the string observedGeneration field of Argo Rollouts. Legacy waiting therefore covers built-in resources and Jobs, and the adapter-specific checks verify Deployment rollout completion or current-generation Rollout health. Client-side apply avoids ownership conflicts when the Rollouts controller normalizes resource quantities (for example, 2000m to 2). Keep --server-side=false for later upgrades.
Helm tests check API health and readiness and PostgreSQL and NATS connectivity. To also check authenticated API access, set tests.apiKeySecret.name and tests.apiKeySecret.key to a Secret that holds a valid project API key. The read-only test lists jobs and submits no documents. tests.keda.enabled adds an optional KEDA readiness check. Failed test pods remain for diagnosis, and later tests replace them.
Check. The script ends without an error, and helm test reports every test as Succeeded:
helm status xberg-enterprise -n xberg-enterprise | grep -E '^STATUS'The output is STATUS: deployed.
Create a project and an API key
Section titled “Create a project and an API key”Enterprise projects, members and API keys live in the backend control plane. Create the first project and its API key in the web console (set frontend.enabled=true and sign in with your identity provider), or call the control-plane API with a session token. See Projects and API keys.
Check. The key authenticates against the data plane:
export XBERG_URL=https://REPLACE_WITH_API_DOMAINexport XBERG_API_KEY=REPLACE_WITH_PROJECT_API_KEYcurl --fail -H "Authorization: Bearer $XBERG_API_KEY" "$XBERG_URL/v1/jobs"The response is a JSON job list. Continue with the quickstart.
Migration modes
Section titled “Migration modes”migrations.mode defaults to maintenance. It quiesces workloads and runs the role-contract and restoration hooks around each schema change.
online renders one restricted schema runner instead and does not stop workloads. It accepts only a converged no-op today, and a nonempty plan fails before it changes the database. Use maintenance for every upgrade.
The operation ID and epoch rules, and the hook transaction requirement, match the Pro chart. See Migration modes, and use the Enterprise release name in those commands.
The schema migration credential needs a direct PostgreSQL connection, or a pooler in session-pooling mode, because the migration lock is held on the connection that runs the SQL.
If the migration hook fails
Section titled “If the migration hook fails”A failed migration hook leaves the workloads drained and their autoscalers detached. This is intended: the chart keeps the release down for a corrected retry.
Symptoms:
helm upgrade --installends with a failed hook Job (Job Failed).- Services stay at zero replicas after the command returns.
- A retry after you changed the chart or values is refused by the maintenance hook.
Collect this before you contact support:
helm history xberg-enterprise -n xberg-enterprisehelm get hooks xberg-enterprise -n xberg-enterprise > hooks.yamlkubectl -n xberg-enterprise get jobs,podskubectl -n xberg-enterprise logs job/REPLACE_WITH_FAILED_JOB_NAME > hook.logkubectl -n xberg-enterprise get events --sort-by=.lastTimestamp > events.logAlso note the installed and target chart versions, and your values file with secrets removed. Then pause every reconciler of the release, leave the chart, values and database unchanged, and contact support. Before an upgrade that changes database privileges, see Upgrades and migrations.
Private MCP listener
Section titled “Private MCP listener”The chart can run a private MCP listener on loopback for local clients. It is off by default and adds no route. See Private MCP listener.
Upgrade and rollback
Section titled “Upgrade and rollback”Rollback needs stable external credential Secrets in both the current and the target revision. Use secrets.create=false and stable application, maintenance, migration, role-admin and vector-worker Secret references, and keep their values available throughout the operation. Embedded chart credentials block rollback.
A values-only rollback validates the existing broker contract and the desired schema before it runs the normal planner. It does not reverse broker ownership or widen migration privileges.
To upgrade:
- Back up the database and object store. See Backup and restore.
- Review the target release’s image versions and migration notes, and render the target chart with your values.
- Run
helm upgradewith the same wait options and repeat the adapter-specific checks above. - Confirm that hooks and workloads succeed, run
helm test, and verify an authenticated extraction with a non-sensitive document.
See Upgrades and migrations for the version policy.
Helm rollback cannot undo database data changes. Before you cross a schema-ownership boundary, stop and contact support for a version-specific privileged rollback plan. This guide does not authorize a one-step rollback across that boundary. Keep old image and chart versions and database backups until you accept the upgrade.
A support-coordinated ownership rollback needs one more precondition. Any NetworkPolicy of your own that selects migration hooks must permit your cluster’s exact Kubernetes API destination CIDRs and TCP ports, as enforced after Service address translation. Apply and verify that access first, do not open all private ranges, and remove temporary allowances after acceptance.
Next steps
Section titled “Next steps”Plan recovery with Backup and restore before you go to production, connect your observability backends as described in Observability, and register webhooks for result delivery. Then run the quickstart against your new deployment.