Migrate Solution Kits

Migrations that involve Solution Kits involve additional consideration. By default, the does not include Solution Kits, even when the "--all" switch is used. How you intend to migrate dictates the parameters and sequence of events:

gateway91

Migrations that involve Solution Kits involve additional consideration. By default, the migrateOut command does not include Solution Kits, even when the "--all" switch is used. How you intend to migrate dictates the parameters and sequence of events:

Scenario 1:
You are backing up the Gateway to be restored on an empty target Gateway.

Scenario 2:
You are migrating a source Gateway into an operational target Gateway (for example, from "Test" to "Production" environments).

(1) Migrating using Scenario 2 requires knowledge of the REST Management API and scripting. (2) The Solution Kit ID is the GUID from SolutionKit.xml
.

Migration is designed for Gateways of the same version. While it is possible to migrate between different versions of Gateways, the results are not guaranteed. Such migrations should be attempted only by advanced users who are aware of the consequences.

Scenario 1: Backing Up

There are several ways to back up a Gateway, one of which involves the using the migrateOut command to export entities from the Gateway. If Solution Kits are in the source Gateway, be sure to include the "--includeSolutionKits" parameter. If this parameter is omitted, Solution Kits are not included, even when the "--all" parameter is used. Note:
This scenario does not
require replay scripts (described in the next scenario).

Scenario 2: Migrating

Migrating a solution kit from a source Gateway to a operational target Gateway is slightly more involved. In this scenario, you perform a full migrateOut (use "--all" but do not include "--includeSolutionKits") along with executing a replay script
that reproduces the Solution Kits on the target Gateway.

What is a "replay script"?
A replay script is one or more "headless" Solution Kit Manager operations saved into a script to be run on the target Gateway. These headless operations are calls to the REST Management API. The "Full Migration Example" below provides a detailed example of a replay script.

For more information, see REST Management API. Once the API is installed, you can view reference documentation for the headless Solution Kit Manager as follows:

Access the REST Management API documentation.

Select Resources
from the table of contents at the left.

Select Solution Kit Manager
from the list.

Full Migration Example

This example assumes:

Both the source and target Gateways are operational.

The Gateway Migration Utility (GMU) can access both the source and target Gateways. For more information, see Configure GMU and Gateways for Migration.

There are user configurable entities (UCE) that must be included in the migration. Examples of UCE are encapsulated assertions and JDBC connections.

In this example you will create several .properties files. These are simply text files that contain the parameters to be used by various GMU commands. Using these files is simply an alternative to appending a lengthy list of parameters to a GMU command. It makes the intent of the command easier to understand and helps reduce errors. It also makes it much easier to reuse the commands.

On Source Gateway: Create Replay Script

Create a text file named uce_out.properties
and populate it with the following:

host=<sourceGatewayHostname>username=<sourceGatewayAdminUser>password=<sourceGatewayEncodedAdminPassword>port=<sourceGatewayPort>header=l7-key-passphrase:<Base64Password–see below for details>method=GETpath=1.0/bundlequery=password=13f1eabb9dc68a1d2504ece2e77bd062&encryptSecrets=true&defaultAction=NewOrUpdateresponse=uceOut.xml

Some tips about the uce_out.properties
file:

For password
, you can generate an encoded admin password using the Gateway Migration Utility with this command: ./GatewayMigrationUtility.sh encodePassword

For header
, create a password and then convert this to Base64 using any publicly-available conversion utility. The l7-key-passphrase
must be specified as a Base64 password. Be sure to make a note of the plaintext version of this password, as you will need it later.

To obtain the ID of the entity to export, use the REST Management API to list it.

Include "encryptSecrets=true"
in the query when exporting an entity that contains passwords (for example: JDBC connections, Cassandra connections, stored password, private keys). When encryptSecrets=true is used, add the encoded passphrase for encryption in the header. This is used later during migrateIn in the encryptionPassphrase paramenter.

Run the following command to create an export bundle containing only the UCE. This bundle is named
uceOut.xml
.

./GatewayMigrationUtility.sh restman -z uce_out.properties

Open uceOut.xml
in a text editor and replace the outer envelope:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
    <l7:Name>Bundle</l7:Name>
    <l7:Type>BUNDLE</l7:Type>
    <l7:TimeStamp>2016-01-27T17:03:41.439-08:00</l7:TimeStamp>
    <l7:Link rel="self" uri="https://sourceGateway.mycompany.com:8443/restman/1.0/bundle?password=13f1eabb9dc68a1d2504ece2e77bd062&encryptSecrets=true&defaultAction=NewOrUpdate"/>
    <l7:Resource>
        <l7:Bundle>
            <l7:References/>
            <l7:Mappings/>
        </l7:Bundle>
    </l7:Resource>
</l7:Item>

with the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<l7:Bundle xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management">
	<l7:References/>
	<l7:Mappings/>
</l7:Bundle>

Create a similar uce_in.properties
file for the import bundle. This will be used later.

host=<targetGatewayHostname>username=<targetGatewayAdminUser>password=<targetGatewayEncodedAdminPassword>port=<targetGatewayPort>results=results.xmlencryptionPassphrase=<encodedPassphrase>bundle=uceOut.xml

Some tips about the uce_in.properties
file:

For password
, you can generate an encoded admin password using the Gateway Migration Utility with this command: ./GatewayMigrationUtility.sh encodePassword

For encryptionPassphrase
, use the

same

plaintext password that was used to create the Base64-encoded password for the uce_out.properties file above and then encode it using the same ./GatewayMigrationUtility.sh encodePassword
command

Create a replay script named replayScript.sh
(but do not
run it yet). This script must contain commands to replicate all the install, upgrade, and delete commands performed on the Solution Kits in the source Gateway. The following is a simple replay script that does the following:

The first line runs the migrateIn
command using the uce_in.properies
created in step 4. This line is always required in the replay script.

The first cURL command creates a solution kit with the entity ID '522abcb01904eb370402863da79d1294'.

The second cURL command upgrades the solution kit

Create additional cURL commands as necessary to reproduce all the install, upgrade, delete actions performed on the source Solution Kit.

Note that the "--insecure" parameter for the user login should be used only for development purposes

./GatewayMigrationUtility.sh migrateIn -z uce_in.properties curl --user admin_user:the_password --insecure --form entityIdReplace=f1649a0664f1ebb6235ac238a6f71a6d::522abcb01904eb370402863da79d1294--form instanceModifier=AAA--form "file=@/<your_path>/SimpleSolutionKit-1.1.sskar" https://targetGateway.ca.com:8443/restman/1.0/solutionKitManagers curl --user admin_user:the_password --insecure --form instanceModifier=AAA--form "file=@/<your_path>/SimpleSolutionKit-1.2.sskar" https://targetGateway.ca.com:8443/restman/1.0/solutionKitManagers?id=33b16742-d62d-4095-8f8d-4db707e9ad52

Be sure to implement error handling in your replay script. For example, checking whether the UCE import is successful before installing the solution kit, or checking that the solution kit installed successfully before upgrading.

On the Source Gateway: Perform a Full Migrate Out

Create a text file named out.properties
and populate it with the following:

host=<sourceGatewayHostname>username=<sourceGatewayAdminUser>password=<sourceGatewayEncodedAdminPassword>alldefaultAction=NewOrUpdateport=<sourceGatewayPort>encryptionPassphrase=<encodedPassphrase>dest=migrateOut.xmlformat=singleFile

Some tips about the out.properties
file:

For password
, you can generate an encoded admin password using the Gateway Migration Utility with this command: ./GatewayMigrationUtility.sh encodePassword

For encryptionPassphrase
, encode any plaintext password using the ./GatewayMigrationUtility.sh encodePassword
command. Make a note of the encoded passphrase as you will need it later. Tip:
This passphrase does not need to be the same as the previously created passphrase.

Run the following command to create an export bundle containing the full Gateway. This bundle is named migrateOut.xml.

./GatewayMigrationUtility.sh migrateOut -z out.properties

On the Target Gateway: Restore Everything

Run the replayScript.sh
created earlier:

./replayScript.sh

This reproduces the Solution Kit(s) on the target Gateway, ensuring an exact match.

Create a text file named in.properties
and populate it with the following:

host=<targetGatewayHostname>username=<targetGatewayAdminUser>password=<targetGatewayEncodedAdminPassword>port=<targetGatewayPort>results=results.xmlencryptionPassphrase=<encodedPassphrase>bundle=migrateOut.xml

Some tips about the in.properties
file:

For password
, you can generate an encoded admin password using the Gateway Migration Utility with this command: ./GatewayMigrationUtility.sh encodePassword

For encryptionPassphrase
, you must use the same encoded passphrase as created in step 1 under "On the Source Gateway: Perform a Full Migrate Out" above.

Run the following command to migrate in the full export bundle created earlier:

./GatewayMigrationUtility.sh migrateIn -z in.properties

This "migrateIn" command imports the full export bundle, minus the Solution Kits which were not included.

Gateway Migration

Content feedback and comments

CA API Gateway 9.1

Migrate Solution Kits