---
title: Charmhub | Deploy Temporal Server using Charmhub - The Open Operator Collection
description: Deploy the latest version of Temporal Server as a Kubernetes Operator
  on any cloud.
url: https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable
---

# Temporal Server

[Workflows Charmers](https://charmhub.io/publisher/workflows-charmers "View all packages from Workflows Charmers")

* [Workflows Charmers](https://charmhub.io/publisher/workflows-charmers "View all packages from Workflows Charmers")

Platform:

1.23/stable 96

```
juju deploy temporal-k8s --channel 1.23/stable
```

[Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications)

---

#### Contacts

##### Maintainers

+ [Commercial Systems](mailto:jaas-crew@lists.canonical.com)

* [Submit a bug](https://github.com/canonical/temporal-k8s-operator/issues)

---

Share your thoughts on this charm with the community on discourse.

[Join the discussion](https://discourse.charmhub.io/)

# 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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-step-2-back-up-postgresql)

Before upgrading, follow the [PostgreSQL K8s backup documentation](https://charmhub.io/postgresql-k8s/docs/h-create-a-backup) 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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-step-3-upgrade-sequentially-from-123-to-130)

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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-31-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-32-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-step-4-upgrade-from-130-to-131)

Version 1.31 supports the transition to Ubuntu 26.04.

### [4.1 Refresh Temporal Admin](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-41-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-42-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-step-6-migrate-temporal-worker-from-10-to-20)

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

### [6.1 Record the existing Worker configuration](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-61-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-62-deploy-worker-20-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-63-integrate-worker-20-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-64-verify-worker-20)

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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-step-7-verify-the-complete-upgrade)

### [7.1 Check deployment status and charm bases](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-71-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-h-72-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](https://github.com/canonical/charmed-temporal-uats) to validate the deployment end-to-end.

## [Recovery](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-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](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.31/stable#p-42546-references)

* [Temporal Server Upgrades](https://charmhub.io/temporal-k8s/docs/h-server-upgrades)
* [Upgrade from latest/stable to 1.23/stable](https://charmhub.io/temporal-k8s/docs/h-upgrade-1.23/stable)
* [Temporal UI on Charmhub](https://charmhub.io/temporal-ui-k8s)
* [Temporal Worker on Charmhub](https://charmhub.io/temporal-worker-k8s)
* [Charmed Temporal UATs](https://github.com/canonical/charmed-temporal-uats)
* [PostgreSQL K8s documentation](https://charmhub.io/postgresql-k8s/docs)
* [Juju refresh documentation](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/refresh/)

---