Migrate from Koldan 9 to Koldan 10

This procedure upgrades a Helm installation from Koldan 9.1.6 to Koldan 10. Perform it during a maintenance window as it requires downtime. Koldan 10 also updates Temporal and removes the bundled Elasticsearch and ZooKeeper components.

Koldan 10 recommends PostgreSQL 18, but Keep PostgreSQL on version 16 for this migration. Optionally upgrade PostgreSQL separately after Koldan 10 is stable; do not combine the PostgreSQL major-version change with this procedure.

Before the maintenance window

1. Rehearse the upgrade with a restored copy of production data and the production dependency topology.
2. Obtain the Koldan 10 chart, application images, and release notes from the same release.
3. Build a new operator values file from the Koldan 10 defaults. Do not use --reuse-values and do not copy the complete Koldan 9 values file forward.
4. Record the existing Temporal persistence settings, especially both database names, credentials, and namespace retention.

5. Take a coordinated, restorable backup of:

6. the Koldan PostgreSQL database;

7. the Keycloak database when Keycloak is managed with Koldan;
8. both Temporal databases, normally temporal and temporal_visibility;
9. Koldan object storage;
10. Elasticsearch data if it must be retained for audit or recovery.

Keep the backups until the Koldan 10 recovery window has ended.

Prepare PostgreSQL

Koldan 10 requires the vector and pg_trgm extensions in the Koldan database. Create them as a database administrator before starting the Helm upgrade so that the Koldan runtime login does not need extension-management privileges:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

Migrate the Temporal values

Koldan 10 includes a newer Temporal subchart and Temporal Server. Preserve the existing SQL stores; do not create new Temporal databases or change the history shard count.

Store Temporal database password in a stable Kubernetes Secret before the upgrade. Use new Secret names that are not owned by the Koldan Helm release, or use the site's existing external-secret mechanism. The secret must contain a password key. For example:

kubectl --namespace <namespace> create secret generic <release>-temporal \
  --from-file=password=/secure/path/temporal-password

Protect and remove the local password files according to the site's credential-handling procedure.

Configure the Koldan 10 values with the existing databases and the new Secrets:

temporal:
  install: true
  server:
    config:
      persistence:
        numHistoryShards: 512 # Use the existing value; do not change it.
        datastores:
          default:
            sql:
              createDatabase: false
              manageSchema: true
              pluginName: postgres12
              driverName: postgres12
              databaseName: temporal
              connectAddr: postgresql:5432
              connectProtocol: tcp
              user: koldan
              existingSecret: <release>-temporal
              secretKey: password
          visibility:
            sql:
              createDatabase: false
              manageSchema: true
              pluginName: postgres12
              driverName: postgres12
              databaseName: temporal_visibility
              connectAddr: postgresql:5432
              connectProtocol: tcp
              user: koldan
              existingSecret: <release>-temporal
              secretKey: password

Replace the example addresses, users, database names, Secret names, and shard count with the current installation's values. Preserve every existing Temporal namespace and its retention setting. If Temporal is managed outside the Koldan chart, upgrade it through its owning procedure and confirm compatibility with the Koldan 10 release before continuing.

Prepare the Koldan 10 values

Apply supported site-specific settings to a clean copy of the Koldan 10 values. In addition to the PostgreSQL and Temporal settings above:

• pin all Koldan images to the Koldan 10 release version or digest;
• preserve Keycloak, object-storage, TLS, ingress, resource, placement, and pull-secret settings
• remove the old elasticsearch and zookeeper sections (do not add replacement Elasticsearch or ZooKeeper endpoints; Koldan 10 does not use them)
• review all renamed or removed values against the Koldan 10 chart defaults and release notes.

Lint and render the exact target chart and values:

helm lint ./koldan-10 --values koldan-10-values.yaml

helm template <release> ./koldan-10 \
  --namespace <namespace> \
  --values koldan-10-values.yaml \
  > rendered-koldan-10.yaml

Upgrade

1. Block new HTTP and gRPC traffic.
2. Allow active requests and workflows to reach a safe stopping point.
3. Take the final coordinated backup.
4. Run the upgrade:

helm upgrade <release> ./koldan-10 \
  --namespace <namespace> \
  --values koldan-10-values.yaml \
  --atomic \
  --wait \
  --timeout 30m

--atomic restores Kubernetes resources when the rollout fails. It does not reverse application, Temporal, or identity database migrations. Do not use a Helm rollback after the Koldan 10 migrations have started unless Koldan Support confirms that the current persistent state is backward compatible. Correct forward or restore the coordinated backup instead.

Verify Koldan 10

Before restoring traffic, confirm all the following:

1. All required Koldan, PostgreSQL, Keycloak, object-storage, and Temporal pods are Ready and stable.
2. Koldan workloads use the intended Koldan 10 image and no old Koldan pod remains.
3. Temporal frontend is healthy, both SQL schemas completed their upgrade, and existing workflow backlog is processing.
4. Elasticsearch and ZooKeeper workloads, pods, and Services are absent.
5. Login and authorization succeed.
6. Representative existing data can be read, and a representative create/read operation succeeds through the public HTTP or gRPC endpoint.

Restore traffic and monitor error rate, latency, workflow backlog, database load, restarts, and storage growth through a normal traffic cycle.

Prune Elasticsearch and ZooKeeper storage

The Koldan 10 Helm upgrade removes Elasticsearch and ZooKeeper workloads and Services. Kubernetes normally retains PVCs created for their StatefulSets. Retain those PVCs until Koldan 10 has passed verification and the backup and audit-retention requirements are satisfied.

Confirm that no Elasticsearch or ZooKeeper workload remains, identify the retained PVCs, and delete only the confirmed PVCs:

kubectl --namespace <namespace> delete pvc \
  <elasticsearch-pvc> \
  <zookeeper-pvc>