Upgrade Charmed Temporal from 1.23/stable to 1.31/stable

This guide describes how to upgrade an existing Charmed Temporal deployment from 1.23 to 1.31 using charms published on Charmhub.

Temporal Server and Admin must be upgraded sequentially through each minor version. For each upgrade, refresh Temporal Admin first to perform the database schema migrations, then refresh Temporal Server.

The Temporal UI and Worker upgrades are performed after Server and Admin reach version 1.31.

Important: Database schema migrations are forward-only. There is no supported in-place downgrade. Always create and verify a PostgreSQL backup before upgrading.

Step 1: Check the current deployment

Verify that the Temporal Server and Admin charms are running version 1.23:

juju status

Identify the deployed application names, channels, revisions, and Ubuntu bases.

The commands below assume the following application names:

• temporal-admin-k8s
• temporal-k8s
• temporal-ui-k8s
• temporal-worker-k8s

Replace these with your actual application names if different.

Step 2: Back up PostgreSQL

Before upgrading, follow the PostgreSQL K8s backup documentation to create and verify a restorable backup.

Where possible, stop new workflow executions, allow running workflows to finish, and shut down workers gracefully before taking the backup.

Repeat this backup step before each minor-version upgrade.

Step 3: Upgrade sequentially from 1.23 to 1.30

Upgrade through the following versions in order:

1.24 → 1.25 → 1.26 → 1.27 → 1.28 → 1.29 → 1.30

Before starting, verify that the corresponding channels are published for both Temporal Server and Admin on Charmhub. The examples below use the stable risk level; use the appropriate published risk level for your deployment.

For each target version:

3.1 Refresh Temporal Admin

For example, to upgrade to 1.24:

juju refresh temporal-admin-k8s \
  --channel 1.24/stable

Wait for Admin to complete its schema migration and return to active status.

juju status
juju debug-log --include temporal-admin-k8s/0

Verify that the logs show successful migration of both the main and visibility schemas. Some releases may have no pending SQL schema changes.

Do not proceed to the Server refresh if the Admin upgrade or schema migration fails.

3.2 Refresh Temporal Server

After Admin becomes active:

juju refresh temporal-k8s \
  --channel 1.24/stable

Wait for Temporal Server to become active:

juju status

Allow approximately 10 minutes for the History Service to load shards and update shard metadata before proceeding to the next version.

Repeat this process for each subsequent minor version (1.25 → 1.26 → 1.27 → 1.28 → 1.29 → 1.30), taking a PostgreSQL backup before each refresh and replacing 1.24/stable with the corresponding channel until both charms reach version 1.30.

Step 4: Upgrade from 1.30 to 1.31

Version 1.31 supports the transition to Ubuntu 26.04.

4.1 Refresh Temporal Admin

Create and verify another PostgreSQL backup.

juju refresh temporal-admin-k8s \
  --channel 1.31/stable \
  --base ubuntu@26.04

Wait for the charm to complete the upgrade hook and schema migration.

juju status
juju debug-log --include temporal-admin-k8s/0

Verify the following messages appear after the refresh:

Starting schema migration to 1.31.x
Schema db migrated using database user ...
Schema visibility migrated using database user ...

Do not proceed until both schemas have been successfully migrated and the Admin application is active.

4.2 Refresh Temporal Server

Once Admin is active and the database schemas are verified:

juju refresh temporal-k8s \
  --channel 1.31/stable \
  --base ubuntu@26.04

Wait for Server to become active and finish processing shard metadata.

juju status

Step 5: Upgrade Temporal UI

Once Server and Admin are running version 1.31, upgrade Temporal UI to the corresponding 1.31 channel.

juju refresh temporal-ui-k8s \
  --channel 1.31/stable \
  --base ubuntu@26.04

Wait for the UI to become active:

juju status

Verify that the UI workload is running the expected release, and confirm that the UI can connect to Temporal Server, display workflows, and access workflow execution details.

Step 6: Migrate Temporal Worker from 1.0 to 2.0

Worker 2.0 must be deployed as a new application rather than refreshed in place

6.1 Record the existing Worker configuration

Before migrating, inspect and preserve the current configuration, resources, and integrations.

juju config temporal-worker-k8s --format yaml \
  > worker-config-before-upgrade.yaml

juju resources temporal-worker-k8s
juju status --relations

Identify the OCI image containing the existing worker application.

kubectl get pod temporal-worker-k8s-0 \
  -o jsonpath='{range .spec.containers[*]}{.name}{": "}{.image}{"\n"}{end}'

Run the command in the model’s Kubernetes namespace.

Record the worker image, configured namespace, task queue, and any custom authentication, environment, or integration settings.

6.2 Deploy Worker 2.0 as a new application

Deploy Worker 2.0 alongside the existing Worker 1.0 application.

For example:

juju deploy temporal-worker-k8s temporal-worker-v2 \
  --channel 2.0/stable \
  --base ubuntu@24.04 \
  --resource temporal-worker-image=<worker-image> \
  --config namespace=temporal-system \
  --config queue=default

Replace <worker-image> with the OCI image containing your worker code. Ensure the image is accessible and compatible with Worker 2.0.

Use the namespace and task queue from your existing deployment rather than copying the example values blindly.

Restore any additional configuration needed by the worker.

6.3 Integrate Worker 2.0 with Temporal Server

juju integrate \
  temporal-k8s:temporal-host-info \
  temporal-worker-v2:temporal-host-info

Recreate any other required integrations that were present on Worker 1.0.

Wait for Worker 2.0 to become active.

juju status

Verify that the new worker is listening to the expected Temporal namespace and task queue.

6.4 Verify Worker 2.0

Because both worker applications may initially consume tasks from the same queue, first verify Worker 2.0 is healthy, then stop Worker 1.0 from polling.

For a single-unit Worker 1.0 deployment:

juju scale-application temporal-worker-k8s 0

Wait until the old worker unit has stopped.

Confirm that a workflow can be started and executed successfully through Worker 2.0, either through the Temporal Web UI or using the cli action on temporal-admin-k8s.

Since Worker 1.0 has been scaled to zero, successful workflow execution confirms that Worker 2.0 can process tasks against the upgraded Temporal Server.

Once the new Worker has been validated, the old Worker application can be removed as part of the migration cutover. Keep it available for recovery until validation is complete.

Step 7: Verify the complete upgrade

7.1 Check deployment status and charm bases

Check the final deployment status:

juju status

Confirm that:

• Temporal Admin and Server are running the expected 1.31 workload versions.
• Admin, Server, and UI are active/idle.
• Both database schemas have been migrated successfully.
• Temporal Server workload is healthy.
• Temporal UI is active and can connect to the Server.
• Temporal Worker 2.0 is active and connected to the correct namespace and task queue.

Verify the deployed Admin and Server charm bases:

kubectl get pod temporal-admin-k8s-0 \
  -o jsonpath='{.spec.containers[?(@.name=="charm")].image}{"\n"}'

kubectl get pod temporal-k8s-0 \
  -o jsonpath='{.spec.containers[?(@.name=="charm")].image}{"\n"}'

Run the commands against the Kubernetes namespace corresponding to the Juju model.

7.2 Verify workflow execution

Confirm that your existing workflows can be started and run to completion through the Temporal Web UI or using the cli action on temporal-admin-k8s.

Optionally, run the automated Charmed Temporal UATs to validate the deployment end-to-end.

Recovery

If an upgrade or schema migration fails, stop further refreshes. Capture the deployment status and Juju debug logs for investigation.

juju status
juju debug-log --include temporal-admin/0
juju debug-log --include temporal-k8s/0

For a failed upgrade-charm hook, inspect the traceback and resolve the underlying issue before retrying.

Juju can be configured to automatically retry failed hooks:

juju model-config automatically-retry-hooks=true

Enable this only after correcting the underlying failure; it does not repair incompatible charm packages or failed database operations.

Do not downgrade charms against a database that has already undergone a forward schema migration. Follow the PostgreSQL restore procedure using a validated backup taken before the failed upgrade.

For a failed Worker 2.0 cutover, retain Worker 1.0 at zero units until the new Worker has been verified or a controlled rollback is required.

References

• Temporal Server Upgrades
• Upgrade from latest/stable to 1.23/stable
• Temporal UI on Charmhub
• Temporal Worker on Charmhub
• Charmed Temporal UATs
• PostgreSQL K8s documentation
• Juju refresh documentation