> For the complete documentation index, see [llms.txt](https://docs.trilio.io/openstack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trilio.io/openstack/admin-guide/workload-import-and-migration.md). # 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 {% hint style="info" %} OpenStack Users can update the User ownership of a Workload by modifying the Workload. {% endhint %} 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. {% hint style="warning" %} 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. {% endhint %} ### workload-get-importworkloads-list {% hint style="warning" %} DEPRECATED: use [workload-get-import-reassign-list](#workload-get-import-reassign-list) instead. {% endhint %} To get a list of importable Workloads use the following CLI command: ``` workloadmgr workload-get-importworkloads-list [--project-id ] [--source-bt [ ...]] ``` * `--project-id ` :arrow\_right: List workloads belonging to the given project only. If not provided, all importable workloads are considered. * `--source-bt [ ...]` :arrow\_right: List workloads belonging to the given backup target(s) only. If not provided, all available Backup Targets are considered. {% hint style="info" %} 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](#job-detail-show). {% endhint %} ### workload-importworkloads {% hint style="warning" %} DEPRECATED: use [workload-import-reassign](#workload-import-reassign) instead. {% endhint %} To import Workloads into the Trilio database use the following CLI command: ``` workloadmgr workload-importworkloads [--workload-ids [ ...]] [--source-btt [ ...]] [--target-btt ] [--source-btt-all] [--inplace-upgrade] ``` * `--workload-ids [ ...]` :arrow\_right: 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 [ ...]` :arrow\_right: 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 ` :arrow\_right: 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` :arrow\_right: Search in all Backup Target Types. Only allowed when `--workload-ids` is **NOT** provided. * `--inplace-upgrade` :arrow\_right: 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](#workload-inplace-db-upgrade) command instead. The command returns a `JOB-ID`; track the progress with [job-detail-show](#job-detail-show). ## Orphaned Workloads {% hint style="warning" %} DEPRECATED: use [workload-get-import-reassign-list](#workload-get-import-reassign-list) with `--orphaned` instead. The former `--generate_yaml` option has been replaced by [job-detail-show --generate-yaml](#job-detail-show). {% endhint %} 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}` :arrow\_right: Set to True if you want to list workloads from other clouds as well. Default is False. {% hint style="info" %} 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](#job-detail-show) and generate a reassign map with `workloadmgr job-detail-show --generate-yaml`. {% endhint %} {% hint style="info" %} 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. {% endhint %} ## 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. {% hint style="warning" %} DEPRECATED: use [workload-import-reassign](#workload-import-reassign) instead. {% endhint %} {% hint style="danger" %} 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. {% endhint %} Use the following CLI command to reassign a Workload: ``` workloadmgr workload-reassign-workloads [--old_tenant_ids ] [--new_tenant_id ] [--workload-ids [ ...]] [--user_id ] [--migrate_cloud {True,False}] [--source-btt [ ...]] [--source-btt-all] [--map_file ] ``` * `--old_tenant_ids ` :arrow\_right: 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 ` :arrow\_right: 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 [ ...]` :arrow\_right: 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 ` :arrow\_right: Specify the user id to which the workloads need to be reassigned. Only one target user can be specified. * `--migrate_cloud {True,False}` :arrow\_right: Set to True if you want to reassign workloads from other clouds as well. Default is False. * `--source-btt [ ...]` :arrow\_right: 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` :arrow\_right: 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 ` :arrow\_right: Path (relative or absolute) to a reassign map file in YAML format, listing old workloads mapped to new tenants. See the [sample mapping file](#workload-import-reassign). {% hint style="info" %} 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-ID`s of the asynchronous import operations; track those with [job-detail-show](#job-detail-show). {% endhint %} ## 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 `. 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 `. 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-ID`s. 4. **Track** the operation with `workloadmgr job-detail-show `. Jobs can be listed with `workloadmgr job-list` and cleaned up with `workloadmgr job-delete`. {% hint style="info" %} All Import & Reassign commands are admin-only operations. {% endhint %} ### 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 [ ...]] [--orphaned] [--source-btt [ ...]] [--source-btt-all] [--migrate-cloud] ``` * `--old-tenant-ids [ ...]` :arrow\_right: List workloads belonging to the given old tenant ids. Mutually exclusive with `--orphaned`. * `--orphaned` :arrow\_right: 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 [ ...]` :arrow\_right: 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` :arrow\_right: Search in all Backup Target Types. Mutually exclusive with `--source-btt`. * `--migrate-cloud` :arrow\_right: 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 | +--------+ ``` {% hint style="info" %} 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. {% endhint %} ### job-detail-show ``` workloadmgr job-detail-show [--generate-yaml] [--output ] ``` * `` :arrow\_right: The job id returned by any Import & Reassign command. * `--generate-yaml` :arrow\_right: 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 ` :arrow\_right: 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` :arrow\_right: Workloads found on the Backup Target that are not known to this Trilio installation. These will be imported. * `workload_to_reassign` :arrow\_right: Workloads that already exist in the Trilio database. These will only be reassigned to the new owner. * `source_btt` :arrow\_right: The Backup Target Type id the workloads were found in. * `current_cloud` :arrow\_right: Whether the workload's owning tenant belongs to the current cloud. If False, `--migrate-cloud` is required to import/reassign it. * `error_message` :arrow\_right: 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 [ ...]] [--old-tenant-ids [ ...]] [--new-tenant-id ] [--user-id ] [--migrate-cloud] [--source-btt [ ...]] [--source-btt-all] [--target-btt ] [--map-file ] ``` * `--workload-ids [ ...]` :arrow\_right: Specify workload ids to import/reassign. Mutually exclusive with `--old-tenant-ids`. * `--old-tenant-ids [ ...]` :arrow\_right: Specify old tenant ids whose workloads need to be imported/reassigned. Mutually exclusive with `--workload-ids`. * `--new-tenant-id ` :arrow\_right: 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 ` :arrow\_right: 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` :arrow\_right: Include workloads from other clouds as well. Default is False. * `--source-btt [ ...]` :arrow\_right: 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` :arrow\_right: Search in all Backup Target Types. Not allowed together with `--workload-ids`. Mutually exclusive with `--source-btt`. * `--target-btt ` :arrow\_right: Backup Target Type id to assign the imported workloads to. If not provided, the workload's original Backup Target Type is used. * `--map-file ` :arrow\_right: 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. {% hint style="warning" %} 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. {% endhint %} The command prints workloads that failed validation, workloads that were reassigned immediately (already present in the database) and the `JOB-ID`s of the asynchronous import operations: ``` Track progress using cmd: workloadmgr job-detail-show +--------+ | JOB-ID | +--------+ | 102 | +--------+ ``` A sample mapping file with explanations is shown below. The easiest way to produce one is `workloadmgr job-detail-show --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 ] [--marker ] [--action ] ``` * `--limit ` :arrow\_right: Maximum number of jobs to return. * `--marker ` :arrow\_right: 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 ` :arrow\_right: 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 [ ...] ``` * ` [ ...]` :arrow\_right: 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](#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 /workload_/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' /workload_/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 ``` 4. Find & replace the backup\_target\_types property of the workload and it’s all respective snapshots ``` a. grep -rl 'old_BTT' /workload_ | xargs sed -i 's///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' ``` 5. Find & replace the backup\_media\_target property of the workload and it’s all respective snapshots ``` a. grep -rl '' /workload_ | xargs sed -i 's///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. ``` 6. Verify the changes ``` a. The following commands must show the files having the updated changes. i. grep -rl 'new_BTT' /workload_ ii. grep -rl '' /workload_ ``` 7. Now try reassigning the workload.