ESS Classic to ESS Pro: Migration guide

This guide is intended for administrators planning and conducting migrations from ESS Classic to ESS Pro. It aims at providing all the technical context around the migration process.

To facilitate migration projects, Element provides a migration tool that will interactively guide administrators through the migration steps. This guide introduces the tool, its usage and gives you everything you need to get started.

Before conducting the actual migration, make sure to read the Customer migration introduction.

If you have questions on the contents of this document or on the migration from ESS Classic to ESS Pro in general, please reach out to Element Support.

Migration Overview

The migration process consists of multiple steps:

Prepare the migration
Transform your ESS Classic configuration to ESS Pro values
Deploy ESS Pro on your Kubernetes cluster
Migrate your data from ESS Classic to ESS Pro
Migrate your PostgreSQL database from ESS Classic to ESS Pro

Preparation

ESS Classic upgrade

Before starting the migration, make sure to upgrade your ESS Classic deployment to the latest version (26.04.x). During the migration, you will migrate to the equivalent ESS Pro version (26.4.x). This will ensure that you are able to rollback to ESS Classic in case of any issue.

Kubernetes cluster

When you setup ESS Classic, the installer allows you to decide between Standalone and Cluster mode. If you are using the Standalone mode, you must move from the microk8s cluster of the ESS Classic VM to another Kubernetes cluster. We suggest to use k3s, but feel free to use any Kubernetes cluster that you are comfortable with.

If you are using the Cluster mode, or if you are using the ESS Classic Helm Charts, you have the option to keep the same Kubernetes cluster to host the ESS Pro deployment. In this case, the migration will be the simplest. No data migration will be required as you can reuse the existing Persistent Volumes.

PostgreSQL database

When you setup ESS Classic, the installer allows you to setup Postgres in cluster. If you are using this mode, you will have to setup your own Postgres database before setting up ESS Pro. The tool will then ask the new database informations, and will suggest commands to run to migrate the database to the new server.

The tool allows you to set-up Postgres with the ESS Pro Helm Chart. While it is possible to do so, we strongly recommend not to use this mode for a Production deployment. It might work fine up to ~100 users, but you should still prefer to host your Postgres database using your own means.

Our installation guide explains how to set-up PostgresSQL ESS Pro databases.

If you are already using an external Postgres database, the tool will ask you if you want to re-use the same PostgreSQL server for the ESS Pro deployment. In this case, the migration will be the simplest. No data migration will be required as you can reuse the existing PostgreSQL connections. You must make sure that your ESS Pro deployment can connect to the existing Postgres server.

DNS

If you are moving to a new Kubernetes cluster, or if your ingresses require a dedicated IP, you might need to update your DNS to point to the new ingress IP of ESS Pro.

To reduce possible service disruptions to a minimum, you should set your DNS TTL records to the lowest possible value, at least 48 hours before running the migration.

Changing hostnames

The migration tool assumes that your ESS Pro deployment re-uses the same ingress hosts as your ESS Classic deployment.

If you want to use the migration to change the hostnames serving your ESS deployment, you should take into consideration the fact that changing the Synapse or Matrix Authentication Service domains will disrupt your users sessions. All your users will need to log in again. In case they failed to save their recovery key, this could lead to data loss due to decryption issues.

In this case it is recommended to edit the values file generated by the migration tool before deploying ESS Pro to do so.

If you are hosting your .well-known files externally to ESS, you will have to update them to point to the new ingress hosts of ESS Pro.

Remember: The serverName cannot be changed! ESS Pro will not prevent you from trying to do so, but it will result in a broken ESS Pro deployment.

Free space availability

If you are migrating to a new PostgreSQL database, the migration process will ask you to generate dumps of the databases. Make sure that you have enough free space on your PostgreSQL database to store the dumps. You can use \l+ PostgreSQL command to check the size of each database. The dumps will need roughly twice the size of the databases once on your disks.

If you are using Postgres in cluster feature from ESS Classic, you can refer to ESS Classic documentation to see how you can connect to the PostgreSQL database.

If you are migrating your Synapse media to a new Kubernetes cluster, you might need to run kubectl cp to copy the media locally before copying them to the new cluster. Make sure that you have enough free space on your local machine to store the media.

ESS Classic preparation

ESS Classic must be upgraded to the latest version of 26.4-LTS before running the migration.

If you are using GroupSync, you need to enable PostgreSQL in GroupSync as it is required by ESS Pro.

ESS Pro preparation

There is a setup guide for ESS Pro. Please read it carefully in order to prepare the migration and take special attention to the following preparation steps.

Setting up DNS entries. The ESS Pro migration tool will re-use existing hostnames from your ESS Classic deployment. Make sure to be able to upgrade your existing DNS entries to point to the new ESS Pro deployment.
(Optionally) Setting up K3s. You can follow these instructions if you are coming from our microk8s-based setup and want to keep using a single node Kubernetes cluster for ESS Pro. You can also decide to use any alternative Kubernetes distribution you are comfortable with.
Setting up TLS/certificates: The ESS Pro migration tool will automatically migrate your ESS Classic certificates to the new deployment.

ESS Pro cluster access from ESS Classic cluster

If you are moving to a new Kubernetes cluster, during the migration, you will need to access both the ESS Classic cluster and the ESS Pro cluster.

The section presents some ways to achieve this. Feel free to use any other access methods depending on your own infrastructure.

Using an SSH tunnel

If you have been using the Standalone setup, you can use the following method to access the next ESS Pro cluster from your microk8s VM:

Export the ESS Pro Cluster kubeconfig file: If you are using the suggested k3s setup, the kubeconfig file is located at /etc/rancher/k3s/k3s.yaml on the VM where k3s is installed.
```
# On the k3s VM:
cat /etc/rancher/k3s/k3s.yaml
```

Copy the output and save it as ~/.kube/k3s-config on your microk8s VM.

Run the following command to rename the context: kubectl config --kubeconfig=$HOME/.kube/k3s-config rename-context default k3s

Open an SSH tunnel from microk8s VM to k3s cluster: On the microk8s VM, run this command to create an SSH tunnel to the k3s VM:
```
ssh -L 127.0.0.1:6443:localhost:6443 <user>@<k3s-VM-IP> -f -N
```
- <k3s-VM-IP>: IP address of the VM running k3s.
- <user>: Your username on the k3s VM.
This forwards local port 6443 on the microk8s VM to port 6443 on the k3s VM.
Alternatively, connect from the k3s machine to the microk8s VM with a reverse tunnel:
```
ssh -R 127.0.0.1:6443:localhost:6443 <user>@<microk8s-VM-IP>
```

Switch between clusters:

kubectl get pods --kubeconfig=$HOME/.kube/config
kubectl get pods --kubeconfig=$HOME/.kube/k3s-config

In-place k3s setup on existing microk8s VM

If you are not able to setup a new VM to execute the ESS Pro migration, it is possible to run the migration in-place.

k3s does not support running on a VM when an existing Kubernetes cluster is already running. The strategy is the following process:

Follow the documentation to run the ess-pro-migration-tool. You will have to specify ESS Pro kubeconfig parameter, but the tool will not be able to access the k3s cluster. Use the path --ess-pro-kubeconfig ~/.kube/k3s-config, we will export k3s kubeconfig path later on.
The tool will run and log commands to run. You can skip running the commands for now, and continue to press enter in the tool until it ends.
If you are using PostgreSQL in cluster ESS Classic feature, the tool will explain in DATABASE IMPORT INSTRUCTIONS section how to dump the databases to a local file. Run the commands described in Create database dumps: now, before we stop microk8s cluster.
The tool will not be able to automatically discover the k3s values. Adjust your values files according to the tip in Adjust the resulting values file.
You can now stop microk8s: microk8s stop
Disable microk8s kubectl alias: snap unalias kubectl. It will be replaced by k3s kubectl setup.
Install k3s according to the relevant documentation
Export it's kubeconfig
```
# On the k3s VM:
cat /etc/rancher/k3s/k3s.yaml
```
Copy the output and save it as ~/.kube/k3s-config on your VM.
You can now run all the commands setting up ESS Pro on the k3s cluster and importing existing data from ESS Classic.
Once you verified that the migration ran successfully, you can uninstall microk8s with snap remove microk8s

Migration

There is a migration tool to guide you through and conduct the migration process. The tool migrates your configuration from ESS Classic to ESS Pro values and gives you instructions on how to migrate data.

The tool has two modes of operation:

a. The tool can directly query the Kubernetes cluster for the Element Deployment CRD. This is the recommended mode.
b. The tool can use static files from your local filesystem. This is useful when you do not have access to the Kubernetes API.

It is recommended to use mode (a) when possible. It is recommended to only use (b) if you do not have access to the Kubernetes API.

The ESS Pro Migration Tool will migrate the following components:

Synapse
Matrix Authentication Service
Element Web
Element Admin
Element Call (or Jitsi Meet to Element Call after acknowledgment of the user)
Well Known Delegation
Hookshot
AdminBot to Supervision
AuditBot
GroupSync to Advanced Identity and Access Management
Secure Border Gateway

All other components will not be migrated. You will need to set them up manually. The ESS Migration Tool will inform you about the unsupported components.

Installing the migration tool

The ESS Pro Migration Tool requires Python 3.11 or higher.

You should ideally install it using pipx, but installing it with pip should also work.

Install the tool using pipx install ess-pro-migration-tool.

How to install with Ubuntu 22.04, which uses Python 3.10?

You will have to install python 3.11 and target it explicitly:

sudo apt install python3.11
pipx install ess-pro-migration-tool --python /usr/bin/python3.11

Manually downloading the tool for use on a machine without internet connection (Airgapped)

Download the package from an internet connected machine

mkdir ess-pro-migration-tool

python3.11 -m pip download \
  --dest ess-pro-migration-tool \
  ess-pro-migration-tool

Copy the entire ess-pro-migration-tool/ directory to the airgapped machine.

Install on the offline machine

pipx install ess-pro-migration-tool \
  --python /usr/bin/python3.11 \
  --pip-args="--no-index --find-links=/path/to/ess-pro-migration-tool"

Generate the ESS Pro values from ESS Classic Element Deployment CRD

With Kubernetes Cluster access

If you are using ESS Classic standalone, you can use the following command and follow the instructions:

ess-pro-migration-tool --ess-classic

If this is a custom ElementDeployment manifest name, you can provide the namespace and the name of the manifest in the --ess-classic flag:

ess-pro-migration-tool --ess-classic=<namespace>/<name of the element deployment instance>

If your ESS Classic cluster is different from your ESS Pro cluster, you can provide the kubeconfig and kubecontext of each with the following arguments:

ess-pro-migration-tool --ess-classic --kubeconfig <path to ESS Classic kubeconfig> --kubecontext <ESS Classic kubecontext> --ess-pro-kubeconfig <path to ESS Pro kubeconfig> --ess-pro-kubecontext <ESS Pro kubecontext>

The tool will automatically suggest commands with the appropriate kubeconfig and kubecontext values.

Accessing the ESS Pro cluster through the SSH tunnel

If you followed Access to the K3S Cluster from your ESS Classic VM using an SSH Tunnel, you should run ess-pro-migration-tool with the --ess-pro-kubeconfig ~/.kube/k3s-config flag.

From Static files

When importing from static files, you need to provide the path to:

The ElementDeployment manifest: kubectl get elementdeployment/<name> -n <ns> -o yaml > elementdeployment.yaml
The Synapse homeserver.yaml config file exported from the ESS Classic deployment with kubectl get secrets/<name>-synapse-main -n <namespace> --template '{{ index .data "instance_template.yaml" }}' | base64 -d > homeserver.yaml
The Element Web config.json config file exported from the ESS Classic deployment with kubectl get secrets/<n>-web-main -n <namespace> --template '{{ index .data "config.json" }}' > config.json
The Well-Known files exported from the ESS Classic deployment with:
client: kubectl get configmap/<name>-new-well-known-haproxy -n <namespace> --template '{{ index .data "client" }}' > client
server: kubectl get configmap/<name>-new-well-known-haproxy -n <namespace> --template '{{ index .data "client" }}' > server
support (optional): kubectl get configmap/<name>-new-well-known-haproxy -n <namespace> --template '{{ index .data "client" }}' > support
element.json (optional): kubectl get configmap/<name>-new-well-known-haproxy -n <namespace> --template '{{ index .data "client" }}' > element.json
The Hookshot config.yaml: (optional): kubectl get configmap/<name>-hookshot-config -n <namespace> --template '{{ index .data "config.yaml" }}' > hookshot-config.yaml

Interactive Mode vs Quiet Mode

By default, the migration tool will guide you through the migration process. The following describes the steps that the tool suggests to follow to run the migration.

It is also possible to run the ESS Pro Migration Tool in quiet mode using --quiet-mode. In this mode, the ESS Pro Migration Tool will not ask you any questions and will fail if there's any ambiguity that it cannot resolve. Some choices can be passed through flags:

Database choice: --database-mode {existing,ess-managed}
Enable Jitsi to Element Call migration --jitsi-migrate

OpenShift

If you are using OpenShift, pass the flag --openshift to the migration tool. This will make sure that the ESS Pro values file is configured accordingly to OpenShift rules (Typically, no runAsUser nor runAsGroup will be set, etc).

Choose your database migration procedure (`🗃 DATABASE CONFIGURATION CHOICE`)

The migration tool will ask you how you want to handle your databases. When coming from ESS Classic, it will discover if you have been using PostgreSQL in cluster feature.

When using an external PostgreSQL server

The migration tool will ask you if you want to migrate to ESS Pro managed databases, or keep using the current external databases. The choices are:

🔗 Connect to the existing database (recommended for production): This mode requires ESS Pro to be able to reach the existing database. No action is required regarding database migration after ESS Pro is deployed. This is the recommended choice for production, and also allows you to easily rollback to ESS Classic in case of issues.
🆕 Install PostgresSQL with ESS Pro: This mode will let the ESS Pro helm chart creates a PostgreSQL server shared between all the components. It can theoretically handle very small deployments (~100 users) but it is not recommended for production. The migration tool will also generate generic instructions about how to dump data from your existing databases to the ESS Pro databases.

When using PostgreSQL in cluster feature

The migration tool will ask you if you want to migrate the ESS Classic-managed databases to an external PostgreSQL server, or to ESS Pro managed databases. The ESS Classic-managed databases will not be used by the ESS Pro deployment. The choices are:

🔄 Migrate the ESS Classic-managed databases to an external PostgreSQL server: This mode requires you to provide a PostgreSQL database to each component. The migration tool will prompt you for database credentials and uris. The resulting ESS Pro deployment will automatically be configured to connect to these databases. The migration tool will also generate instructions about how to migrate your data from the ESS Classic databases to the new PostgreSQL server.
🆕 Install PostgresSQL with ESS Pro: This mode will let the ESS Pro helm chart creates a PostgreSQL server shared between all the components. It can theoretically handle very small deployments (~100 users) but it is not recommended for production. The migration tool will also generate instructions about how to migrate your data from the ESS Classic databases to the ESS Pro managed databases.

Migration summary

The migration tool will generate a summary describing how the values were transformed.

ESS Pro values (`✅ ESS PRO VALUES CREATED SUCCESSFULLY`)

This table shows, for each ESS Pro value, which source file and configuration key was used to determine it.

The example below show that serverName was determined from config.yaml fetched from the Matrix Authentication Service ESS Classic deployment, using the matrix.homeserver configuration key.

│ ╭──────────────────────────────────┬─────────────────┬─────────────╮ │
│ │ Source                           │ Path            │ ESS Value   │ │
│ ├──────────────────────────────────┼─────────────────┼─────────────┤ │
│ │ k8s://element-onprem/first-elem… │ bridge.domain   │ serverName  │ │

If any value conflicts, the user will be prompted to decide which value to use and resolve the conflict.

ESS Pro Secrets (`🔐 MIGRATED SECRETS` and `ℹ️ ESS-INITIALIZED SECRETS`)

It shows, for each ESS Pro secret, which source file and configuration key was used to import it in ESS Pro configuration. If a secret could not be imported, but could be initialized safely by ESS Pro when setting-it up, it will be shown in the next table.

The example below show that synapse.macaroon was determined from instance_template.yaml fetched from the Synapse ESS Classic deployment, using the macaroon_secret_key configuration key. The synapse.registrationSharedSecret could not be imported will be initialized with a random value when ESS Pro is set up.

╭──────────────────────────── 🔐 MIGRATED SECRETS ─────────────────────────────╮
│ ╭────────────────────────┬────────────────────────┬────────────────────────╮ │
│ │ Source File            │ Config Key             │ Secret Path in Values  │ │
│ ├────────────────────────┼────────────────────────┼────────────────────────┤ │
│ │ k8s://element-onprem/… │ macaroon_secret_key    │ synapse.macaroon       │ │

[...]

╭──────── ℹ️  ESS-INITIALIZED SECRETS ────────╮
│ ╭──────────────────────────────────╮        │
│ │ Secret Path in Values            │        │
│ ├──────────────────────────────────┤        │
│ │ synapse.registrationSharedSecret │        │
│ ╰──────────────────────────────────╯        │
╰─────────────────────────────────────────────╯

Additional configuration owned by ESS Pro (`ℹ️ ESS-MANAGED COMPONENTS CONFIGURATIONS DETECTED`)

When migrating from ESS Classic, the ESS Pro Migration Tool will automatically discover the configuration generated by the Updater and the Operator. It will parse them to discover ESS Pro values, and will pass them to additional.00-imported key of each component, pruned from any configuration that is already managed by the ESS Pro helm chart. This section shows the configurations that have been pruned.

User customizations (`ℹ️ DEVIATION FROM ESS PRO DEFAULT CONFIGURATIONS FOUND`)

The ESS Pro Migration Tool will keep configuration that is either not managed by ESS Pro, or for which defaults can be overridden by the user. This section shows the deviations from the default configuration that are being passed to additional.00-imported key of each component.

Adjust the resulting values file

ESS Migration Tool will port your ESS Classic values to ESS Pro values. It will also try to discover the IngressClass, StorageClass and ClusterIssuer of your ESS Pro cluster if you are changing to a new cluster and it is able to reach it.

If the tool cannot reach the ESS Pro cluster, you will need to adjust the generated values file in ~/output/values.yaml, especially regarding the following:

Ingress Class: Microk8s uses nginx as default Ingress Class. You will need to change it to your own Ingress Class according to your Kubernetes cluster.
Storage Class: Microk8s uses local-path as default storage class. You will need to change it to your own storage class according to your Kubernetes cluster.
Cluster Issuer: Microk8s uses letsencrypt as the default Certificate manager issuer. You will need to change it to your own Certificate manager issuer according to your Kubernetes cluster.
Additional configuration: You can take a look at the additional configuration generated by the ESS Pro Migration Tool. This is the configuration that customize your ESS Pro deployment according to how your ESS Classic deployment was configured.

!!! tip "Which values should I use against the suggest k3s cluster?" If you are deploying against our suggested k3s cluster, you can use the following values:

  ```yaml
  ingress:
    className: traefik
  storage:
    storageClassName: local-path
  certManager:
    clusterIssuer: letsencrypt-prod
  ```

Deploy ESS Pro

The ESS Pro Migration Tool will generate the commands needed to deploy ESS Pro.

Create Kubernetes namespace: kubectl create namespace ess
The ESS Pro Migration Tool will export the secrets generated by ESS Classic in dedicated Kubernetes secrets manifests. You will need to apply them to your ESS Pro namespace. For each secret in the output directory, run kubectl apply -f output/imported-<name-secret.yaml -n ess
The migration tool will ask you to login against registry.element.io with helm. Use your ESS Credentials. helm registry login registry.element.io
You can then install ESS using Helm with the generated values. They automatically refer to the secret you applied in the namespace: helm upgrade --install --version "26.4.*+lts" --namespace "ess" ess oci://registry.element.io/matrix-stack -f output/values.yaml --wait
It is expected that some components crash until the data is migrated (AuditBot, Supervision, Advanced Identity Management).

Migrate your data

Before migrating your data, you should stop your ESS Classic deployment. Follow the instructions in Starting and Stopping ESS Classic Services

Migrating persistent volumes from ESS Classic to ESS Pro

When you are migrating to ESS Pro on the same Kubernetes cluster, you can migrate your persistent volumes from ESS Classic to ESS Pro.

To migrate the persistent volumes from ESS Classic to ESS Pro, the tool will explain to you how to unbind the ESS Classic Persistent Volume Claims, release the existing Persistent Volume, and set-up ESS Pro so that they mount the existing Persistent Volumes.

Make sure the existing Persistent Volumes have a persistentVolumeReclaimPolicy of Retain:

kubectl patch pv <pv-name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

Delete the ElementDeployment to remove the ESS Classic PersistentVolumeClaim: kubectl delete elementdeployment/<name> -n <namespace>
Delete the ESS Classic claimRef on the Persistent Volume to make them Available for ESS Pro:

kubectl patch pv pvc-b5868e24-44f9-40e0-be34-08683a476418 --type=json -p='[{"op": "remove", "path": "/spec/claimRef"}]'
kubectl wait pv pvc-b5868e24-44f9-40e0-be34-08683a476418 --for=jsonpath='{.status.phase}'=Available

When ESS Pro setup runs, the Persistent Volume Claims will be created. As they are configured with the same size, storageClass, and volumeName of your ESS Classic deployment, Kubernetes will automatically bind them against the matching ESS Classic Persistent Volumes.

Migrating data by copying files from ESS Classic to ESS Pro

When you are migrating to ESS Pro to a new Kubernetes cluster, you might have to copy your data to transfer it into the new cluster.

To migrate your data, you cannot directly copy against the ESS Pro pods. As it is a Distroless image, it lacks binaries required for kubectl cp to work properly. The ESS Pro Migration Tool will suggest to create a matrix-tools debug variant pod that will mount your Synapse media persistent volume. You will be able to use kubectl cp against it.

Create the cp-debug pod

kubectl run cp-debug \
--image=registry.element.io/matrix-tools:0.17.9-debug \
-n ess --restart=Never \
--overrides='{
  "spec": {
    "imagePullSecrets": [
      {
        "name": "ess-registry-element-io"
      }
    ],
    "containers": [
      {
        "name": "debug",
        "image": "registry.element.io/matrix-tools:0.17.9-debug",
        "command": [
          "sleep",
          "infinity"
        ],
        "volumeMounts": [
          {
            "name": "synapse-media",
            "mountPath": "/media"
          }
        ]
      }
    ],
    "volumes": [
      {
        "name": "synapse-media",
        "persistentVolumeClaim": {
          "claimName": "ess-synapse-media"
        }
      }
    ]
  }
}'

Wait for the pod to be ready: kubectl wait --for=condition=ready pod/cp-debug -n ess --timeout=300s
Run kubectl cp against the pod: kubectl cp /<path to synapse data> cp-debug:/media/media_store -n ess
Delete the cp-debug pod kubectl delete pod cp-debug -n ess

Note: When Migrating from a microk8s deployment, the ESS Pro Migration Tool will automatically discover the path of the local data directory.

Migrate your PostgreSQL database (`📋 DATABASE IMPORT INSTRUCTIONS`)

The ESS Pro Migration Tool will provide database migration instructions when you are changing from the ESS Classic database. This happens if you have been using the PostgreSQL in cluster mode of ESS Classic, or if you ask the ESS Pro Migration Tool to migrate to the ESS Pro managed database.

The overall process is as follows:

Dump the ESS Classic PostgreSQL databases
Stop the ESS Pro workloads
Copy the dumps to the ESS Pro database
Import the dumps into the ESS Pro database
Start the ESS Pro workloads

Stop the ESS Pro workloads

Follow the instructions in the Starting and Stopping ESS Services

Dump the ESS Classic PostgreSQL in cluster databases

To migrate from PostgreSQL in cluster, the ESS Pro Migration Tool will generate the command that you can reuse to dump the databases.

# Synapse
kubectl --namespace element-onprem exec --container postgres --stdin --tty synapse-postgres-0 -- bash -c
 'pg_dump --no-owner --no-privileges --dbname=$POSTGRES_DB --username=$POSTGRES_USER -f /postgresdump'
kubectl cp element-onprem/synapse-postgres-0:/postgresdump ./synapse-postgres.dump -c postgres

# Matrix Authentication Service
kubectl --namespace element-onprem exec --container postgres \
 --stdin --tty matrix-authentication-service-postgres-0 -- bash -c \
 'pg_dump --no-owner --no-privileges --dbname=$POSTGRES_DB --username=$POSTGRES_USER -f /postgresdump'
kubectl cp element-onprem/matrix-authentication-service-postgres-0:/postgresdump \
 ./matrix_authentication_service-postgres.dump -c postgres

# Groupsync
kubectl --namespace element-onprem exec --container postgres \
 --stdin --tty groupsync-postgres-0 -- bash -c \
 'pg_dump --no-owner --no-privileges --dbname=$POSTGRES_DB --username=$POSTGRES_USER -f /postgresdump'
kubectl cp element-onprem/groupsync-postgres-0:/postgresdump \
 ./groupsync-postgres.dump -c postgres

Import the dumps into the ESS Pro managed PostgreSQL server

To import the dumps, into the ESS Pro managed database, you will need to copy the dump files and import them. The ESS Pro Migration Tool will generate the commands to do so.

# Synapse
kubectl cp synapse-postgres.dump ess-postgres-0:/tmp -n ess
kubectl exec -n ess sts/ess-postgres -- bash -c \
"dropdb -U postgres synapse;
createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user -U postgres synapse;
psql -U synapse_user -d synapse < /tmp/synapse-postgres.dump"

# Matrix Authentication Service
kubectl cp matrix_authentication_service-postgres.dump ess-postgres-0:/tmp -n ess
kubectl exec -n ess sts/ess-postgres -- bash -c \
"dropdb -U postgres matrixauthenticationservice;
createdb --encoding=UTF8 --locale=C --template=template0 --owner=matrixauthenticationservice_user -U postgres matrixauthenticationservice; psql -U matrixauthenticationservice_user -d matrixauthenticationservice < /tmp/matrix_authentication_service-postgres.dump"

# Groupsync
kubectl cp groupsync-postgres.dump ess-postgres-0:/tmp -n ess
kubectl exec -n ess sts/ess-postgres -- bash -c \
"dropdb -U postgres advancedidentitymanagement;
createdb --encoding=UTF8 --locale=C --template=template0 --owner=advancedidentitymanagement_user -U postgres advancedidentitymanagement; psql -U advancedidentitymanagement_user -d advancedidentitymanagement < /tmp/groupsync-postgres.dump"

Import the dumps into an external PostgreSQL server

If you are not using the ESS Pro managed database, you will have to import the dumps into an external PostgreSQL server. The ESS Pro Migration Tool will show an example of the commands to do so. This should be run against an existing database, with the user that will be used by Synapse or Matrix Authentication Service.

psql -U <username> -d <database> -f <dump_file>

Start the ESS Pro workloads

Follow the instructions in the Starting and Stopping ESS Services

Verifications

Follow the general ESS setup instructions in the Verifying the setup section.

Rolling back

If you need to rollback to ESS Classic, you will need to:

Stop the ESS Pro workloads
Start the ESS Classic workloads
Reconfigure the DNS entries accordingly

Important things to note if your users were starting to use the new ESS Pro services:

If you are using the same external DB, they should not see any data loss
If you are using the same S3 media endpoint, they should not see any media loss

If this is not the case, you might have to accept data loss, or migrate the data the other way around, from your ESS Pro deployment to your ESS Classic deployment.

ESS Classic to ESS Pro: Migration guide

Migration Overview

Preparation

ESS Classic upgrade

Kubernetes cluster

PostgreSQL database

DNS

Changing hostnames

Free space availability

ESS Classic preparation

ESS Pro preparation

ESS Pro cluster access from ESS Classic cluster

Using an SSH tunnel

In-place k3s setup on existing microk8s VM

Migration

Installing the migration tool

Generate the ESS Pro values from ESS Classic Element Deployment CRD

With Kubernetes Cluster access

From Static files

Interactive Mode vs Quiet Mode

OpenShift

Choose your database migration procedure (🗃 DATABASE CONFIGURATION CHOICE)

When using an external PostgreSQL server

When using PostgreSQL in cluster feature

Migration summary

ESS Pro values (✅ ESS PRO VALUES CREATED SUCCESSFULLY)

ESS Pro Secrets (🔐 MIGRATED SECRETS and ℹ️ ESS-INITIALIZED SECRETS)

Additional configuration owned by ESS Pro (ℹ️ ESS-MANAGED COMPONENTS CONFIGURATIONS DETECTED)

User customizations (ℹ️ DEVIATION FROM ESS PRO DEFAULT CONFIGURATIONS FOUND)

Adjust the resulting values file

Deploy ESS Pro

Migrate your data

Migrating persistent volumes from ESS Classic to ESS Pro

Migrating data by copying files from ESS Classic to ESS Pro

Migrate your PostgreSQL database (📋 DATABASE IMPORT INSTRUCTIONS)

Stop the ESS Pro workloads

Dump the ESS Classic PostgreSQL in cluster databases

Import the dumps into the ESS Pro managed PostgreSQL server

Import the dumps into an external PostgreSQL server

Start the ESS Pro workloads

Verifications

Rolling back

Choose your database migration procedure (`🗃 DATABASE CONFIGURATION CHOICE`)

ESS Pro values (`✅ ESS PRO VALUES CREATED SUCCESSFULLY`)

ESS Pro Secrets (`🔐 MIGRATED SECRETS` and `ℹ️ ESS-INITIALIZED SECRETS`)

Additional configuration owned by ESS Pro (`ℹ️ ESS-MANAGED COMPONENTS CONFIGURATIONS DETECTED`)

User customizations (`ℹ️ DEVIATION FROM ESS PRO DEFAULT CONFIGURATIONS FOUND`)

Migrate your PostgreSQL database (`📋 DATABASE IMPORT INSTRUCTIONS`)