Over a year ago we introduced the IntegrationRuntime as a new custom resource (Blog - What is an IntegrationRuntime ) which has all the great features of the IntegrationServer and much much more. In the future we are looking to stop shipping the IntegrationServer resource and would like customers to move all of their IntegrationServers over to IntegrationRuntimes. The fields of the custom resources are very similar but not quite the same so hopefully migration won’t be too tricky but to help with this we have now produced a tool which can be used to migrate your IntegrationRuntimes to IntegrationServers.
Tool Download
We provide the tool in both Linux amd64 and also Mac arm64 formats. These can be downloaded from the App Connect Library - CR Converter. Inside the download is two binaries. Take the file for your platform and rename it to "AppConnectCrConverter" i.e.
mv AppConnectCRConverter/AppConnectCrConverter_darwin_arm64_20240521-011517 AppConnectCRConverter/
Prepare for migration
To support the migration tool you must have App Connect operator 11.5 installed.
Perform the following steps to prepare for migrating your IntegrationServers to IntegrationRuntimes (Skip this if you are using custom images and/or external bar files)
-
Create a new instance of the App Connect dashboard with `spec.displayMode=IntegrationRuntimes`
-
In your existing dashboard go to the bars panel and export all your bar files using the “backup” button 
-
In your new dashboard import all the bar files using the “restore” button (This will re-import all your bar files using the same paths as previously used on the old dashboard) 
NOTE: When restoring the bar files into the IntegrationRuntime dashboard it will remove any existing bars from that dashboard.
Migrating runtimes
There are two ways to run the migration command. You can either provide your IntegrationServer.yaml file to the command or you can supply the name of IntegrationServer on the cluster you are logged into. Each type of migrations uses different command line parameters
To migrate an IntegrationServer called “CustomerDB” running in a cluster to an IntegrationRuntime you would perform the supply the following command line parameters:
-
-name: Name of IntegrationServer CR to get from current cluster
-
-namespace: Namespace to get IntegrationServer CR from current cluster
-
-oldDomain: Service name of the IntegrationServer dashboard i.e. <ISDashboardCRName>-dash
-
-newDomain: Service name of the IntegrationRuntime dashboard i.e. <IRDashboardCRName>-dash
i.e. “AppConnectCrConverter -name customerdb -namespace ace-migration -oldDomain db-quickstart-is-dash -newDomain db-quickstart-ir-dash”
To migrate a local IntegrationServer CR yaml file you would use:
i.e. “AppConnectCrConverter -resourceYaml /tmp/myIS.yaml -oldDomain db-quickstart-is-dash -newDomain db-quickstart-ir-dash”
This should produce logs similar to below and a yaml file for an IntegrationRuntime (This is reading directly from Kube)
2024/04/16 09:26:02 CommandLine Parameters:
2024/04/16 09:26:02 resourceYaml:
2024/04/16 09:26:02 name: customerdb
2024/04/16 09:26:02 namespace: ace-migration
2024/04/16 09:26:02 Reading YAML from cluster with resource name customerdb, namespace ace-migration
2024/04/16 09:26:03 IntegrationRuntime CR read from cluster
2024/04/16 09:26:03 Empty objects removed
2024/04/16 09:26:03 IntegrationRuntime CR written to customerdb-IR.yaml
2024/04/16 09:26:03 Finished creating your IntegrationRuntime CR - customerdb-IR.yaml
Examine the IntegrationRuntime CR to make sure it looks sensible and take note of any warnings.
Add the following annotation to your existing IntegrationServer. Once applied it will stop your IntegrationServer reconciling so if any changes are made they will not be picked up. This is to ensure the configuration is static during migration.
metadata:
annotations:
appconnect.ibm.com/pause: "true"
Create your new IntegrationRuntimes by running `oc apply -f ./customerdb-IR.yaml`. This will start your IntegrationRuntime with routes disabled. This means that it will not process any http based input workloads. The existing route will be routing all traffic to your old Integration Server
NOTE1 - Any event triggered flows will become active once you have created this resource.
NOTE2 - Due to the route being disabled the “TryIt” capability in the ACE Dashboard will not work until the routes are enabled
Once the IntegrationRuntime has created make sure it all looks as expected.
Once you are happy that the flow started cleanly edit the IntegrationRuntume CR and enable routes. Making this change will trigger all the traffic over to the new IntegrationRuntime.
spec:
routes:
disabled: false
Once you are happy that everything is working as expected delete your existing IntegrationServer i.e. `oc delete IntegrationServer customerdb`.
If you find you are hitting problems you can switch back the traffic by:
1) Update the integrationRuntime CR with
spec:
routes:
disabled: false
2) Trigger a reconcile of the IntegrationRuntime CR by removing the “pause” annotation
apiVersion: appconnect.ibm.com/v1beta1
kind: IntegrationServer
metadata:
annotations: {}
Hopefully once you have completed the steps above you will have been able to successfully move to the IntegrationRuntime custom resource and then start taking advantage of all the great features we are adding.