Helm chart - FlowX.AI

FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

This page covers the Helm side of an upgrade from FlowX.AI 5.9.x to 6.0.0 for an installation that already runs on the flowx-ai Helm chart. The deployment guidelines list every change in detail. This page puts the ones that need action in the order you do them.

If you still run the per-service charts or the ai-platform umbrella chart, move to the flowx-ai chart on 5.9.x first, as described in Migrate self-hosted FlowX.AI to the flowx-ai Helm chart. That migration recreates every workload. Doing it separately keeps the 6.0.0 upgrade a single helm upgrade of one release.

Before you begin

Read the FlowX.AI 6.0.0 release notes and deployment guidelines.
Get pull access to the flowx-ai chart at the chart version for 6.0.0. The chart version is the platform release.
Take a backup of PostgreSQL, MongoDB, the object store, and the Qdrant collections right before the upgrade.
If you run a container app with a FlowX renderer SDK, plan its upgrade with the renderer SDK guides.

The commands on this page read the namespace from NS:

export NS={your-flowx-namespace}

Update your values

Set every group flag explicitly

Don’t rely on the chart’s group defaults. Set all four group flags in your values, using one of these combinations:

To install	`core`	`base`	`devtime`	`runtime`
Core services only	`true`	`false`	`false`	`false`
Core, base, and devtime services	`true`	`true`	`true`	`false`
Core, base, and runtime services	`true`	`true`	`false`	`true`
All services	`true`	`true`	`true`	`true`

base is the AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and Qdrant. The devtime and runtime services call it, so turn base on whenever either of them is on. The chart doesn’t check this for you.For example, to install the core, base, and runtime services:

groups:
  core:
    enabled: true
  base:
    enabled: true
  devtime:
    enabled: false
  runtime:
    enabled: true

See AI service groups in the Helm chart for the services in each group, and Service groups for how group and service flags combine.

Provision databases and secrets for the services you turn on

In 6.0.0, these services need their own database users and secrets: agent-builder, dynamic-classifier, and harness in PostgreSQL, and designer-user in MongoDB. Create them before the upgrade for every service your group flags turn on. designer-user is in the core group, so it always needs its database.The keycloak-flowx-realm-clients secret needs four new client secret keys, whatever your group flags. authorization-system reads all four at startup and, when it has Keycloak admin access (the default), creates the matching service-account clients with those secrets. If a key is missing, its database migration fails and authorization-system doesn’t start. Without Keycloak admin access, create the four clients in Keycloak yourself.See New databases and secrets for the user, secret, key, and client names.

Grant process-engine read access to the integration-designer bucket

process-engine now reads Kafka payloads that integration-designer stores in its bucket. Give the process-engine credentials s3:GetObject on that bucket. See New databases and secrets for the secret names.

Set a bucket name for dynamic-classifier

If you turn on dynamic-classifier, set its bucket under services.dynamic-classifier.component.s3.applicationFileStorage.bucketName. The chart sets no bucket names, as described in Migrate S3 buckets. dynamic-classifier also stores data on a 20Gi ReadWriteOnce volume, so your cluster needs a storage class that can provide one.Unlike the Qdrant volumes, this claim is part of the Helm release. helm uninstall, or deleting the Argo CD Application with cascading deletion, deletes it, and with a Delete reclaim policy its data too.

Move callers off the removed admin Ingress routes

If you route with Kubernetes Ingress, the chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier, and the upgrade deletes the existing ones. ai-gateway keeps its own. Platform services and frontends don’t use these routes. If anything outside the cluster calls one of these paths on the admin host, such as /speech-to-text, move it to the service’s in-cluster address before you upgrade.Installations that use the Gateway API aren’t affected.

Allow private MongoDB hosts

nosql-db-runner now applies its host restriction to external MongoDB connections. Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to FLOWX_SSRFALLOWEDHOSTS on nosql-db-runner. See nosql-db-runner host restrictions.

Trust your IMAP servers' certificates

email-gateway now verifies the certificate of every IMAPS server it connects to. Email triggers that read from a server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server’s CA to the email-gateway trust store, or list the host in EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS. See IMAPS certificate verification.

Keep the management port private

advancing-controller no longer reads MANAGEMENT_SECURITY_ENABLED, and the actuator endpoints on its management port, 8081, including Prometheus, answer without authentication. Check that no public Ingress or Gateway route exposes that port. See Removed environment variables.

Set the personal-data encryption key

Since 5.12, integration-designer needs FLOWX_PII_ENCRYPTION_MASTER_KEY for the Mask Personal Data and Restore Personal Data nodes. The variable has no default and the chart doesn’t set it, so without it those nodes fail when a workflow runs them. Store a strong random value in a secret under the key FLOWX_PII_ENCRYPTION_MASTER_KEY, and load the secret into integration-designer:

services:
  integration-designer:
    extraEnvVarsSecret: {your-pii-secret-name}

Keep the value identical on every pod and stable over time: changing it invalidates every in-flight placeholder map. See personal-data encryption master key.

Choose how Elasticsearch replicates new indices

Since 5.13, process-engine and audit-core create new indices with the Elasticsearch auto_expand_replicas setting 0-1, which overrides FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS. On a cluster with two or more data nodes, the replica roughly doubles the disk space these indices use. To keep a fixed replica count instead, turn auto-expansion off on both services:

services:
  process-engine:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
  audit-core:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"

See Elasticsearch replica auto-expansion.

Create the new Kafka topics

New capabilities since 5.9.x depend on new Kafka topics. Create them before you upgrade. The 6.0.0 deployment guidelines list the topics added since 5.13. From 5.9.x, also create the topics added in the 5.10, 5.11, 5.12, and 5.13 feature releases, listed in each release’s deployment guidelines.If the chart creates your topics, add the new names to the list under global.flowx.kafka.topics.topics. The chart creates topics only when global.flowx.kafka.topics.enabled is true, as Strimzi KafkaTopic resources with 3 partitions and 3 replicas unless you set other values under global.flowx.kafka.topics.defaults:

global:
  flowx:
    kafka:
      topics:
        enabled: true
        topics:
          - ai.flowx.build.deployment-failed.v1

Render and compare

Render the 6.0.0 chart with your updated values before you upgrade, and compare it with what runs today:

helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml

Check that the rendered Deployments are the services you expect. A missing AI base service, or an AI runtime service you didn’t plan for, means a group flag isn’t set. The render fails if your values still contain top-level devtime or runtime keys, or service keys outside services. See Render and compare for commands that compare environment variables per Deployment.

Upgrade

Run helm upgrade on your flowx-ai release with the 6.0.0 chart version and your updated values:

helm upgrade {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml

dynamic-classifier uses the Recreate deployment strategy, so its old pod stops before the new one starts.

After the upgrade

Upgrading from 5.9.5 or earlier: re-publish builds that were waiting for a retry. The retry queue for failed build deployments moves from Redis to PostgreSQL, and deployments waiting in Redis are not moved. 5.9.6 already uses the PostgreSQL queue. See Failed deployments retry from PostgreSQL.
Check component versions. In FlowX.AI Designer, go to Platform Status and compare the versions with the deployment guidelines.
Check files from before the upgrade. Open a process attachment, a media library asset, and a knowledge base document, and confirm they load. A bucket-not-found error in the logs points at a bucket name that didn’t carry over.
Update name placeholders. data-privacy now masks names with gendered placeholders, such as <NAME_F_1>. Update prompts or scripts that match the old form. See Name placeholders in data-privacy.
Expect a new workspace role name. Users and groups with the Workspace operations editor role now have the Workspace corrective actions editor role, and keep access to process instance migration and move token. See Workspace operations editor role replaced.

Deployment guidelines v6.0.0

Component versions and every deployment-level change in 6.0.0

Migrate to the flowx-ai Helm chart

Move from the per-service or ai-platform charts to the single chart

​Before you begin

​Update your values

​Render and compare

​Upgrade

​After the upgrade

​Related resources

Deployment guidelines v6.0.0

Migrate to the flowx-ai Helm chart

Before you begin

Update your values

Render and compare

Upgrade

After the upgrade

Related resources