Skip to content

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.

  1. Prepare the cluster
  2. Get the chart
  3. Prepare the database
  4. Create the Secrets
  5. Configure the values
  6. Install and verify
  7. Create a project and an API key
  • Helm 4, kubectl, yq and curl on 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/amd64 or linux/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, is linux/amd64 only. Schedule it on amd64 nodes, for example with workerGpu.nodeSelector."kubernetes.io/arch": amd64.
  • PostgreSQL 15 to 18 (managed or self-hosted) with pgvector 0.8.0 or newer. pgvectorscale is optional; see PostgreSQL extensions.
  • psql and the GNU timeout command 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 imagePullSecrets or node identity.
  • KEDA, either preinstalled or bundled, and Argo Rollouts or the native Deployment adapter; see Deployment adapter.
  • Prometheus Operator, if you want ServiceMonitor resources. 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:

Terminal window
kubectl get crd scaledobjects.keda.sh
kubectl get crd rollouts.argoproj.io
kubectl get nodes -o wide

The 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.

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: RollingUpdate

Native 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.

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:

Terminal window
export ENTERPRISE_CHART=oci://us-central1-docker.pkg.dev/xberg-public-assets/helm-charts/xberg-enterprise
export VERSION=REPLACE_WITH_RELEASE_VERSION
helm pull "$ENTERPRISE_CHART" --version "$VERSION" --untar
export ENTERPRISE_CHART_DIR="$PWD/xberg-enterprise"
helm show values "$ENTERPRISE_CHART_DIR" > values.yaml

If 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:

Terminal window
kubectl create namespace xberg-enterprise
kubectl -n xberg-enterprise create secret docker-registry xberg-registry \
--docker-server=REPLACE_WITH_REGISTRY_HOST \
--docker-username=REPLACE_WITH_USERNAME \
--docker-password=REPLACE_WITH_PASSWORD

Then 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:

Terminal window
helm show chart "$ENTERPRISE_CHART_DIR" | grep -E '^(name|version):'
test -f "$ENTERPRISE_CHART_DIR/charts/_distribution/files/pro-db-bootstrap.sh" && echo OK

The chart reports name: xberg-enterprise and your version, and the second command prints OK.

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 pgvector preinstalled. pgvectorscale is not available, so pin hnsw, 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 pgvectorscale for your engine version.
  • Azure Database for PostgreSQL enables extensions in the portal or through Terraform. pgvector is 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.

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_PASSWORD
  • POSTGRES_MAINTENANCE_PASSWORD
  • POSTGRES_SCHEMA_OWNER_PASSWORD
  • POSTGRES_MIGRATION_PASSWORD
  • POSTGRES_ROLE_ADMIN_PASSWORD
  • POSTGRES_INDEX_WORKER_PASSWORD
  • POSTGRES_VECTOR_BROKER_PASSWORD
  • POSTGRES_PHYSICAL_MIGRATION_PASSWORD
Terminal window
export PGPASSWORD="$POSTGRES_PASSWORD"
export PRO_DB_BOOTSTRAP_MODE=standard
export PRO_DB_BOOTSTRAP_PHASE=all
export PRO_DB_INITIALIZE_SCHEMA=true
export PRO_DB_DEFER_CLAIMS_ENABLE=true
export SCHEMA_DIRECTORY="$ENTERPRISE_CHART_DIR/charts/_distribution/files"
sh "$SCHEMA_DIRECTORY/pro-db-bootstrap.sh"
export MIGRATION_PLAN_DATABASE=xberg_schema_plan
export PLANNING_DATABASE_BOOTSTRAP=true
export 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:

Terminal window
PGPASSWORD="$POSTGRES_APPLICATION_PASSWORD" \
psql -h "$PGHOST" -p "$PGPORT" -U xberg_app -d "$POSTGRES_DB" -c 'SELECT current_user'

psql prints xberg_app.

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-url
global:
maintenance:
databaseUrlSecret:
name: xberg-enterprise-secrets
key: maintenance-database-url
natsCredentials:
create: false
existingSecret: xberg-nats
migrations:
planningDatabaseBootstrap: false
databaseUrlSecret:
name: xberg-schema-migrator
key: database-url
roleAdminDatabaseUrlSecret:
name: xberg-role-admin
key: database-url
vectorIndexWorker:
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-url
tests:
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:

Terminal window
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:

Terminal window
kubectl -n xberg-enterprise get secrets

The 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:

  1. Add the bootstrap credential to the server and Secret.
  2. Run the provisioning command against the existing resources.
  3. 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.

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.

With <component>.networkPolicy.enabled: true, the chart’s egress rules cover same-namespace dependencies, cluster DNS and public HTTPS.

  • The worker, workerGpu and webhooks policies also admit public TCP 80, because crawl seeds and webhook receivers answer on plain HTTP.
  • The backend policy 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.

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.

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.ingress owns the control-plane paths (/auth/config, /auth/login, /auth/account, /auth/profile, /healthz, /readyz, /api-doc).
  • backend.gatewayApiPaths: true forwards the data-plane prefixes in backend.apiGatewayPathPrefixes to 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.

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.

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:

Terminal window
helm lint --strict "$ENTERPRISE_CHART_DIR" -f values.yaml
helm template xberg-enterprise "$ENTERPRISE_CHART_DIR" \
-n xberg-enterprise -f values.yaml > rendered.yaml && echo OK

helm lint reports 0 chart(s) failed, and the second command prints OK. Store rendered.yaml securely, because chart-created Secrets appear in it.

Install the chart and check the workloads for your adapter. Run these commands with shell error checking enabled:

Terminal window
set -e
helm upgrade --install xberg-enterprise "$ENTERPRISE_CHART_DIR" \
-n xberg-enterprise -f values.yaml --server-side=false --wait=legacy --wait-for-jobs --timeout 110m
adapter="$(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 ;;
esac
helm test xberg-enterprise -n xberg-enterprise --logs --timeout 5m

Helm 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:

Terminal window
helm status xberg-enterprise -n xberg-enterprise | grep -E '^STATUS'

The output is STATUS: deployed.

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:

Terminal window
export XBERG_URL=https://REPLACE_WITH_API_DOMAIN
export XBERG_API_KEY=REPLACE_WITH_PROJECT_API_KEY
curl --fail -H "Authorization: Bearer $XBERG_API_KEY" "$XBERG_URL/v1/jobs"

The response is a JSON job list. Continue with the quickstart.

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.

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 --install ends 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:

Terminal window
helm history xberg-enterprise -n xberg-enterprise
helm get hooks xberg-enterprise -n xberg-enterprise > hooks.yaml
kubectl -n xberg-enterprise get jobs,pods
kubectl -n xberg-enterprise logs job/REPLACE_WITH_FAILED_JOB_NAME > hook.log
kubectl -n xberg-enterprise get events --sort-by=.lastTimestamp > events.log

Also 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.

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.

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:

  1. Back up the database and object store. See Backup and restore.
  2. Review the target release’s image versions and migration notes, and render the target chart with your values.
  3. Run helm upgrade with the same wait options and repeat the adapter-specific checks above.
  4. 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.

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.