Workload Import and Migration

Workload Import and Migration lets you bring existing workload definitions and their associated snapshot metadata from one TrilioVault instance into another, or move protected workloads between OpenStack clouds entirely. This is useful when consolidating backup infrastructure, promoting workloads from a staging cloud to production, or recovering after a TrilioVault cluster rebuild. Because TrilioVault's protection model is workload-centric — snapshots capture multi-VM applications as a consistent unit — migration preserves that grouping and its snapshot history so you can restore from pre-migration recovery points immediately after the import completes.

Before you begin a workload import or migration, confirm the following are in place:

• TrilioVault version: Both the source and destination TrilioVault instances must be running the same major version. Cross-version imports may succeed, but Trilio recommends keeping versions aligned to avoid schema incompatibilities.
• OpenStack ≥ Stein on the destination cloud.
• OpenStack services: Keystone, Nova, and Cinder must be healthy on the destination cloud.
• TrilioVault Trustee RBAC role: The user performing the import must hold the Trustee role on the destination OpenStack project. The standard OpenStack admin role is not a substitute.
• Shared or accessible backup target: The destination TrilioVault instance must be able to reach the same backup target (NFS share, S3-compatible endpoint, or Swift container) that holds the source workload's snapshots. Mount paths or endpoint URLs must be configured identically.
• nova user UID/GID consistency: All read and write operations on the backup target are performed as nova:nova. The POSIX UID and GID of nova must be identical across the source cluster nodes, destination cluster nodes, and all compute nodes on both clouds.
• Cinder quota headroom: TrilioVault creates up to two Cinder snapshots and one temporary Cinder volume per disk during restore operations triggered after import. Verify quotas before proceeding.
• workloadmgr CLI: The workloadmgr command from the workloadmanager-client package must be installed and configured with valid OpenStack credentials pointing at the destination cloud.
• Destination network space (for network topology restore): If you intend to restore network topology after migration, the destination tenant's network space must be completely empty of networking components — networks, subnets, routers, ports, and floating IPs — before the restore step.
• Python ≥ 3.6 on the host running the CLI.
• Horizon dashboard plugin (optional): The horizon-tvault-plugin must be installed on the destination Horizon instance if you prefer a graphical workflow.

Workload import is performed by pointing the destination TrilioVault instance at the backup target that already contains the source workload's snapshot data, then running the import command. No additional packages are required beyond the standard TrilioVault installation.

Step 1 — Verify the backup target is reachable from the destination cluster

SSH into each TrilioVault node in the destination cluster and confirm the backup target mount or endpoint is accessible. For an NFS target:

showmount -e <nfs-server-address>

For an S3-compatible target, confirm the bucket and credentials are already configured in the destination TrilioVault settings via the TrilioVault Dashboard or the configurator playbooks.

Step 2 — Confirm the destination backup target configuration matches the source

On the destination TrilioVault master node, inspect the current backup target registration:

workloadmgr backup-target-list

The output should show the same NFS path, S3 endpoint, or Swift URL that the source workload snapshots were written to. If it does not, configure the matching target before continuing.

Step 3 — Source your OpenStack credentials for the destination cloud

source /path/to/destination-openrc.sh

Verify the active project and that your user holds the Trustee role:

openstack token issue
openstack role assignment list --user <your-username> --project <destination-project>

Step 4 — Discover importable workloads on the backup target

TrilioVault can scan the backup target and surface workload metadata that exists on storage but is not yet registered in the destination Workload Manager database:

workloadmgr workload-discover

This command contacts wlm-api, which queries the backup target for unregistered workload metadata files and returns a list of workload IDs and display names available for import.

Step 5 — Import a specific workload

Use the workload ID returned in Step 4 to register the workload in the destination TrilioVault instance:

workloadmgr workload-importworkloads <workload-id>

Replace <workload-id> with the UUID surfaced by workload-discover. Repeat this step for each workload you want to import.

Step 6 — (Optional) Import all discovered workloads in one operation

If you are migrating an entire backup target, you can batch-import all discovered workloads:

workloadmgr workload-importworkloads --all

Step 7 — Verify the imported workloads and their snapshots

workloadmgr workload-list

For each imported workload, list its snapshots to confirm the history was preserved:

workloadmgr snapshot-list --workload_id <workload-id>

Step 8 — (Optional) Horizon UI verification

If the horizon-tvault-plugin is installed on the destination Horizon, log in to the dashboard, navigate to Project → Workloads, and confirm the imported workloads and their snapshots appear in the Workloads panel.

The following configuration points govern how workload import and migration behave. Most are set during initial TrilioVault cluster configuration via the triliovault-cfg-scripts Ansible playbooks, but several can be adjusted per-operation through CLI flags.

Backup target path or endpoint

nova user UID/GID

All backup target I/O runs as the nova user (nova:nova). If the nova UID or GID differs between source compute nodes, destination compute nodes, and TrilioVault cluster nodes, file permission errors will occur during both discover and restore. Ensure consistency before running any import command. This is enforced at the OS level — TrilioVault does not remap UIDs automatically.

Trustee role assignment

The Trustee role must be assigned in the destination OpenStack project for every user who will own or manage imported workloads. Assign it with:

openstack role add --user <username> --project <project-name> Trustee

Import operations submitted without this role will be rejected by wlm-api.

Idempotency and re-import behavior

Workload import is idempotent. If you run workloadmgr workload-importworkloads for a workload ID that is already registered in the destination database, the operation is a no-op — it will not create duplicate records or overwrite existing snapshot metadata. This means you can safely re-run discovery and import scripts after partial failures.

Snapshot policy inheritance

After import, the workload's existing snapshot policy (schedule and retention rules) is imported alongside the workload definition. Review the policy on the destination cluster and adjust it if the destination environment has different RTO/RPO requirements:

workloadmgr workload-show <workload-id>

The scheduler_hints section shows the schedule and retention values currently attached to the workload.

Network topology considerations

TrilioVault ≥ 3.0 automatically captures full tenant network topology — networks, subnets, routers, static routes, ports, and floating IPs — in every snapshot. When you restore from an imported snapshot on the destination cloud, TrilioVault will attempt to recreate this topology. The destination tenant's network space must be completely empty before a topology restore, or the restore will fail. After topology restore, TrilioVault does not reconnect private networks to the public network; you must perform that final step manually.

Discovering and importing workloads from the CLI

The most common scenario is consolidating two TrilioVault deployments onto one backup target and then importing all existing workloads into the surviving instance.

After mounting the shared backup target and sourcing destination credentials, run discovery to see what is available:

workloadmgr workload-discover

Review the list and import selectively or all at once. To import a single workload by its UUID:

workloadmgr workload-importworkloads 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c

Once imported, the workload behaves exactly like a natively created workload. You can take new snapshots, modify or replace the snapshot policy, or trigger an immediate restore from any pre-migration snapshot.

Restoring from a pre-migration snapshot

After import, list the available snapshots and choose the recovery point:

workloadmgr snapshot-list --workload_id 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c

Initiate a full workload restore from a chosen snapshot:

workloadmgr workload-restore \
  --workload_id 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c \
  --snapshot_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --restore_type openstack

File-level restore from an imported snapshot

If you only need specific files from a pre-migration snapshot, use file-level restore without recreating entire VMs:

workloadmgr workload-file-restore \
  --snapshot_id a1b2c3d4-e5f6-7890-abcd-ef1234567890

For file-level restore to appear as a valid mount target in the Horizon UI, the File Recovery Manager Glance image on the destination cloud must have the property tvault_recovery_manager=yes set.

Using the Horizon dashboard plugin

If the horizon-tvault-plugin is installed, you can perform the same operations graphically:

1. Log in to Horizon on the destination cloud.
2. Navigate to Project → Workloads.
3. Click Import Workloads and follow the guided wizard — Horizon calls wlm-api on your behalf using your session credentials.
4. After import, select any workload and click Restore to choose a snapshot and restore type.

Scheduling ongoing snapshots after migration

Imported workloads retain their original snapshot policy. To update the policy to match destination requirements:

workloadmgr workload-modify \
  --workload_id 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c \
  --fullbackup_interval 7 \
  --retention_policy_value 30

The wlm-cron service on the destination cluster will pick up the new policy and fire scheduled snapshots at the updated interval.

Example 1 — Discover all importable workloads on the backup target

Run discovery after configuring the destination backup target:

source /home/admin/destination-openrc.sh
workloadmgr workload-discover

Expected output:

+--------------------------------------+-------------------------+--------+
| ID                                   | Name                    | Status |
+--------------------------------------+-------------------------+--------+
| 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c | web-tier-workload       | ready  |
| 7a9d3b1c-22e4-4f1a-bc78-9d0e1f2a3b4c | db-cluster-workload     | ready  |
| c4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 | analytics-stack         | ready  |
+--------------------------------------+-------------------------+--------+

Example 2 — Import a single workload by UUID

workloadmgr workload-importworkloads 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c

Expected output:

Workload 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c imported successfully.
Name:    web-tier-workload
Status:  available
Snapshots imported: 14

Example 3 — Import all discovered workloads in a single command

workloadmgr workload-importworkloads --all

Expected output:

Importing workload 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c ... done (14 snapshots)
Importing workload 7a9d3b1c-22e4-4f1a-bc78-9d0e1f2a3b4c ... done (8 snapshots)
Importing workload c4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 ... done (21 snapshots)

3 workloads imported. 0 errors.

Example 4 — Verify imported snapshots for a workload

workloadmgr snapshot-list --workload_id 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c

Expected output (truncated):

+--------------------------------------+---------------------+-----------+------+
| ID                                   | Created At          | Type      | Size |
+--------------------------------------+---------------------+-----------+------+
| a1b2c3d4-e5f6-7890-abcd-ef1234567890 | 2024-06-01T03:00:00 | incremental| 12G |
| b2c3d4e5-f6a7-8901-bcde-f01234567891 | 2024-05-25T03:00:00 | full      | 85G  |
| c3d4e5f6-a7b8-9012-cdef-012345678912 | 2024-05-18T03:00:00 | incremental| 9G  |
+--------------------------------------+---------------------+-----------+------+

Example 5 — Restore a workload from a pre-migration snapshot

workloadmgr workload-restore \
  --workload_id 3f7c1a2e-84b0-4d2e-9b5a-0c1e2f3a4b5c \
  --snapshot_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --restore_type openstack

Expected output:

Restore initiated.
Restore ID: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f01
Status:     in-progress

Monitor progress with:
  workloadmgr restore-show d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f01

Example 6 — Assign the Trustee role before importing (if not yet assigned)

openstack role add --user backup-admin --project destination-project Trustee

Expected output:

(no output on success)

Confirm the assignment:

openstack role assignment list --user backup-admin --project destination-project

workload-discover returns an empty list

Symptom: Running workloadmgr workload-discover returns zero results even though you know snapshots exist on the backup target.

Likely cause:

• The backup target configured on the destination TrilioVault instance does not match the path or endpoint used by the source instance.
• The NFS share is not mounted, or the S3/Swift credentials are invalid on the destination cluster.
• The nova user on the destination TrilioVault nodes cannot read the backup target due to a UID/GID mismatch.

Fix:

1. Verify the backup target registration: workloadmgr backup-target-list.
2. SSH into the destination TrilioVault master node and confirm the NFS mount or S3/Swift endpoint is reachable and readable as the nova user: sudo -u nova ls <backup-target-path>.
3. Check that the nova UID and GID are identical on all cluster nodes and compute nodes.
4. Review the wlm-api log for error details: /var/log/workloadmgr/workloadmgr-api.log.

Import fails with 403 Forbidden or Policy does not allow

Symptom: workloadmgr workload-importworkloads exits immediately with a 403 error or a policy denial message.

Likely cause: The user performing the import does not hold the Trustee role on the destination project. The OpenStack admin role does not substitute for Trustee.

Fix:

openstack role add --user <your-username> --project <destination-project> Trustee

Re-run the import command after confirming the role assignment.

Network topology restore fails with a conflict error

Symptom: After importing a workload and attempting a restore, the operation fails with an error indicating network resource conflicts.

Likely cause: The destination tenant's network space is not empty. TrilioVault requires the tenant to have no existing networks, subnets, routers, ports, or floating IPs before attempting a network topology restore.

Fix:

1. List and delete all networking resources in the destination tenant:
   Copy

   openstack router list --project <destination-project>
   openstack network list --project <destination-project>
   

2. Remove routers, ports, subnets, and networks in the correct dependency order.
3. Re-run the restore command.
4. After the restore completes, manually reconnect the restored private networks to the public network — TrilioVault does not perform this final step automatically.

Imported workload shows error status immediately after import

Symptom: workloadmgr workload-list shows the imported workload with a status of error rather than available.

Likely cause:

• Snapshot metadata on the backup target is corrupt or incomplete.
• The wlm-workloads agent on the destination nodes cannot reach the backup target to validate the snapshot chain.

Fix:

1. Check the wlm-workloads log for details: /var/log/workloadmgr/workloadmgr-workloads.log.
2. Confirm that wlm-workloads is running on every destination TrilioVault node (it runs on all nodes, unlike wlm-api and wlm-scheduler which run only on the master):
   Copy

   systemctl status wlm-workloads
   

3. If the log shows I/O errors, recheck backup target permissions and nova user UID/GID consistency.

Scheduled snapshots do not start after import

Symptom: The imported workload has a snapshot policy defined, but no automatic snapshots are triggered on the destination cluster.

Likely cause: The wlm-cron service on the destination cluster is not running, or the policy was not imported correctly.

Fix:

1. Verify wlm-cron is healthy:
   Copy

   systemctl status wlm-cron
   

2. Confirm the policy is attached to the workload:
   Copy

   workloadmgr workload-show <workload-id>
   

3. If the policy fields are blank, modify the workload to reattach a schedule:
   Copy

   workloadmgr workload-modify \
     --workload_id <workload-id> \
     --fullbackup_interval 7 \
     --retention_policy_value 30
   

4. Check the wlm-api log for scheduling errors: /var/log/workloadmgr/workloadmgr-api.log.

File-level restore mount target does not appear in Horizon

Symptom: After importing a workload, the File Recovery Manager image does not appear as a valid mount option in the Horizon Workloads panel.

Likely cause: The File Recovery Manager Glance image on the destination cloud is missing the required property.

Fix:

openstack image set --property tvault_recovery_manager=yes <file-recovery-manager-image-id>

Refresh the Horizon page and the image should now appear as a selectable mount target.