About the venmigrate Tool
The venmigrate tool streamlines VEN migration between PCEs, particularly from on-prem to Illumio Cloud PCE.
It supports Linux, macOS, and Windows, handling unpairing/deactivating the VEN from the current PCE, as well as pairing and activation on the target PCE. Custom labels are applied to migrated managed workloads, and parameters can be overridden during execution.
The tool reads migration parameters from a YAML file and workload metadata from a JSON file. It handles encrypted and non-encrypted migration parameters. When the Illumio Cloud front-end management port is accessible, it applies custom labels post-VEN pairing and deletes unmanaged workloads on Illumio Cloud after VEN activation.
When the on-premise PCE front-end management port is accessible, it creates an unmanaged workload on the on-premise PCE before VEN deactivation/unpairing and retrieves managed workload metadata from the on-premise PCE before VEN deactivation/unpairing.
Deploy the venmigrate tool on VEN hosts for seamless VEN migration.
General Syntax of the venmigrate Tool
venmigrate command\[flags] where: command is the specific command to execute. For example, migrate to migrate a VEN from one PCE to another. flags are optional parameters.
% venmigrate --help
venmigrate is a tool that helps to migrate a VEN from one PCE to another PCE.
Usage:
venmigrate [command]
Ven migration Commands:
ven-migrate-setting Sets VEN migration options.
enc-ven-migrate-conf Generates an encrypted version of venmigrate
yaml file
migrate Migrates a VEN.
apply-custom-label Applies custom labels to a managed workload.
Version Command:
version Prints the venmigrate version.
Use "venmigrate [command] --help" for more information about a command.VEN Migration Preparation Command
Generate an Encrypted venmigrate file
To generate an Encrypted venmigrate file, use theven-migrate-config command to specify parameters for VEN migration to the target PCE and custom label application post-pairing.
Key parameters include Target PCE FQDN, Front-end port, Front-end management port (Optional for custom labels), Proxy URL, Pairing Profile ID, Organization ID (Not required for custom labels), Activation code, and Migration type (Pair or Active).
Pairing involves unpairing and then pairing with the target PCE, while activation includes deactivating and then reactivating with the target PCE.
Additional parameters needed for the
venmigratecommand to retrieve workload metadata or create unmanaged workloads before deactivation/unpairing are:Source PCE FQDN
Front-end port of the source PCE
Front-end management port of the source PCE
Organization ID on the source PCE
API Key
API Key user on the source PCE
These parameters are stored in a default YAML file.
To migrate a VEN, transfer these files to the workload node:
venmigrate(Golang tool for VEN pairing/activation and label application)venmigrate.yaml(YAML file with migration parameters), andworkload-metadata.json(JSON file containing workload metadata, which the tool will try to retrieve from the source PCE if not already transferred).
ven-migrate-config
% pcemigrate ven-migrate-config --help
Generates the venmigrate yaml file.
The default file name is venmigrate.yaml, and it is stored in the current directory. Use the --ven-migrate-config flag to set a custom file. You also use the ILLUMIO_VEN_MIGRATE_CONFIG environment variable.
The command can be automated (avoid prompt) by using flags or the following environment variables:
PCE_NAME, PCE_FQDN, PCE_PORT, PCE_USER, PCE_PWD, PCE_DISABLE_TLS, PCE_PROXY.
The --update-pce and --no-prompt flags are ignored for this command.
Usage:
pcemigrate ven-migrate-config [flags]
Flags:
--ven-migrate-config string The VEN migration configuration
yaml file. The default file is
venmigrate.yaml
--source-name string The name of the source PCE.
The source PCE parameters are retrieved
from pce.yaml
--target-name string The name of the target PCE.
The target PCE parameters are retrieved
from pce.yaml
--pce string The FQDN of the target PCE.
--port int The front-end port of the target PCE.
--fe-mgmt-port int The front-end management port of the
target PCE.
--org-id int The API owner organization ID on the
target PCE
--api-user string The API user on the target PCE.
--api-key string The API key on the target PCE.
--proxy string The proxy URL to reach the target PCE
--src-pce string The FQDN of the source PCE.
--src-port int The front-end port of the source
PCE.
--src-fe-mgmt-port int The front-end management port of the
source PCE.
--src-org-id int The API owner organization ID on the
source PCE
--src-api-user string The API user on the source PCE.
--src-api-key string The API key on the source PCE.
--src-proxy string The proxy URL to reach the source
PCE.
--pairing-profile-id int The pairing profile id.
--api-version string The API version.
--activation-code string The activation code.
--migration-type string The type of VEN migration planned:
pair or activate.
--ven-dir string The path of the VEN directory.
The default path is:
/opt/illumio_ven
--ven-data-dir string The path of the VEN data directory.
The default path is: /opt/illumio_ven_data
--no-label-assignment Do not specify the label when pairing
the VEN. Labels will be inherited from
the profile.
--no-enforcement-mode Do not specify the enforcement mode when
pairing the VEN. It will be inherited
from the profile.
-h, --help help for ven-migrate-config
Global Flags (not relevant for all commands):
--config-file string The path for the pcemigrate
pce.yaml file.
--debug Enables debug-level
logging for troubleshooting.
--log-file string The path for the pcemigrate log file.
(default "pcemigrate.log")
--migrate-op When migrate-op is set to true, the Import
operation is interpreted as a copy of
objects from a different PCE as part of
a PCE migration operation. (default true)
--no-prompt Removes the user prompt when used with
update-pce.
--update-pce This command will update the PCE after
a single user prompt.
The default will just log potential changes
to workloads.
--verbose When verbose is enabled, includes the raw
API responses.
This makes pcemigrate.log increase in
size significantly.venmigrate-yaml
pce: mnctestvc13.ilabs.io port: 8443 fe_mgmt_port: 8443 pairing_profile_id: 3 api_version: v25 org_id: 655363 api_key: 4f766fdddf92455345a5463d344f56272e87af1f085a6868c699d42a190a5587 api_user: api_1250c9b3b1ce17a6c activation_code: 1bdd5740c4986c5998505098f566a5ea51c9526807538405faf327761b9dfbd5c008239c1a4757ae1 migration_type: activate ven_migrate_config_file: venmigrate.yaml src_pce: 4x2testvc49.ilabs.io src_port: 8443 src_fe_mgmt_port: 8443 src_org_id: 1 src_api_key: 28b287a455cd03feb4ba467024e4cf28f2a7278558fd4158cef218058a0646c5 src_api_user: api_155bb81f30f1ef859
Create an Encrypted venmigrate Configuration File
The venmigrate.yaml configuration file may include sensitive data such as API keys or activation codes. To secure this information, you can generate an encrypted version of the file.
The venmigrate command decrypts and utilizes the data without exposing it. By default, the encrypted configuration file is named venmigrate.enc.
enc-ven-migrate-conf
% pcemigrate enc-ven-migrate-conf --help
Generates an encrypted version of the venmigrate yaml file.
The default migration yaml file name is venmigrate.yaml and it is stored in the current directory.
The default encrypted version file name is venmigrate.enc.
Use the --ven-migrate-config and --enc-ven-migrate-config flags respectively to set custom file names.
You can also use ILLUMIO_VEN_MIGRATE_CONFIG and ILLUMIO_ENC_VEN_MIGRATE_CONFIG environment variables.
The --update-pce and --no-prompt flags are ignored for this command.
Usage:
pcemigrate enc-ven-migrate-conf [flags]
Flags:
--ven-migrate-config string The VEN migration configuration
yaml file.
The default file is venmigrate.yaml
--enc-ven-migrate-config string The encrypted VEN migration
configuration file.
The default file is venmigrate.enc.
-h, --help The help for enc-ven-migrate-conf
Global Flags (not relevant for all commands):
--config-file string The path for the pcemigrate
pce.yaml file.
--debug Enables debug-level logging
for troubleshooting.
--log-file string The path for the pcemigrate log file.
(default "pcemigrate.log")
--migrate-op When migrate-op is set to true,
the Import operation is interpreted
as a copy of objects from a different
PCE as part of a PCE migration operation.
--no-prompt Removes the user prompt when used with
update-pce.
--pce string The PCE to use in the command if not
using the default PCE.
--update-pce This command will update the PCE
after a single user prompt.
The default will just log potential
changes to workloads.
--verbose When verbose is enabled, includes
the raw API responses.
This makes pcemigrate.log increase
in size significantly. Sample of venmigrate.enc
data % ~/pcemigrate/bin/pcemigrate enc-ven-migrate-conf --ven-migrate-config venmigrate.yaml 2025-02-04 13:59:15 [INFO] - Ven migration configuration file venmigrate.yaml encrypted successfully and saved as venmigrate.enc. 2025-02-04 13:59:15 [INFO] - enc-ven-migrate-conf completed data % cat venmigrate.encw14dgeoF0wRlzWUgHkdGFDoxVQKg0qDyG39fOOAB7wB0AiQbnrMo3bSIMmhoBQ6klab7qfCrtHq8Er1fNRiILl3a2JeHw6Wa89rCyvIIlJMtigFbjM6IblL3BaTzkqI1XB/jKgcAcUk9gfgVDfYlIzPQVEWtWYt4NGC6FSSpkar9/OfG7Yq+4CKMW6rFXssiYsvTt0Nd6rqacSPOKHpbBuGJNVTkySAf0nvmXga9jdc+tnGmEmdY3UTAazaJ09rVTNIRNC44WqiRDv3lZ