Workload Import & Migration

Each Trilio Workload has a dedicated owner. The ownership of a Workload is defined by:

• OpenStack User - The OpenStack User-ID is assigned to a Workload

• OpenStack Project - The OpenStack Project-ID is assigned to a Workload

• OpenStack Cloud - The Trilio Serviceuser-ID is assigned to a Workload

OpenStack Users can update the User ownership of a Workload by modifying the Workload.

This ownership secures, that only the owners of a Workload are able to work with it.

OpenStack Administrators can reassign Workloads or reimport Workloads from older Trilio installations.

Import workloads

Workload import allows to import Workloads existing on the Backup Target into the Trilio database.

The Workload import is designed to import Workloads, which are owned by the Cloud.

It will not import or list any Workloads that are owned by a different cloud.

workload-get-importworkloads-list

DEPRECATED: use workload-get-import-reassign-list instead.

To get a list of importable Workloads use the following CLI command:

workloadmgr workload-get-importworkloads-list [--project-id <project-id>]
                                              [--source-bt <source-bt> [<source-bt> ...]]

• --project-id <project-id> ➡️ List workloads belonging to the given project only. If not provided, all importable workloads are considered.

• --source-bt <source-bt> [<source-bt> ...] ➡️ List workloads belonging to the given backup target(s) only. If not provided, all available Backup Targets are considered.

Response change: the command no longer prints the importable workload list directly. It now returns a JOB-ID; fetch the importable workload list with job-detail-show.

workload-importworkloads

DEPRECATED: use workload-import-reassign instead.

To import Workloads into the Trilio database use the following CLI command:

workloadmgr workload-importworkloads [--workload-ids <workload_ids> [<workload_ids> ...]]
                                     [--source-btt <source-btt> [<source-btt> ...]]
                                     [--target-btt <target-btt>]
                                     [--source-btt-all]
                                     [--inplace-upgrade]

• --workload-ids <workload_ids> [<workload_ids> ...] ➡️ Specify workload ids to import only the specified workloads. If not provided, all available workloads from the source Backup Target Type are imported.

• --source-btt <source-btt> [<source-btt> ...] ➡️ Search workloads in the given Backup Target Type ids. If not provided, the default Backup Target Type is considered. Only a single --source-btt is allowed when --workload-ids is provided.

• --target-btt <target-btt> ➡️ Backup Target Type id to assign the imported workloads to. If not provided, the workload's original Backup Target Type is used. Warning: if the Backup Target Type of a workload changes, its snapshots are not imported and the next snapshot will be a full snapshot in the newly assigned Backup Target Type.

• --source-btt-all ➡️ Search in all Backup Target Types. Only allowed when --workload-ids is NOT provided.

• --inplace-upgrade ➡️ DEPRECATED. Update all workload and policy records in the database to the current release version instead of importing. Please use the newly added workload-inplace-db-upgrade command instead.

The command returns a JOB-ID; track the progress with job-detail-show.

Orphaned Workloads

DEPRECATED: use workload-get-import-reassign-list with --orphaned instead. The former --generate_yaml option has been replaced by job-detail-show --generate-yaml.

The definition of an orphaned Workload is from the perspective of a specific Trilio installation. Any workload that is located on the Backup Target Storage, but whose owning tenant/user is not valid in the current cloud, is considered orphaned.

Further is to divide between Workloads that were previously owned by Projects/Users in the same cloud or are migrated from a different cloud.

The following CLI command provides the list of orphaned workloads:

workloadmgr workload-get-orphaned-workloads-list [--migrate_cloud {True,False}]

• --migrate_cloud {True,False} ➡️ Set to True if you want to list workloads from other clouds as well. Default is False.

Response change: the command no longer prints the orphaned workload list directly and no longer accepts --generate_yaml. It now returns a JOB-ID; fetch the orphaned workload list with job-detail-show and generate a reassign map with workloadmgr job-detail-show <job-id> --generate-yaml.

Running this command against a Backup Target with many Workloads can take a bit of time. Trilio is reading the complete Storage and verifies every found Workload against the Workloads known in the database.

Reassigning Workloads

OpenStack administrators are able to reassign a Workload to a new owner. This involves the possibility to migrate a Workload from one cloud to another or between projects.

DEPRECATED: use workload-import-reassign instead.

Reassigning a workload only changes the database of the target Trilio installation. When the Workload was managed before by a different Trilio installation, will that installation not be updated.

Use the following CLI command to reassign a Workload:

workloadmgr workload-reassign-workloads
                                        [--old_tenant_ids <old_tenant_id>]
                                        [--new_tenant_id <new_tenant_id>]
                                        [--workload-ids <workload_ids> [<workload_ids> ...]]
                                        [--user_id <user_id>]
                                        [--migrate_cloud {True,False}]
                                        [--source-btt <source-btt> [<source-btt> ...]]
                                        [--source-btt-all]
                                        [--map_file <map_file>]

• --old_tenant_ids <old_tenant_id> ➡️ Specify old tenant ids from which workloads need to be reassigned to the new tenant. Specify multiple times to choose Workloads from multiple tenants.

• --new_tenant_id <new_tenant_id> ➡️ Specify the new tenant id to which the workloads need to be reassigned. Only one target tenant can be specified. Required (together with --user_id) unless --map_file is used.

• --workload-ids <workload_ids> [<workload_ids> ...] ➡️ Specify workload ids that need to be reassigned to the new tenant. If not provided, all the workloads from the old tenant get reassigned to the new tenant.

• --user_id <user_id> ➡️ Specify the user id to which the workloads need to be reassigned. Only one target user can be specified.

• --migrate_cloud {True,False} ➡️ Set to True if you want to reassign workloads from other clouds as well. Default is False.

• --source-btt <source-btt> [<source-btt> ...] ➡️ Search workloads in the given Backup Target Type ids. If not provided, the default Backup Target Type is considered. Only a single --source-btt is allowed when --workload-ids is provided.

• --source-btt-all ➡️ Search in all Backup Target Types. Only allowed when --workload-ids is NOT provided. --old_tenant_ids and --new_tenant_id must be provided to use it.

• --map_file <map_file> ➡️ Path (relative or absolute) to a reassign map file in YAML format, listing old workloads mapped to new tenants. See the sample mapping file.

Response change: the command now delegates to the unified import + reassign operation. Instead of only printing the reassigned workloads, it prints the workloads that failed validation, the workloads that were reassigned immediately (already present in the database) and the JOB-IDs of the asynchronous import operations; track those with job-detail-show.

Unified Import and Reassign workflow

Workload import, workload reassignment and orphaned workload discovery are combined into a single, job-based Import & Reassign workflow. All operations run asynchronously: each command returns a JOB-ID and the results or progress of the operation are fetched with workloadmgr job-detail-show <job-id>.

The workflow consists of the following steps:

1. Discover the workloads available for import and/or reassignment using workloadmgr workload-get-import-reassign-list. The command returns a JOB-ID.

2. Inspect the discovery results using workloadmgr job-detail-show <job-id>. Add --generate-yaml to produce a pre-filled reassign map file.

3. Execute the import/reassign operation using workloadmgr workload-import-reassign. The command returns one or more JOB-IDs.

4. Track the operation with workloadmgr job-detail-show <job-id>. Jobs can be listed with workloadmgr job-list and cleaned up with workloadmgr job-delete.

All Import & Reassign commands are admin-only operations.

workload-get-import-reassign-list

The unified list command discovers all workloads on the Backup Target(s) that can be imported into the Trilio database or reassigned to a new owner.

workloadmgr workload-get-import-reassign-list
                                        [--old-tenant-ids <old_tenant_id> [<old_tenant_id> ...]]
                                        [--orphaned]
                                        [--source-btt <source-btt> [<source-btt> ...]]
                                        [--source-btt-all]
                                        [--migrate-cloud]

• --old-tenant-ids <old_tenant_id> [<old_tenant_id> ...] ➡️ List workloads belonging to the given old tenant ids. Mutually exclusive with --orphaned.

• --orphaned ➡️ Discover orphaned workloads (workloads whose tenant/user is not valid in the current cloud) without specifying any ids. Mutually exclusive with --old-tenant-ids. Combine with --migrate-cloud to also discover orphaned workloads on other clouds' backup targets. This replaces the deprecated workload-get-orphaned-workloads-list command.

• --source-btt <source-btt> [<source-btt> ...] ➡️ Search workloads in the given Backup Target Type ids only. Mutually exclusive with --source-btt-all. If neither is provided, the default Backup Target Type is considered.

• --source-btt-all ➡️ Search in all Backup Target Types. Mutually exclusive with --source-btt.

• --migrate-cloud ➡️ Include workloads owned by other clouds as well. Default is False.

At least one of --old-tenant-ids, --orphaned, --source-btt or --source-btt-all must be provided.

The command returns a JOB-ID:

+--------+
| JOB-ID |
+--------+
| 101    |
+--------+

Running the discovery against a Backup Target with many Workloads can take a bit of time. Trilio is reading the complete storage and verifies every found Workload against the Workloads known in the database. Re-run job-detail-show until the job status is no longer in progress.

job-detail-show

workloadmgr job-detail-show <jobid> [--generate-yaml] [--output <output>]

• <jobid> ➡️ The job id returned by any Import & Reassign command.

• --generate-yaml ➡️ For a discovery job (list_import_reassign), write a reassign_map.yaml pre-filled with the discovered workload ids to the system temporary directory. Fill in the new_tenant_id/user_id/source_btt placeholders and feed the file back via workloadmgr workload-import-reassign --map-file. This replaces the deprecated workload-get-orphaned-workloads-list --generate_yaml output.

• --output <output> ➡️ Optional file path to save a downloadable artifact produced by other job types (e.g. the tenants-chargeback CSV job). Not used for Import & Reassign jobs.

For a discovery job the output contains the job header and, per Backup Target Type searched, the discovered workloads:

• workload_to_import ➡️ Workloads found on the Backup Target that are not known to this Trilio installation. These will be imported.

• workload_to_reassign ➡️ Workloads that already exist in the Trilio database. These will only be reassigned to the new owner.

• source_btt ➡️ The Backup Target Type id the workloads were found in.

• current_cloud ➡️ Whether the workload's owning tenant belongs to the current cloud. If False, --migrate-cloud is required to import/reassign it.

• error_message ➡️ Any error hit while listing the workloads of this Backup Target Type.

For an import/reassign operation job the output contains the job header followed by the progress of the reassigned workloads (workload_to_update, updated_workloads, source_btt, error_message) and of the imported workloads (workload_to_import, source_btt, error_message, wl_import_job_id, wl_import_job_details).

workload-import-reassign

The unified operation imports workloads from the Backup Target and, when a reassignment target is provided, reassigns them to that tenant/user.

workloadmgr workload-import-reassign
                                        [--workload-ids <workload_ids> [<workload_ids> ...]]
                                        [--old-tenant-ids <old_tenant_ids> [<old_tenant_ids> ...]]
                                        [--new-tenant-id <new_tenant_id>]
                                        [--user-id <user_id>]
                                        [--migrate-cloud]
                                        [--source-btt <source-btt> [<source-btt> ...]]
                                        [--source-btt-all]
                                        [--target-btt <target-btt>]
                                        [--map-file <map_file>]

• --workload-ids <workload_ids> [<workload_ids> ...] ➡️ Specify workload ids to import/reassign. Mutually exclusive with --old-tenant-ids.

• --old-tenant-ids <old_tenant_ids> [<old_tenant_ids> ...] ➡️ Specify old tenant ids whose workloads need to be imported/reassigned. Mutually exclusive with --workload-ids.

• --new-tenant-id <new_tenant_id> ➡️ Optional. New tenant id to reassign the workloads to. If set, --user-id is required. When omitted, the command performs a pure import and the workloads keep their original owner.

• --user-id <user_id> ➡️ Optional. User id to reassign the workloads to. Required when --new-tenant-id is provided. The user must exist in the new tenant and hold the trustee role.

• --migrate-cloud ➡️ Include workloads from other clouds as well. Default is False.

• --source-btt <source-btt> [<source-btt> ...] ➡️ Search workloads in the given Backup Target Type ids. If not provided, the default Backup Target Type is considered. Multiple values are allowed, including together with --workload-ids; when a workload exists in more than one Backup Target Type, the latest copy is imported.

• --source-btt-all ➡️ Search in all Backup Target Types. Not allowed together with --workload-ids. Mutually exclusive with --source-btt.

• --target-btt <target-btt> ➡️ Backup Target Type id to assign the imported workloads to. If not provided, the workload's original Backup Target Type is used.

• --map-file <map_file> ➡️ Path (relative or absolute) to a YAML reassign map file describing multiple mappings in one call. Mutually exclusive with --workload-ids, --old-tenant-ids, --new-tenant-id and --user-id; the remaining options are ignored, as each mapping in the file carries its own values.

One of --workload-ids, --old-tenant-ids or --map-file must be provided.

If --target-btt changes the Backup Target Type of a workload, its existing snapshots are not imported and the next snapshot in the newly assigned Backup Target Type will be a full snapshot.

The command prints workloads that failed validation, workloads that were reassigned immediately (already present in the database) and the JOB-IDs of the asynchronous import operations:

Track progress using cmd: workloadmgr job-detail-show <job-id>
+--------+
| JOB-ID |
+--------+
| 102    |
+--------+

A sample mapping file with explanations is shown below. The easiest way to produce one is workloadmgr job-detail-show <jobid> --generate-yaml on a discovery job:

reassign_mappings:
   - old_tenant_ids: [] # provide either a list of old_tenant_ids or workload_ids
     new_tenant_id: new_tenant_id # optional; omit together with user_id for a pure import
     user_id: user_id # required when new_tenant_id is provided
     source_btt: [] # list of source BTT ids in which the workloads are searched
     source_btt_all: False # True searches all available BTTs (not allowed with workload_ids)
     workload_ids: [] # provide either a list of old_tenant_ids or workload_ids
     migrate_cloud: False # True also reassigns workloads from other clouds
     target_btt: null # optional; BTT id to assign the imported workloads to
     upgrade: True # optional; upgrade imported records to the current release schema

   - old_tenant_ids: []
     new_tenant_id: new_tenant_id
     user_id: user_id
     source_btt: []
     source_btt_all: False
     workload_ids: []
     migrate_cloud: False

job-list

All jobs created by the Import & Reassign workflow (and every other job type job-detail-show can render) can be listed, newest first and paginated:

workloadmgr job-list [--limit <limit>] [--marker <marker>] [--action <action>]

• --limit <limit> ➡️ Maximum number of jobs to return.

• --marker <marker> ➡️ Return jobs older than (with a job id less than) this job id. Use the last job id of the previous page to fetch the next page.

• --action <action> ➡️ Narrow to the given job action(s). Repeat the option to pass several. If not provided, all job types are listed. One of: import_workloads, list_importable_workloads, inplace_upgrade_db_records, tenants-chargeback-csv, list_import_reassign, list_reassign_workloads, import_reassign, workload_reassign.

The Import & Reassign workflow uses the actions list_import_reassign (discovery jobs) and import_reassign (operation jobs).

job-delete

Job records that are no longer needed can be deleted in bulk:

workloadmgr job-delete <jobid> [<jobid> ...]

• <jobid> [<jobid> ...] ➡️ One or more job ids to delete (space separated for bulk deletion). Deleting a job also removes its detail records.

workload-inplace-db-upgrade

After upgrading Trilio, existing workload and policy database records can be converted to the current release schema without re-importing them:

workloadmgr workload-inplace-db-upgrade

The command takes no arguments and runs cloud-wide across all backup targets: it converts old policy and workload job-schedule fields to the current schema and refreshes each workload's backup-target-type metadata. It returns a JOB-ID; track the progress with job-detail-show. This replaces the deprecated workload-importworkloads --inplace-upgrade option.

Reassigning workloads on immutable backup targets

Note:- We cannot reassign the immutable backup target workload from one cloud to another. To do this, we need to follow the steps outlined below

Steps:-

1. Download the immutable workload directory from its mount path and upload/copy it to the non-immutable backup target mount path.

2. We need to update the backup_target_types and backup_media_target metadata property of the workload and all it’s snapshots at backup target to the current backup target where it exists. Here reference Please perform following steps to accomplish the task.

3. Check the original backup_target_types and backup_media_target metadata property of the workload using either less or jq command. If you already knows this information then you may skip this step.

    a. Using less command
        i. less <file_system_mountpath>/workload_<workload_uuid>/workload_db
        ii. Example
            1. less /var/trilio/triliovault-mounts/L2hvbWUva29sbGEv/workload_385d0e94-d602-4963-96c2-28bebea352f1/workload_db
        iii. search backup_target_types and backup_media_target in the file and note down it’s respective values

    b. Using jq command
        i. jq '.metadata[] | select(.key == "backup_media_target") | .value' <file_system_mountpath>/workload_<workload_uuid>/workload_db
        ii. Example
            jq '.metadata[] | select(.key == "backup_target_types") | .value' /var/trilio/triliovault-mounts/L2hvbWUva29sbGEv/workload_385d0e94-d602-4963-96c2-28bebea352f1_backup/workload_db
        iii. search backup_target_types and backup_media_target and note down it’s respective values

1. Find & replace the backup_target_types property of the workload and it’s all respective snapshots

    a. grep -rl 'old_BTT' <file_system_mountpath>/workload_<workload_uuid> | xargs sed -i 's/<old_BTT>/<new_BTT>/g'
    b. Here,
        i. old_BTT  ---> Old Backup Target Type name
        ii. new_BTT ---> New Backup Target Type name  
    c. Example
        i. grep -rl 'nfs_1' /var/trilio/triliovault-mounts/L2hvbWUva29sbGEv/workload_385d0e94-d602-4963-96c2-28bebea352f1 | xargs sed -i 's/nfs_1/nfs_2/g'

1. Find & replace the backup_media_target property of the workload and it’s all respective snapshots

    a. grep -rl '<old_filesystem_export>' <file_system_mountpath>/workload_<workload_uuid> | xargs sed -i 's/<old_filesystem_export>/<new_filesystem_export>/g'
    b. Here,
        i. old_filesystem_export  ---> File system export path of old Backup Target
        ii. new_filesystem_export ---> File system export path of new Backup Target
    c. Note: Please make sure to use {{}} before every {{/ }} character in old_filesystem_export & new_filesystem_export places.
    d. Example
        i. grep -rl '192.168.0.51:/home/kolla/' /var/trilio/triliovault-mounts/L2hvbWUva29sbGEv/workload_385d0e94-d602-4963-96c2-28bebea352f1 | xargs sed -i 's/192.168.0.51:\/home\/kolla\//192.168.0.52:\/home\/kolla_new\//g'
        ii. Here the original filesystem export is 192.168.0.51:/home/kolla/ which we have mentioned in above command as 192.168.0.51:\/home\/kolla\/ by adding additional }} before every {{/ character. The same changes are expected for new filesystem export path as well.

1. Verify the changes

    a. The following commands must show the files having the updated changes.
        i. grep -rl 'new_BTT' <file_system_mountpath>/workload_<workload_uuid>
        ii. grep -rl '<new_filesystem_export>' <file_system_mountpath>/workload_<workload_uuid>

1. Now try reassigning the workload.