Python script to migrate hooks from PowerShell version 2 to host's Default PowerShell version.

Overview

With 6.0.3.0, the Delphix Engine will use the default PowerShell version installed on the host (hereinafter referred as default PowerShell) to perform all its operations, also the new hooks and hook templates can be created using the default PowerShell.
The existing hooks and hook templates on the engine will continue functioning using PowerShell version 2, and there will be an option to migrate them to use default PowerShell.

The article intends to introduce a Python script that can be used to migrate all the hooks and hook templates on the engine to default PowerShell. The motivation behind writing the script is to save the manual effort required in doing the migration via the UI or CLI.

Link to download the script.

Requirements for running the script

The requirements for running the script are as follows, they are the same as running any Python script in general.

1. The machine where the script is run should have Python installed.
   1. Relevant link: https://www.python.org/downloads/
   2. The script is supported for both Python 2 and Python 3 release.
2. The machine where the script is run should have the 'delphixpy' Python package installed.
   1. Relevant link: https://pypi.org/project/delphixpy/
   2. python.org documentation on installing packages and creating Python environments: Installing packages using pip and virtual environments.
   3. If the package is already installed, it should be upgraded to the latest version, the minimum delphixpy version required to run the script is 1.11.3.0
3. The Delphix Engine should be accessible from the machine where the script is run since the script makes API requests to the Delphix Engine to perform the migration,
   1. The easiest way to verify the same is to use the ping command.
      

Functionalities of the script

1. The script can migrate the hooks and hook templates in the Delphix Engine to run with default PowerShell.
   
2. The script can also migrate the hooks and hook templates back to PowerShell version 2.
   
3. It is possible to migrate only the hooks or only the hook templates.
4. If INSTALLEDPOWERSHELL feature flag is enabled on the Delphix Engine, the script will disable the same.
   

The script parameters and usage

Command examples

1. Displaying the description and usage details of the parameters for the script on the terminal

   python <path to the script> --help

2. An example command for migrating all the hook and hook templates to default PowerShell version:

   python <path to the script> --engine-addr engine.delphix.com --sys-admin-usr sysadmin --sys-admin-pwd sysadmin --admin-usr admin --admin-pwd delphix

3. An example command for migrating all the hook and hook templates to PowerShell version 2:

   python <path to the script> --engine-addr engine.delphix.com --sys-admin-usr sysadmin --sys-admin-pwd sysadmin --admin-usr admin --admin-pwd delphix --hook-ps-version ps2 --hook-templ-ps-version ps2

   Please note that this will migrate all the hooks and hook templates in the Delphix Engine to  PowerShell version two, the script does not have the functionality to perform the migration for specific hooks or hook templates.
   
   

4. An example command for migrating only the hook templates: 

   python <path to the script> --engine-addr engine.delphix.com --sys-admin-usr sysadmin --sys-admin-pwd sysadmin --admin-usr admin --admin-pwd delphix --migrate-only templates

5. An example command for running the script in debug mode:

   python <path to the script> --engine-addr engine.delphix.com --sys-admin-usr sysadmin --sys-admin-pwd sysadmin --admin-usr admin --admin-pwd delphix --debug

Common Errors while running the script:

1. If the Delphix engine is not accessible from the machine where the script is run, the connectivity test run by the script prior to running the migration will fail, and the following error will be thrown:
   

   Error occurred while connecting to the engine via the given Delphix System Administrator user:
   [Errno 8] nodename nor servname provided, or not known
   
   Error occurred while connecting to the engine via the given Delphix Administrator user: 
   [Errno 8] nodename nor servname provided, or not known

2. The connectivity test run by the script prior to running the migration will fail if the value of the required parameters provided is not correct, and the following error will be thrown:
   

   Error occurred while connecting to the engine via the given Delphix Administrator user: 
   HTTP status was 401 when doing POST '{"username": "admin", "password": "blah", "type": "LoginRequest", "target": "DOMAIN"}' to '/resources/json/delphix/login': {"type":"ErrorResult","status":"ERROR","error":{"type":"APIError","details":"Invalid username or password.","action":"Try with a different set of credentials.","id":"exception.webservices.login.failed","commandOutput":null,"diagnoses":[]}}

3. If for some reason, the script execution stops in between before migrating all the hooks and hook templates, it’s perfectly fine to run the script again; each time the script is run, the hooks and hook templates will be migrated to the specified PowerShell version.