Troubleshooting the form-factor migration from v2018

Troubleshoot problems with migrating from v2018 to v10 on a different form factor.

Script help

You can access help for all the migration scripts by using the --help argument:
python3 <script_file_name> --help

Restarting migration

On the target system, if the register_gateway_portals_in_target.py, update_to_new_portals.py, or update_to_new_gateways.py scripts fail, run the load script 3 again, with the -reset_gateway_portal flag as shown:
python3 load_v2018_data_to_v10.py ... -reset_gateway_portal
This resets the portals and deletes the gateway pods.
Note: If you deleted the data directory after you registered the Gateways or Portals, but want to use the same target API Connect system that you already installed, then extract the data again:

Factory reset of portal subsystem

The migration load script with -reset_gateway_portal does a factory reset of your portal subsystems. Portals can also be factory reset by following these steps:
  1. Log in to the portal www pod admin container: 
    kubectl exec -it <portal www pod> -c admin -n <apic namespace> -- bash
  2. Run the command: 
    curl -X DELETE -k --cert /etc/nginx/ssl/portal-director-client-both.pem  https://localhost:3009/v2/portal/factory-reset
  3. Use the list_sites command to check that all sites are deleted.
  4. Check health of the Portal subsystem.

Avoid error when a gateway is already registered to another API manager

Error messages
Error: An error occurred communicating with the gateways subsystem at 'some_url' (status: 400, response: '"Unable to perform initial registration for API Management.
Error: The API Connect Gateway Service is already registered to another API Manager instance"

To fix this first try restarting the gateways, or if you are using Gateway appliances, restart them. If the problem persists, reload the v2018 data with the load_v2018_data_to_v10.py script and repeat the remaining steps of the migration process, starting with Step 5 in Restoring the v2018 data to the v10 target deployment.

x-ibm-gateway-cors-allow-credentials-when-no-cors-policy API property is deprecated in v10.

In v2018, when cross-origin resource sharing (CORS) is enabled for an API, every response to a CORS request contains the header:

Access-Control-Allow-Credentials: true

Inclusion of Access-Control-Allow-Credentials (ACAC) does not provide optimal security, so starting with v2018.4.1.17, an API property can be set to prevent this header from being returned:

Name: x-ibm-gateway-cors-allow-credentials-when-no-cors-policy
Collection: *
Value (string): off

The Collection property refers to a specific Catalog to which a property value applies. The "*" value means the value applies to all catalogs. You can either specify * or a Catalog (collection) name.

The property can also be set by using the DataPower CLI:

api-definition myAPI
  property x-ibm-gateway-cors-allow-credentials-when-no-cors-policy * off
exit

Important: The value of this property must be exactly the string off (case-sensitive) in order to remove the header.

It is only possible to turn off this header, or leave it on, for an entire API. In order to have more control, such as returning the header for some origins and not others, you must upgrade to v10 and use the CORS policy feature. For more info, see:

In API Connect 10.0.3.0 or later, the x-ibm-gateway-cors-allow-credentials-when-no-cors-policy property works, but only for API definitions which do NOT contain a cors-policy. You cannot define both this property and a CORS Policy on the same API definition.

This property is deprecated in v10: a warning will be written to the log for every CORS request received by an API whose definition contains this property.

For v10, the recommended way to ensure the ACAC header does not appear in CORS responses is to add a CORS policy to the API definition. In v10, any API definition which has a cors-policy defined will NOT return the ACAC header by default . Note that it is possible in the CORS policy rules to explicitly return the ACAC header for some or all origins.

If you move your configuration from Version 2018 to 10.0.3.0 or later, and have this custom property defined in your API definitions, you will not see any change in behavior, other than new warnings in the log. This property will remove the ACAC header for any API definition where it appears.

If, when you move your configuration from Version 2018 to Version 10, you want to have the ACAC header present in the CORS responses, you can leave the API definitions as-is (without the new property defined) and the ACAC header will be returned, as long as a cors-policy is not added to the API definition. Note also that even with a CORS policy defined for an API, the ACAC header can be returned if desired by explicitly allowing it in the rules of the CORS policy.

Note that the x-ibm-gateway-cors-allow-credentials-when-no-cors-policy property in an API definition:

  • Will cause a commit-time error in v10 if a cors-policy is also present in the same API definition
  • Will NOT work in v10 or v2018 to turn ON the ACAC header; it can ONLY be used to turn OFF the header. Explanation:
    • In v2018, ACAC is on by default
    • In v10, without cors-policy, ACAC is on by default
    • In v10, with cors-policy, ACAC can be turned on for specific origins via rules in cors-policy