Custom Migration Best Practices

Review these Illumio-recommended best practices before you start the migration.

Minimize changes to your environment during the on-prem-to-SaaS migration. Any policy adjustment on-prem will be synced to SaaS on the next pcemigrate sync. Do not change any policy objects on SaaS during the migration from on-prem, as the pcemigrate sync is one-directional for policy objects.
Warning
Do not change any policy objects on SaaS during the migration.
Tip
Next, review Minimize Environmental Changes During the Migration.

Pairing of new VENs to SaaS is not supported.

A new VEN paired to SaaS that was not present on-prem when the database backup was taken will not be synced by the Migration Tool.

This creates an inconsistency between on-prem and SaaS workloads, which should be equivalent.

While you are not actively migrating VENs, run the pcemigrate sync command at regular intervals. Illumio recommends running this every 6 hours.
Important
Schedule a cron job to run the pcemigrate sync command at regular intervals. Make sure that each cron job does not overlap with the previous run by setting the cron interval longer than the typical execution time of pcemigrate sync.
The required interval depends on the size of your environment (the recommended time is six hours).
Disable this cron job during the VEN migration from on-prem to SaaS and re-enable it only after the migration batch is complete.

Migrating a VEN from on-prem to SaaS typically takes up to 4 heartbeats (about 20 minutes at the default 5-minute interval). After 6 heartbeats, run pcemigrate transplant-vens-status to verify which VENs have migrated.
Important
VENs with a status of Underway or Unsuccessful did not migrate in the current batch. You must review these before attempting another migration in a subsequent batch.
Illumio recommends that you do not unpair VENs for workloads included in the initial database dump until the migration is complete. Unpairing such VENs may require ad hoc recovery procedures to keep policies and actors in sync between on-prem and SaaS environments. They may cause pcemigrate sync to fail until the inconsistencies are resolved.
VENs paired on the on-prem PCE after the database dump will be migrated using the standard migration process (also known as legacy or small customer), which requires either deploying the venmigrate tool on hosts or deactivating/activating using other configuration/deployment automation tools such as Chef.
These limitations apply to such workloads:
- Avoid duplicate hostname for managed workloads. If there are duplicate hostnames, only migrate one.
- Follow the standard VEN migration procedure, including creating unmanaged workloads on-prem using the pcemigrate create-unmanaged-workload command if venmigrate is not used, before you migrate the VENs.
- No rule should reference such managed workloads directly.

When updating the workload data is stopped, and users want to restart the process:
- Updates should be applied at the location where the VEN is currently pointing. Therefore, users need to point the job at SaaS rather than on-prem.
- When enabling the job, users should note that it will require more frequent syncs. The better option is to wait until all VENs are migrated. Minimizing sync operations is always recommended.
If some VENs were not transplanted, users should deactivate them on-prem and reactivate them on SaaS. For any VENs that are not transplanting, it is recommended to unpair and then re-pair them.

The migration tool cannot process VENs that cannot communicate with the PCE. The VEN will not migrate if it is in any of the following states: suspended, offline, warning, or error.

Illumio Core 25.2.10 Install, Configure, Upgrade (On-Prem)