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.

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

Step 1: Enable VEN Migration on the on-prem PCE

Upgrade all your PCE nodes with the RPM and UI packages available on the Illumio Support portal.

Enable and set the runtime data in runtime_env.yml.

Important

Enable runtime data across all nodes on-prem PCEs.

These are the additional runtime parameters to include:

inter_pce_ven_migration_enabled: true

inter_pce_ven_migration_jwt_key_pair: |
-----BEGIN RSA PRIVATE KEY-----
<source-private-key-pem>
-----END RSA PRIVATE KEY-----

inter_pce_ven_migration_token_expiry_secs: 3600

inter_pce_ven_migration_peers:
  - fqdn: "<peer-pce-fqdn>"
    enabled: true
    public_key: |
    -----BEGIN PUBLIC KEY-----
    <peer-public-key-pem>
    -----END PUBLIC KEY-----
    allowed_source_orgs:
      - <source-org-id>

skip_agent_info_timed_work_checks_org_ids:
  - <target-org-id>

workload_update_allow_list_org_ids:
  - <target-org-id>

where:

Runtime	Description
inter_pce_ven_migration_enabled: true \| false	The master switch for inter-PCE VEN migration sets the feature flag to enable the migration.
inter_pce_ven_migration_jwt_key_pair	RSA private key pair used to decrypt / handle incoming migration tokens
inter_pce_ven_migration_token_expiry_secs	Time to leave (TTL) for migration
inter_pce_ven_migration_peers[].enabled	Enable/disable a specific peer
inter_pce_ven_migration_peers[].fqdn	Peer PCE FQDN lookup is the destination PCE FQDN (i.e scp30.ilum.io)
inter_pce_ven_migration_peers[].public_key	Peer public key used for migration token trust
skip_agent_info_timed_work_checks_org_ids	Skip timed-work checks for migrated organizations
workload_update_allow_list_org_ids	Allow workload updates for migrated organizations

Note

You can apply runtime patches simultaneously, but be aware that PCE resources are diverted to the migration processes.

Restart the PCE to sync runtime_env.yml.
```
illumio-pce-ctl cluster-restart
```

Step 2: Perform pcemigrate sync before migrating the first batch of VENs

To ensure consistency before the move, run pcemigrate sync before migrating the first batch of VENs.

Step 3: Transplant 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-premises environment includes multiple PCEs, group the VENs by their owning PCE 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 batch can result in inconsistent states and may require manual remediation, such as unpairing and re-pairing.
```
pcemigrate transplant-vens --from-pce <source-pce-name> --to-pce <destination-pce-name> --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"
 }
]
```

Step 4: 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 six heartbeats, the migration is considered unsuccessful.

Review the VEN status before attempting another migration.

ven_href	Name	Host_Name	Status
`/orgs/1/vens/6f408598-8963-44fd-9afb-72c909b100a6`	test1	vm1	Migration is underway or unsuccessful.
`/orgs/1/vens/b8fc4e13-34de-49a8-9ff6-42ce0ac70951`	test2	vm2	Success
`/orgs/1/vens/4560e131-676e-49a6-9aa6-53ce0ac70951`	test3	vm3	Migration is underway or unsuccessful.

Step 5: 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 <src-pce-name> --to-pce <destination-pce-name>
```
Warning
Wait for On‑Prem Propagation Before You Sync
When making policy changes on-premises, wait for at least 10 minutes after the last change before starting a sync between the on-premises 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-premises nodes. Wait for at least 10 minutes after the final change before initiating the sync.
Only changes that have completed on-premises replication are included in a single SaaS sync.
Note
This step can be configured as a cron job.

Step 6: Repeat for additional batches of VENs

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

Install, Configure, and Upgrade Guide for 26.x