This document provides instructions for backing up your IBM App Connect specific data from an Red Hat OpenShift cluster and how to restore them in case of scenarios such as Disaster Recovery. You might also find this useful if you want to copy your App Connect topology from one namespace to another on the same cluster or to setup an equivalent topology on to another cluster.
It’s worth noting that in an purist cloud-native deployment, all the artefacts mentioned below would in fact live in source control. In true GitOps style, we could re-create our deployment anywhere simply by running the relevant CICD pipelines and pointing them to the appropriate environment. However, we don’t live in a perfect world, and sometimes we do need to know how to extract configuration from an existing environment. This document explains how you would go about that.
The examples here are based on the Red Hat OpenShift Kubernetes command line, but they would be largely the same for App Connect on any Kubernetes platform (although using the command kubectl instead). We assume that you are using the IBM App Connect Operator and its associated container image to perform your integration deployment.
While Red Hat provides backup of project related resources it is the responsibility of the user to back up application-specific data for example App Connect configuration or MQ configuration.
To prepare your deployment for disaster, complete this task to copy the App Connect deployment settings:
- Configuration Objects
- Customer Resource Definitions of IS, Dashboard
- BAR Files
- Designer Authoring flows
- Switch Server Definition
Let us now look at the commands and instructions to backup each of these items.
Prerequisites
You must have [jq](https://stedolan.github.io/jq/download/) version 1.6 or greater installed on your computer.
Check the version using jq --version.
Ensure that you have logged into your cluster from your terminal by running oc login.
Backing up App Connect Resources:
A script to backup configuration objects provided by the product and is available to download from IBM Docs at here : https://www.ibm.com/docs/en/app-connect/containers_cd?topic=ddtiis-backing-up-restoring-configuration-objects-in-red-hat-openshift
Follow the instructions in the README.md file to backup the config objects.
$ backupconfigs.sh <namespace>
This will create a backup of all your configurations in the form of a .json file in the current directory. The filename will be in the format : configbackup-27-08-2022_11-44-49.json
- Integration Server Custom Resource Definitions (CRs)
To backup all Integration Servers:
$ oc get IntegrationServer -o yaml -n <namespace>
To backup Specific Integration Server:
$ oc get IntegrationServer/<IS name> -o yaml -n <namespace>
$ oc get Dashboard/<dashboard name> -o yaml -n <namespace>
The bar files can be hosted on external repo (like github or jfrog) or in ACE Dashboard’s content server.
-
- If you have hosted your BARs on external repo, then there is no extra action needed here to backup BAR files. The BarAuth configuration that is backed up with Configuration Backup script would help access the BAR files again using the same credentials from your new/target cluster or namespace.
-
- If you are using ACE dashboard to store the BAR files (i.e. in the Content Server) then you will need to export bars from inside dashboard as shown below:
- In the ACE Dashboard, go to BAR Files panel from the left hand side menu.
- Click on Backup arrow as highlighted below
- It will download a zip file with all the BAR files currently attached to your dashboard instance.
- SwitchServer Custom Resource
If you have created a switch server resources for using with callable flows, you can backup its definition using:
$ oc get SwitchServer -o yaml -n <namespace>
Recovering from a disaster
To Restore the configuration on another cluster or namespace or Disaster Recovery site:
Ensure that App Connect Operator (same version as the one the backup was taken from) is installed in the target cluster (and namespace) where you will be restoring the configuration and other resources.
Here are the steps to restore the resources. Ensure you maintain the sequence as given below for restoring objects.
- Log in to the target cluster from your terminal by running oc login.
Using the config object json file obtained during the backup stage, run following command to restore the configuration objects.
$ oc apply --namespace <namespace> -f configbackup-27-08-2022_11-44-49.json
Using the yaml file obtained during the backup stage, restore the dashboard using:
$ oc apply -f <dashboard.yaml> -n <namespace>
Upon successful deployment of dashboard, the output would look like :
$ oc get Dashboard
NAME RESOLVEDVERSION REPLICAS CUSTOMIMAGES STATUS URL AGE
ace-dashboard 12.0.4.0-r2 1 false Ready https://ace-dashboard-ui-ace-new.apps.cp4i-india-l3.cp.fyre.ibm.com 50s
Note : If you are restoring the CRs to a namespace that is different from the one the backup was taken from, then you will need to update the backed up yaml definition with the new namespace name. For example : In the backup definition,
apiVersion: appconnect.ibm.com/v1beta1
kind: Dashboard
metadata:
name: ace-dashboard
namespace: ace
and you intend to restore it to a namespace (on same cluster or different cluster ) say ‘ace-new’, then update the Dashboard CR yaml as :
apiVersion: appconnect.ibm.com/v1beta1
kind: Dashboard
metadata:
name: ace-dashboard
namespace: ace-new
Similar concept would apply to the other CRs like IntegrationServer , SwitchServer, Trace, DesignerAuthoring.
If you had taken backup of BAR files from ACE Dashboard, then you can restore them using Restore Bar option in dashboard UI
Clicking on the restore icon will open a new diaglog box prompting for the backup file.
Input the zip file of the BARs that was generated during backup procedure and click Restore.
Using the yaml obtained during backup stage, run following command:
$ oc apply -f switchserver.yaml -n <namespace>
$ oc apply -f intServer.yaml -n <namespace>
Check the status of Integration Servers to ensure they are in ‘Ready’ state.
$ oc get IntegrationServer
NAME RESOLVEDVERSION REPLICAS AVAILABLEREPLICAS CUSTOMIMAGES STATUS AGE
auto-scale-app 12.0.4.0-r2 1 0 false Ready 51s
database-app 12.0.4.0-r2 1 0 false Ready 51s
tcpip-client 12.0.4.0-r2 1 0 false Ready 51s
tcpip-server 12.0.4.0-r2 1 0 false Ready 51s
Conclusion:
While the procedure described above helps in taking the backup of the App Connect resources, there may be dependent product components in OCP cluster that your ACE message flows may be dependent on , for example, IBM MQ. The user would need to follow the respective product’s guidelines in taking the backup of the artifacts to ensure the successful restoration of the App Connect environment in case of a disaster.
As noted at the beginning, ideally all the above configuration would already live in source control, and we could recreate a deployment simply by re-directing our pipelines to a new environment. However, sometimes it is necessary to know how to get configuration directly from an existing environment.
Reference:
For a similar guide to backing up an API Connect environment see: https://www.ibm.com/docs/en/api-connect/10.0.5.x_lts?topic=integration-preparing-disaster-recovery-cloud-pak
Acknowledgement and thanks to Kim Clark for reviewing and providing valuable inputs to this article.