Updates

Upgrading a self-hosted Prisme.ai platform to a new release always has two phases, in this order:

1. Services

Bump the image tag of the 5 core microservices (and the 3 apps services) in your Helm values, then helm upgrade.

2. Products

From the Platform workspace, pull the product workspaces (Agent Creator, Knowledges, Governe, LLM Gateway, Storage, …) group by group: base1 → base2 → extended → one-product.

The order is not optional. The product workspaces are bundled inside the prismeai-workspaces image of the release you are upgrading to. Pulling them before every service runs the target tag imports workspaces that the running runtime cannot execute.

A third step, verifying the imports, confirms the upgrade actually succeeded: an import that reports zero errors is what tells you the release is live.

Before you start

Read the release notes

Check What’s New for the target version, and the Prisme.ai releases page for the full list of available tags.Look specifically for: database version requirements, new mandatory environment variables, breaking changes in workspace configuration, and anything flagged as requiring a manual action.

Versions are named vMAJOR.MINOR.PATCH since v27 (for example v27.4.2). Releases before v27 used a date-stamped form such as v26.03.161453.

Back up your databases and storage

Back up everything the platform owns before touching the tags:

Permissions store, users store and collections store (MongoDB or PostgreSQL)
Elasticsearch or OpenSearch (events, and RAG indexes if self-hosted)
Redis (broker streams and caches)
Object storage buckets (workspace models, uploads)

Full procedures are on the Backup & Restore page.

Check database compatibility

Confirm your database engines still meet the minimum versions of the target release (see the cards in Database compatibility below). Upgrading an engine and the platform in the same maintenance window makes failures much harder to attribute; do them separately.

Record your rollback point

Note the tags you are currently running and the current Helm revisions:

# Current image tags per pod
kubectl get pods -n prismeai-core \
  -o custom-columns='POD:.metadata.name,IMAGE:.spec.containers[*].image'

# Current Helm revisions
helm history prismeai-core -n prismeai-core
helm history prismeai-apps -n prismeai-apps

Keep the output. You need it for the rollback procedure.

Push any local changes on product workspaces

Bulk import always runs with discardLocalChanges: true. Any edit you made in Builder on a product workspace (LLM Gateway, Storage, Governe, Agent Creator, Secure-chat Agent, …) is overwritten by the upgrade.If you customized one of them, push it to your own Git repository first so you can replay the change afterwards. See Versioning.

1. Upgrade the platform services

The services to update

Prisme.ai runs as two Helm releases. Every image tag in both must move to the target release.

Release / namespace	Services
`prismeai-core`	`prismeai-api-gateway`, `prismeai-console`, `prismeai-workspaces`, `prismeai-runtime`, `prismeai-events`
`prismeai-apps`	`prismeai-functions`, `prismeai-crawler`, `prismeai-searchengine`

See Platform microservices for what each one does.

Bump the tags

In prismeai-core-values.yaml, set the same tag on all five core services:

prismeai-api-gateway:
  image:
    tag: "v27.4.2"

prismeai-console:
  image:
    tag: "v27.4.2"

prismeai-workspaces:
  image:
    tag: "v27.4.2"

prismeai-runtime:
  image:
    tag: "v27.4.2"

prismeai-events:
  image:
    tag: "v27.4.2"

Do the same for prismeai-functions, prismeai-crawler and prismeai-searchengine in prismeai-apps-values.yaml.

Only the tag changes on a routine upgrade. If you are still coming from a pre-v27 platform, prismeai-console also needs its image.repository switched to the unified platform image; follow Migration v27 instead of this page.

All services must carry the same tag. Mixing versions leaves the runtime executing DSUL models or emitting events that another service in a different version does not understand. Symptoms are subtle: automations that silently do nothing, missing activity events, failed workspace saves.

If you pin tags through a GitOps pipeline, use a single YAML anchor or a templated variable so a release bump is one edit instead of eight. This is also what makes it obvious that a service was left behind.

Deploy

helm repo update prismeai

helm -n prismeai-core upgrade prismeai-core prismeai/prismeai-core \
  -f prismeai-core-values.yaml

helm -n prismeai-apps upgrade prismeai-apps prismeai/prismeai-apps \
  -f prismeai-apps-values.yaml

Keep global.secrets.allowCreation: false in your values, as set after the first install. See Secret bootstrapping.

Watch the rollout

kubectl get deploy -n prismeai-core -o name \
  | xargs -n1 -I{} kubectl rollout status {} -n prismeai-core --timeout=10m

kubectl get pods -n prismeai-core -w

If a pod crash-loops, read the logs of the previous container instance:

kubectl logs <pod> -n prismeai-core --previous
kubectl describe pod <pod> -n prismeai-core | tail -30

Confirm every service is on the target tag

This is the gate before phase 2. Verify it explicitly rather than assuming the rollout was complete:

kubectl get pods -n prismeai-core \
  -o custom-columns='POD:.metadata.name,IMAGE:.spec.containers[*].image'

kubectl get pods -n prismeai-apps \
  -o custom-columns='POD:.metadata.name,IMAGE:.spec.containers[*].image'

Then check platform health:

Call the readiness API: curl -H "Authorization: Bearer YOUR_JWT" https://api.your-domain.com/v2/readiness should return "status": "ready".
Open Govern → Infrastructure and run the Test buttons in the Services block.

Only move on once all eight services report the new tag and readiness is green.

2. Update the products

The products are shipped as workspaces and updated through the Platform workspace bulk import, in four sequential groups.

base1

Foundation apps (Custom Code, Prisme.ai API, …).

base2

Extended base (Crawler, RedisSearch, …).

extended

Legacy AI products (Knowledges, AI Store, …): still required as a dependency for the platform products. They will disappear in a future release.

one-product

Main platform products (LLM Gateway, Storage, Governe, Agent Creator, …).

Import the groups one at a time, in order, and wait for workspaces.bulkImport.completed with no errors before starting the next one. Each group depends on the previous one.

From the UI

Open the Platform workspace

In Builder, open the Platform workspace. It is only visible to super admins.

Trigger the pull

Navigate to Settings → Versions → Platform Pull, then select the Release vXXX platform repository matching the version you just deployed.

Select the group and start the import

Pick base1, start the import, and close the modal.

Monitor progress

From the Activity feed of the Platform workspace, wait for the workspaces.bulkImport.completed event and check that its errors list is empty.

Repeat for the next group

Import the remaining groups in order: base2 → extended → one-product.

From the API

The same import can be triggered without the UI:

curl -X POST "${API_URL}/v2/workspaces/platform/versions/latest/pull" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"repository": {"id": "release"}, "groups": ["base1"]}'

Repeat with base2, extended, then one-product. If the HTTP request times out, the response returns { "processing": true } and the import keeps running; the final result is in the workspaces.bulkImport.completed event.

What the import actually does

Behavior that matters specifically on an upgrade (full mechanics in Bulk import):

Already up-to-date workspaces are skipped. The platform compares version.name from the repository’s .import.yml with the workspace’s lastPull.version. On a patch release, most workspaces are legitimately reported as skipped. Pass forceReimport: true to reimport them anyway.
Local changes are discarded. Imports always run with discardLocalChanges: true.
Dependencies are ordered automatically. Workspaces are topologically sorted through their dependsOn declarations inside each group.
Only one bulk operation at a time. The Platform workspace holds a cluster-wide write lock for the duration of the import.

You can automate this on every pod start with STARTUP_IMPORT_GROUPS and STARTUP_IMPORT_REPOSITORY, which makes the product update part of the deployment itself. See Automatic import at startup.

3. Verify the imports

An upgrade is only confirmed once every group imported without errors. There are two places to check.

The Platform workspace activity feed

All bulk import events are emitted to the Platform workspace and visible from its Activity view:

Event	What it tells you
`workspaces.bulkImport.started`	The list of workspaces the import will process
`workspaces.bulkImport.progress`	Per-workspace status (`imported`, `skipped` or `error`), file counts and percentage
`workspaces.bulkImport.completed`	The final summary: created, updated, skipped, errors, total duration

Open the workspaces.bulkImport.completed event and read its payload. An empty errors list is the confirmation that the group imported correctly. If errors is populated, each entry names the workspace and the reason; fix the cause and re-import that group before moving on. Individual workspace events (workspaces.imported, workspaces.versions.progress) are also emitted in each product workspace’s own activity feed if you need per-workspace detail.

The workspaces service logs

The same detailed error list is written by the service that performs the import:

# Follow the import live
kubectl logs -n prismeai-core deploy/prismeai-core-prismeai-workspaces -f

# Or review the last lines after the fact
kubectl logs -n prismeai-core deploy/prismeai-core-prismeai-workspaces --tail=500

If your Helm release is not named prismeai-core, the deployment name follows the <release>-prismeai-workspaces pattern. List it with kubectl get deploy -n prismeai-core | grep workspaces.

Use the logs when the activity feed is unavailable (for example when the import was triggered at startup through STARTUP_IMPORT_GROUPS, before anyone could open the UI), or when an import fails early enough that no completed event is emitted.

Functional checks

Once the four groups are in, confirm the platform behaves:

Readiness and infrastructure

Call /v2/readiness again, then run the Test buttons in Govern → Infrastructure, including the Vector store block.

Models

In Govern → Models, open one completion model and one embedding model and click Test.

Products

Confirm every enabled product still appears in the left menu, then open Agent Creator and run an existing agent end to end, including a document upload if you use RAG.

Custom code

If you use Custom Code apps, run one automation that calls them: dependency installation restarts after an import.

Database compatibility

Per-engine upgrade notes and version requirements live on the dedicated database pages:

PostgreSQL

Minimum 12+ with sslmode=require.

MongoDB

Minimum 6+. Schema migrations run automatically on backend startup.

Elasticsearch or OpenSearch

Minimum Elasticsearch 8.x / OpenSearch 2.x. Some upgrades require reindexing.

Redis

Minimum 6.2+. Cluster mode supported since Prisme.ai v3.2.

Object storage (S3-compatible, Azure Blob, GCS) follows the provider’s standard lifecycle; verify bucket permissions remain consistent after an upgrade.

Managing the upgrade with Terraform

If your Helm releases are declared as helm_release resources, bump the chart version there instead of running helm upgrade by hand:

resource "helm_release" "prismeai_core" {
  name       = "prismeai-core"
  repository = "https://helm.prisme.ai/charts"
  chart      = "prismeai-core"
  version    = "X.Y.Z"
  namespace  = "prismeai-core"

  # Your values, including the image tags
}

terraform init -upgrade
terraform plan
terraform apply

Review the plan output before applying: a chart version bump can rename or replace resources. Terraform only covers phase 1; the product update in phase 2 still goes through the Platform workspace.

Rollback

Roll the services back

Either roll back the Helm releases:

helm history prismeai-core -n prismeai-core
helm rollback prismeai-core <revision> -n prismeai-core

helm history prismeai-apps -n prismeai-apps
helm rollback prismeai-apps <revision> -n prismeai-apps

Or set the previous tags back in your values files and re-run helm upgrade. Prefer this second option when your values are the source of truth in Git.

Re-pull the products at the previous release

Open the Platform workspace and pull the four groups again, in order (base1 → base2 → extended → one-product), selecting the previous release repository.Up-to-date workspaces are skipped by default, which would leave the newer versions in place. Force the reimport through the API so the older versions are actually written back:

curl -X POST "${API_URL}/v2/workspaces/platform/versions/latest/pull" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"repository": {"id": "release"}, "groups": ["base1"], "forceReimport": true}'

Restore databases only if needed

Restore from backup only if the release ran schema migrations you need to undo. Rolling back the images alone does not revert a migration. See Backup & Restore.

Verify

Re-run the checks in Verify the imports.

Troubleshooting

Bulk import reports errors

Open the workspaces.bulkImport.completed event in the Platform workspace activity feed and read the errors payload, or check prismeai-workspaces logs. Resolve missing dependencies or slug conflicts, then re-import the failed group. Do not start the next group until the failed one completes cleanly.

Could not rename workspace slug ... as it is already used

A workspace in the release collides with an existing one. Rename your own workspace, or exclude the conflicting index file from the import. Details in Deployment troubleshooting.

Every workspace is reported as skipped

Expected on a patch release where the product workspaces did not change: the platform compares the repository version.name with lastPull.version. If you need to force a reimport, pass forceReimport: true in the pull payload.

Automations do nothing, or activity events are missing

Almost always a mixed-version deployment. Re-check that all five core services and the three apps services report the same image tag, and that no pod is still running an old ReplicaSet.

Pods stay in ImagePullBackOff after the bump

The tag does not exist in the registry, or the registry secret is missing. Check the tag against the releases page. For the prismeai-apps namespace, recreate the pull secret:

kubectl create secret docker-registry registry-secret \
  --docker-server=registry.gitlab.com \
  --docker-username=YOUR_USERNAME \
  --docker-password=YOUR_TOKEN \
  --namespace prismeai-apps

Custom Code apps fail after the import

Check prismeai-functions logs for dependency installation errors. If dependencies are still installing or missing, re-save the affected Custom Code app to restart installation.

A product is missing from the menu

A customization disappeared after the upgrade

Bulk import discards local changes. Re-apply the change from the Git repository you pushed it to, or re-run the workspace automation that produced it (for example update-agent for the Secure Chat agent, see Install products).

Next steps

Backup & Restore

Create and manage backups before every upgrade.

Install products

The first-install reference for the four workspace groups and post-install configuration.

Migration v27

Coming from legacy products? Follow the migration guide instead.

Scaling

Scale the platform to meet growing demand.

Overview

Installation

Databases

Entreprise Services

Operations

1. Services

2. Products

Before you start

1. Upgrade the platform services

The services to update

Bump the tags

Deploy

Watch the rollout

Confirm every service is on the target tag

2. Update the products

base1

base2

extended

one-product

From the UI

From the API

What the import actually does

3. Verify the imports

The Platform workspace activity feed

The workspaces service logs

Functional checks

Database compatibility

PostgreSQL

MongoDB

Elasticsearch or OpenSearch

Redis

Managing the upgrade with Terraform

Rollback

Troubleshooting

Next steps

Backup & Restore

Install products

Migration v27

Scaling

1. Services

2. Products

​Before you start

​1. Upgrade the platform services

​The services to update

​Bump the tags

​Deploy

​Watch the rollout

​Confirm every service is on the target tag

​2. Update the products

base1

base2

extended

one-product

​From the UI

​From the API

​What the import actually does

​3. Verify the imports

​The Platform workspace activity feed

​The workspaces service logs

​Functional checks

​Database compatibility

PostgreSQL

MongoDB

Elasticsearch or OpenSearch

Redis

​Managing the upgrade with Terraform

​Rollback

​Troubleshooting

​Next steps

Backup & Restore

Install products

Migration v27

Scaling

Before you start

1. Upgrade the platform services

The services to update

Bump the tags

Deploy

Watch the rollout

Confirm every service is on the target tag

2. Update the products

From the UI

From the API

What the import actually does

3. Verify the imports

The Platform workspace activity feed

The workspaces service logs

Functional checks

Database compatibility

Managing the upgrade with Terraform

Rollback

Troubleshooting

Next steps