Start Your VEN Migration in Batches

After the initial replication of policy objects and workloads to the Illumio SaaS is complete, migrate VENs from the on-prem PCE to the Illumio SaaS in batches.

Important

If the source PCE is a supercluster, all VENs in the batch must be paired with the same region.

Migration is completed by a region or cluster member. When creating HREF lists, make sure that objects belong to the specific region or cluster member that is being migrated.

The migration process is initiated with the pcemigrate transplant-vens command.

Run a sync before you start the migration with pcemigrate sync.

pcemigrate sync --from-pce <on-prem-pce> --to-pce <saas-pce> --no-prompt

Transplant the VENs from the on-prem PCE to SaaS

Perform migrations from one source PCE at a time.
All VENs in a migration batch must belong to the same PCE. If your on-prem environment includes multiple PCEs, group the VENs by the PCE owning these objects and migrate each group as a separate batch.
Example: If your supercluster contains three PCEs, create three separate migration batches, one per PCE.
Important
Mixing VENs from multiple regions (different PCEs) in a single migration is not supported. This will result in inconsistent state and may require manual remediation such as unpairing and re-pairing.
```
pcemigrate transplant-vens --from-pce <on-prem-pce> --to-pce <saas-pce> --href-file /path/to/href-file.json 
```
The href-file uses the following format. The href is a list of all the VENs to be moved in this batch.
```
[
 {
   "href": "/orgs/1/vens/6f408598-8963-44fd-9afb-72c909b100a6"
 },
 {
   "href": "/orgs/1/vens/b8fc4e13-34de-49a8-9ff6-42ce0ac70951"
 }
]
```

Check the VEN transplant status

Run the following command to check the VEN transplant status.

pcemigrate transplant-vens-status --from-pce <on-prem> --to-pce <saas> --href-file <path-to-href-json-file> --check-source-heartbeat

For all options, see the command reference for pcemigrate transplant-vens-status.

The href-json-file uses the following format.

[
 {
   "href": "/orgs/1/vens/6f408598-8963-44fd-9afb-72c909b100a6"
 },
 {
   "href": "/orgs/1/vens/b8fc4e13-34de-49a8-9ff6-42ce0ac70951"
 }
]

Verify that the transplant has succeeded by reviewing the .csv file.

Caution

If the migration status remains In Progress or changes to Unsuccessful after four to five heartbeats, the migration of that VEN is considered unsuccessful.

Review the VEN status output file (csv) to find the last heartbeat time before you start another migration.

Sample of VEN Migrate status CSV file:

src_href,status,dst_href,name,hostname,last_heartbeat,migrated_at
/orgs/1/vens/979b26e9-9dde-4222-a78a-2ed4232f0e63,SUCCESS,/orgs/33/vens/112ec099-e7ef-4bf6-967c-d0a6b62b195f,vm3,vm3,2026-03-21T10:01:18.183355Z,2026-03-17T01:21:01.882300Z
/orgs/1/vens/703f81d0-5a30-40c6-85af-60d7b2288ea6,UNKNOWN,,,vm0,2026-03-21T09:59:33.923000Z,
/orgs/1/vens/bc8d038d-5ec1-4f03-8345-f44c8fd2d75c,SUCCESS,/orgs/33/vens/2a5e2270-33d7-4049-b3d6-474b4b3087b4,vm4,vm4,2026-03-21T10:01:28.705951Z,2026-03-17T02:51:27.807307Z
/orgs/1/vens/eabea77f-5058-4334-8906-070fb78cc445,UNKNOWN,,,vm102,2026-03-09T20:51:29.826000Z,

The file contains the following columns:

src_href: Href of VEN on the source PCE
status: Status of the VEN migration (SUCCESS, UNKNOWN, FAILED_AFTER_MIGRATE)
dst_href: href of the VEN after migration to the target PCE
name: Name of the workload
hostname: hostname of the workload
last_heartbeat: Timestamp of the last heartbeat received on the target PCE if dst_href is determined on the source PCE.
migrated_at: Corresponds to the managed since timestamp of the VEN on the target PCE.

Synchronize the PCEs

Note

Make sure that the syncs occur before and after the VEN transplant.

Synchronize the changes between the source (only the leader in a supercluster) and the target after every batch you migrate.
```
pcemigrate sync --from-pce <on-prem-pce> --to-pce <saas-pce>
```
Warning
Wait for On‑Prem Propagation Before You Sync
When making policy changes on-prem, wait for at least 10 minutes after the last change before starting a sync between the on-prem and SaaS environments.
You can make multiple policy updates, but do not start the sync until all changes have been fully replicated across all on-prem nodes. Wait for at least 10 minutes after the final change before initiating the sync.
Only changes that have completed on-prem replication are included in a single SaaS sync.
Note
If your migration takes longer than a day, run the pcemigrate sync as a scheduled task (cron job) that runs several times a day automatically.

Repeat for additional batches of VENs

Make sure the pcemigrate sync is complete.
Repeat steps 1 through 4 till all VENs are migrated to SaaS.

Install, Configure, and Upgrade Guide for 26.x