Upgrade considerations for IBM App Connect instances
Before you upgrade any of your existing custom resources (or instances), review the following considerations. These considerations pertain to integration tracing, the App Connect Dashboard and App Connect Designer storage types, cloud-managed accounts, integration server environment variables, BAR file versions, and paths in configuration objects.
- Implications for the removal of the flowdocAuthoring container when upgrading to App Connect Designer 12.0.12.2-r1 or later instances
- IAM implications for upgrading App Connect Designer and App Connect Dashboard instances to 12.0.10.0-r2 or later
- Accessing the updated URL for an upgraded App Connect Designer 12.0.10.0-r2 or later instance that uses a CloudPakForIntegration license
- Accessing the updated URL for an upgraded App Connect Dashboard 12.0.9.0-r3 or later instance that uses a CloudPakForIntegration license
- Upgrading a 12.0.8.0-r1 or earlier integration server that uses the Operations Dashboard for integration tracing
- Upgrading a 12.0.3.0-r1 or earlier App Connect Designer or integration server instance that uses cloud-managed accounts
- Upgrading a 12.0.1.0-r3 or earlier App Connect Designer instance to Simple Storage Service (S3) storage
- Migrating an 11.0.0.12-r1 or earlier App Connect Dashboard instance to Simple Storage Service (S3) storage
- Setting custom environment variables for integration servers that are upgraded to 12.0.1.0-r1 or later
- Matching BAR file versions to integration server versions
- Updating version-specific App Connect Enterprise paths in configuration objects
Implications for the removal of the flowdocAuthoring container when upgrading to App Connect Designer 12.0.12.2-r1 or later instances
App Connect Designer instances at version 12.0.12.2-r1 or later do not require a flowdocAuthoring container so when you upgrade from 12.0.12.0-r2 or earlier, the flowdocAuthoring pod is removed while the new ui pod starts up. During the upgrade, any flows in your Designer instance might not be visible until the ui pod is fully started.
IAM implications for upgrading App Connect Designer and App Connect Dashboard instances to 12.0.10.0-r2 or later
In IBM App Connect Operator 10.1.1 or earlier, you can control access to your App Connect Designer and App Connect Dashboard instances by using identity and access management (IAM) that IBM Cloud Pak foundational services 3.19.x or later 3.x.x provides. In IBM App Connect Operator 11.0.0 or later, IAM is implemented by using Keycloak.
- Upgrading your App Connect Designer and App Connect Dashboard instances to use IAM with Keycloak
-
For IBM App Connect Operator 11.0.0 or later, you can use IAM with Keycloak only if the IBM App Connect Operator is part of an IBM Cloud Pak for Integration deployment. Therefore, when you upgrade to IBM App Connect Operator 11.0.0 or later, you must ensure that all the required Operators for IAM are upgraded (and installed where necessary) in your environment. For information about upgrading your independent IBM App Connect Operator deployment or your Cloud Pak for Integration deployment to an IAM environment that uses Keycloak, see Upgrade considerations for identity and access management (IAM) on Red Hat OpenShift.
After all the Operators are installed or upgraded to the supported versions that are needed to enable IAM with Keycloak, you must upgrade your 12.0.10.0-r1 or earlier App Connect Designer and App Connect Dashboard instances to 12.0.10.0-r2 or later. The following requirements apply for storage, licensing, and IAM for these instances.
- Storage requirements
Keycloak requires block storage and uses the default storage class in Red Hat OpenShift.
- Before you upgrade your instances, set up the required storage as follows:
- Ensure that block storage is installed on the cluster. For more information, see Storage options in the Cloud Pak for Integration documentation.
- Set the storage class, which you want to assign to your instances, as the default class. To do
so, you can add an annotation to the metadata block in the StorageClass custom
resource (CR) as shown in the following example.
apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: rook-ceph-block annotations: storageclass.kubernetes.io/is-default-class: 'true' ...
- When you upgrade the instances, update the storage settings in their CRs as follows:
- App Connect Designer: Set the
spec.couchdb.storage.class value to the default storage class. For
example:
spec: couchdb: storage: class: rook-ceph-block size: 10Gi type: persistent-claim
- App Connect Dashboard: Set the spec.storage.class
value to the default storage class. For example:
spec: storage: class: rook-ceph-block size: 5Gi type: persistent-claim
- App Connect Designer: Set the
spec.couchdb.storage.class value to the default storage class. For
example:
- Before you upgrade your instances, set up the required storage as follows:
- License and IAM requirements
License and IAM settings in a 12.0.10.0-r1 or earlier Designer or Dashboard CR before the upgrade Result when you attempt an upgrade to 12.0.10.0-r2 or later spec.license.use set to a
CloudPakForIntegration*
valuespec.useCommonServices set to
true
(indicating IAM with IBM Cloud Pak foundational services 3.19.x or later 3.x.x)You see a warning that advises you to remove the spec.useCommonServices setting from the custom resource (CR) of the instance.
If you do not update the CR to remove spec.useCommonServices, the upgrade to 12.0.10.0-r2 or later is allowed to happen and the setting is ignored. However, the instance is flagged with a warning, which remains until you manually delete spec.useCommonServices from the CR.
By default, spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled are both set to
true
to enable IAM with Keycloak. However, these settings are not exposed in the upgraded CR.Note: You need to upgrade all of your 12.0.10.0-r1 or earlier Dashboard and Designer instances to 12.0.10.0-r2 or later.
- Storage requirements
- Upgrading your App Connect Designer and App Connect Dashboard instances in an independent IBM App Connect Operator deployment
-
If you want to upgrade from an independent deployment IBM App Connect Operator 10.1.1 or earlier to an independent deployment IBM App Connect Operator 11.0.0 or later, you can follow the instructions in Upgrading the IBM App Connect Operator from an earlier to a later Continuous Delivery (CD) version to upgrade the Operator.
After you upgrade the Operator, you can upgrade your 12.0.10.0-r1 or earlier App Connect Designer and App Connect Dashboard instances to 12.0.10.0-r2 or later. The action that you need to take to allow the upgrade to proceed will depend on whether the IAM service from IBM Cloud Pak foundational services 3.19.x or later 3.x.x was previously configured for your instances.
License and IAM settings in a 12.0.10.0-r1 or earlier Designer or Dashboard CR before the upgrade Result when you attempt an upgrade to 12.0.10.0-r2 or later spec.license.use set to an
AppConnectEnterprise*
valuespec.useCommonServices not included in the CR (indicating no IAM with IBM Cloud Pak foundational services 3.19.x or later 3.x.x)
By default, spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled are both set to
true
to enable IAM with Keycloak. However, these settings are not exposed in the upgraded CR. (As a prerequisite to using IAM, you must ensure that all the required Operators are installed and that a Keycloak installation is manually triggered.)If you want to retain the
no IAM
status for the Designer or Dashboard instance, add spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled with a value offalse
to the CR.spec.license.use set to an
AppConnectEnterprise*
valuespec.useCommonServices set to
false
(indicating no IAM with IBM Cloud Pak foundational services 3.19.x or later 3.x.x)You see a message that advises you to replace the spec.useCommonServices setting in the CR with spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled settings that are set to
false
(to indicate that you still don't require IAM). Complete this action to allow the upgrade to proceed and to retain theno IAM
status for the Designer or Dashboard instance.If you want to enable IAM with Keycloak, ensure that all the required Operators are installed and that a Keycloak installation is manually triggered. Then, remove the spec.useCommonServices setting from the CR to allow the upgrade to proceed. You do not need to add the spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled settings because they are enabled by default (with a value of
true
) even when not explicitly specified in the CR.spec.license.use set to an
AppConnectEnterprise*
valuespec.useCommonServices set to
true
(indicating IAM with IBM Cloud Pak foundational services 3.19.x or later 3.x.x)You see a message, which requests that you remove the spec.useCommonServices setting from the CR. After you remove the setting, the upgrade to 12.0.10.0-r2 or later is allowed to proceed and IAM with Keycloak is automatically enabled. (As a prerequisite to using IAM, you must ensure that all the required Operators are installed and that a Keycloak installation is manually triggered.)
For information about configuring IAM when you create Designer and Dashboard instances, see Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.
Accessing the updated URL for an upgraded App Connect Designer
12.0.10.0-r2 or later instance that uses a CloudPakForIntegration
license
The generated URL that you use to access an App Connect Designer
12.0.10.0-r2 or later instance that was created with a CloudPakForIntegration
-type
license, has a different root URL from 12.0.10.0-r1 or earlier instances. This URL change, which was
introduced in IBM App Connect Operator 11.0.0, is due to architectural changes
to the common UI elements to add simplicity, for resource reduction, and to improve resiliency and
performance.
When you upgrade any 12.0.10.0-r1 or earlier Designer instance to 12.0.10.0-r2 or later, the following implications apply for your IBM Cloud Pak for Integration deployment on Red Hat OpenShift:
- During the upgrade, there might be a short outage when the new URL for your Designer instance is not active.
- If you access your Designer instance from the IBM Cloud Pak Platform UI after the upgrade, the switch to the updated URL is automatic and you can access the instance in the usual ways.
- If you access your Designer instance from a stored bookmark after the upgrade, this link is
broken. To access the upgraded Designer instance, you can obtain its updated URL from the Red Hat
OpenShift web console or CLI, or you can use the IBM Cloud Pak Platform UI.
- To obtain the updated URL from the Red Hat
OpenShift web console,
complete the following steps:
- From a browser window, log in to the Red Hat
OpenShift Container Platform web console. Ensure
that you are in the Administrator perspective
.
- If required, select the namespace (project) in which you installed the IBM App Connect Operator.
- From the navigation, click .
- From the Installed Operators page, click IBM App Connect.
- From the
Operator details
page for the App Connect Operator, click the Designer Authoring tab. - Locate and click the name of the upgraded Designer instance to view information about its
definition and current status.
On the Details tab, the UI URL field provides the updated URL for accessing the Designer instance. You can also locate this URL under in the console navigation.
- From a browser window, log in to the Red Hat
OpenShift Container Platform web console. Ensure
that you are in the Administrator perspective
- To obtain the updated URL from the Red Hat
OpenShift CLI, complete the
following steps:
- From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
- Run the following command against the namespace (project) where the App Connect Designer instance is deployed:
oc get designerauthorings -n namespace
The output provides the URL of the Designer instance; for example:
NAME RESOLVEDVERSION URL CUSTOMIMAGES STATUS AGE cp4i-des-quickstart 12.0.10.0-r2 https://cp4i-des-quickstart-ui-ace-demo.apps.acecc-abcde.icp4i.com false Ready 5d
- To obtain the updated URL from the Red Hat
OpenShift web console,
complete the following steps:
You are typically advised to close any instances that are open in your browser before you upgrade. If a Designer instance is open during an upgrade to 12.0.10.0-r2 or later, you can no longer access that instance from the open widow after the upgrade. Instead, use the preceding methods to access the instance.
Accessing the updated URL for an upgraded App Connect Dashboard
12.0.9.0-r3 or later instance that uses a CloudPakForIntegration
license
The generated URL that you use to access an App Connect Dashboard
12.0.9.0-r3 or later instance that was created with a CloudPakForIntegration
-type
license, has a different root URL from 12.0.9.0-r2 or earlier instances. This URL change, which was
introduced in IBM App Connect Operator 10.0.0, is due to architectural changes
to the common UI elements to add simplicity, for resource reduction, and to improve resiliency and
performance.
When you upgrade any 12.0.9.0-r2 or earlier Dashboard to 12.0.9.0-r3 or later, the following implications apply for your IBM Cloud Pak for Integration deployment on Red Hat OpenShift:
- During the upgrade, there might be a short outage when the new URL for your Dashboard instance is not active.
- If you access your Dashboard instance from the IBM Cloud Pak Platform UI after the upgrade, the switch to the updated URL is automatic and you can access the instance in the usual ways.
- If you access your Dashboard instance from a stored bookmark after the upgrade, this link is
broken. To access the upgraded Dashboard instance, you can obtain its updated URL from the Red Hat
OpenShift web console or CLI, or you can use the IBM Cloud Pak Platform UI.
- To obtain the updated URL from the Red Hat
OpenShift web console,
complete the following steps:
- From a browser window, log in to the Red Hat
OpenShift Container Platform web console. Ensure that you are in the
Administrator perspective
.
- If required, select the namespace (project) in which you installed the IBM App Connect Operator.
- From the navigation, click .
- From the Installed Operators page, click IBM App Connect.
- From the
Operator details
page for the App Connect Operator, click the Dashboard tab. - Locate and click the name of the upgraded Dashboard to view information about its definition and
current status.
On the Details tab, the Admin UI field provides the updated URL for accessing the Dashboard instance. You can also locate this URL under in the console navigation.
- From a browser window, log in to the Red Hat
OpenShift Container Platform web console. Ensure that you are in the
Administrator perspective
- To obtain the updated URL from the Red Hat
OpenShift CLI, complete the
following steps:
- From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
- Run the following command against the namespace (project) where the App Connect Dashboard instance is deployed:
oc get dashboards -n namespace
The output provides the URL of the Dashboard instance; for example:
NAME RESOLVEDVERSION REPLICAS CUSTOMIMAGES STATUS URL AGE cp4i-ace-dashboard 12.0.9.0-r3 1 false Ready https://cp4i-ace-dashboard-ui-ace-dashboard-ns.apps.acecc-abcde.icp4i.com 7d1h
- To obtain the updated URL from the Red Hat
OpenShift web console,
complete the following steps:
You are typically advised to close any instances that are open in your browser before you upgrade. If a Dashboard instance is open during an upgrade to 12.0.9.0-r3 or later, you can no longer access that instance from the open widow after the upgrade. Instead, use the preceding methods to access the instance.
Upgrading a 12.0.8.0-r1 or earlier integration server that uses the Operations Dashboard for integration tracing
IBM App Connect Operator 8.2.0 removed support for the IBM Cloud Pak for Integration Operations Dashboard, which provides cross-component transaction tracing to aid with troubleshooting and latency issues in deployed integration servers. As a result, integration servers at version 12.0.8.0-r2 or later do not support the use of the Operations Dashboard for integration tracing. Support for the Operations Dashboard is also only available in IBM Cloud Pak for Integration 2022.4.1 or earlier, and it is deprecated in those versions.
If the Operations Dashboard is enabled for a 12.0.8.0-r1 or earlier integration server, and an automatic or a manual upgrade to 12.0.8.0-r2 or later is attempted, the upgrade fails with an error. The IBM App Connect Operator cannot reconcile such integration servers. To enable the upgrade to proceed without error, complete the following steps:
- Update the integration server's custom resource (CR) to disable tracing.
When tracing is enabled, the following settings apply.
spec: tracing: enabled: true namespace: namespaceName
To disable tracing, you can set spec.tracing.enabled to
false
. Alternatively, remove both the spec.tracing.enabled and spec.tracing.namespace settings from the CR since these settings are not supported in 12.0.8.0-r2 or later, and are therefore now redundant.You can use the oc edit command to update the CR settings. This command automatically opens the default text editor for your operating system or another configured editor. Update and save the YAML definition, and then close the text editor to apply the command.
oc edit integrationserver integrationserverName -n namespaceName
- Upgrade the integration server to version 12.0.8.0-r2 or later.Tip: If you want to implement tracing in 12.0.8.0-r2 or later, consider either of these options:
- Enable user or service trace for the integration server as described in Trace reference and Enabling and managing trace for a deployed integration server.
- Deploy your BAR file as an integration runtime and configure OpenTelemetry tracing to make the integration runtime deployment observable. You'll require an Observability agent or backend system such as Instana, Jaeger, or Zipkin that is configured to accept OpenTelemetry data. OpenTelemetry tracing is supported only for IBM App Connect Enterprise Toolkit integrations. For more information, see App Connect Integration Runtime reference and Configuring OpenTelemetry tracing for integration runtimes.
If you want to continue to use the Operations Dashboard for tracing an existing integration server at version 12.0.8.0-r1 or earlier, you can retain the integration server at that version. However, the integration server is assigned a Warning status because the Operations Dashboard is deprecated in 12.0.8.0-r1 or earlier.
Upgrading a 12.0.3.0-r1 or earlier App Connect Designer or integration server instance that uses cloud-managed accounts
IBM App Connect Operator 4.0.0 removed support for cloud-managed
connectors. If your existing App Connect Designer or integration server
instances are at version 12.0.3.0-r1 or earlier, and are enabled to use both local and cloud-managed
connectors (with the spec.designerFlowsOperationMode: all
setting), you will
observe an error if you try to upgrade to version 12.0.3.0-r2 or later.
Because only local connectors are supported in 12.0.3.0-r2 or later, you must take the following actions before attempting to upgrade:
- Update your 12.0.3.0-r1 or earlier App Connect Designer instance as follows:
- Update the custom resource (CR) settings of the App Connect Designer instance:
- Locate the following settings:
spec: designerFlowsOperationMode: all appConnectURL: '<Base URL of App Connect on IBM Cloud region>' ibmCloudAPIKeyValue: <IBM Cloud API key> appConnectInstanceID: <App Connect on IBM Cloud instance identifier>
or
spec: designerFlowsOperationMode: all appConnectURL: '<Base URL of App Connect on IBM Cloud region>' ibmCloudAPIKeySecret: <IBM Cloud API key secret> appConnectInstanceID: <App Connect on IBM Cloud instance identifier>
- Update these settings as follows:
spec: designerFlowsOperationMode: local
For information about updating CR settings, see App Connect Designer reference: Updating the custom resource settings for an instance.
- Locate the following settings:
- Review the existing flows in your Designer instance to check whether any nodes were set up to
connect to cloud-managed accounts that are hosted in App Connect on IBM Cloud.
If any are detected, take the relevant action to update the flow:
- If there is a corresponding local connector in your Designer instance, create a local account for use or switch to an existing local account. For more information, see Connecting to accounts.
- If a corresponding local connector is not available in your Designer instance, refactor the flow to replace the cloud-managed nodes with alternative nodes.
- Update the custom resource (CR) settings of the App Connect Designer instance:
- Update your 12.0.3.0-r1 or earlier integration server that runs a Designer integration by
completing either of the following steps:
- If there is a corresponding local connector that can be used in the Designer integration, create
a local account for use or switch to an existing local account. You can create local accounts as
configuration objects of type
Accounts
from the App Connect Dashboard, the Red Hat OpenShift web console or CLI, or the Kubernetes CLI.- To create configuration objects of type
Accounts
from the App Connect Dashboard, see Accounts type. - To create configuration objects of type
Accounts
from the Red Hat OpenShift web console or CLI, or from the Kubernetes CLI, see Configuration reference: Creating an instance and Accounts type.
Update the CR settings of the integration server by locating the following setting:s
spec: designerFlowsOperationMode: all ... configurations: - NAME_OF_SETDBPARMS_CONFIGURATION_OBJECT_FOR_YOUR_IBM_CLOUD_API_KEY
Update these settings as follows:
spec: designerFlowsOperationMode: local ... configurations: - NAME_OF_ACCOUNTS_CONFIGURATION_OBJECT_FOR_LOCAL_ACCOUNTS
For information about updating CR settings, see Integration server reference: Updating the custom resource settings for an instance or Editing the settings for a deployed integration server.
- To create configuration objects of type
- If there is no corresponding local connector that can be used in the Designer integration, use
your App Connect Designer instance to refactor the original flow that was
exported as a BAR file for deployment to the integration server. After refactoring to replace any
cloud-managed nodes, export the flow again for deployment to an integration server. When the new
integration server is successfully deployed, you can remove the previous version that referenced
cloud-managed accounts. For more information, see Deploying IBM App Connect Designer flows and APIs to integration servers and Deleting an integration server.Tip: If a BAR file of the same name already exists in the Dashboard's content server, ensure that you rename the refactored flow in your Designer instance before you export it as a BAR file.
- If there is a corresponding local connector that can be used in the Designer integration, create
a local account for use or switch to an existing local account. You can create local accounts as
configuration objects of type
Upgrading a 12.0.1.0-r3 or earlier App Connect Designer instance to Simple Storage Service (S3) storage
IBM App Connect Operator 2.0.0 introduced support for choosing a bucket in an S3 instance as the storage type for the artificial intelligence (AI) model, which the Mapping Assist incremental learning feature uses, in App Connect Designer. For S3 compatibility, your Designer version must be 12.0.1.0-r4 or later.
If you want your existing 12.0.1.0-r3 or earlier App Connect Designer
instance to start using S3 storage for the AI model (instead of persistent storage), you must first
upgrade the instance to 12.0.1.0-r4 or later. Then create a configuration of type
S3Credentials
, and edit the Designer custom resource (CR) settings to update the
incremental learning storage definition. A new base AI model is automatically created and training
is triggered on this model by using the collated data for the old 12.0.1.0-r3 or earlier AI model
that was stored in a persistent volume in the container file system. This new AI model is then added
to the specified S3 bucket and will be subsequently retrained at defined intervals by using mapping
preferences in new or edited flows.
For more information about storage types, see Designer reference: Storage. For more information about incremental learning, see Simplifying data mapping and data transformation with AI-powered suggestions.
Before you begin, ensure that the following prerequisites are met:
- Ensure that you have cluster administrator authority or have been granted the appropriate role-based access control (RBAC).
- Ensure that you have access to an S3 instance that contains an S3 bucket that you want to use for storing the AI model. For more information about the requirements for S3 storage, see Supported storage types for the AI model. Make a note of the S3 bucket name and S3 endpoint.
To provide S3 support for your 12.0.1.0-r3 or earlier App Connect Designer instance, complete the following steps:
- Upgrade to the latest version of the IBM App Connect Operator as described in Upgrading the IBM App Connect Operator from an earlier to a later Continuous Delivery (CD) version.
- Upgrade your existing 12.0.1.0-r3 or earlier App Connect Designer instance
to the latest version. To allow the upgrade to proceed, you must update the Designer version to a
12.0
-specific channel or a fully qualified version of 12.0.1.0-r4 or later, and update the license accordingly. For more information, see Upgrading your instances. - In the same namespace as your upgraded App Connect Designer instance,
create a configuration of type
S3Credentials
, which your instance can use to supply S3 credentials for accessing the S3 bucket. For more information, see Creating a configuration of type S3Credentials for use with App Connect Designer. - Modify the incremental learning storage definition for your Designer instance to support S3
storage. The following steps describe how to use the Red Hat
OpenShift CLI.
- From the namespace where the Designer instance is deployed, run the oc edit
command to partially update the instance, where instanceName is the name
(metadata.name value) of the instance.
oc edit designerauthoring instanceName
This command will automatically open the Designer CR in the default text editor for your operating system. Your existing settings for Mapping Assist and incremental learning with a
persistent-claim
storage definition for the AI model should be similar to this:apiVersion: appconnect.ibm.com/v1beta1 kind: DesignerAuthoring metadata: name: instanceName namespace: namespaceName spec: ... designerMappingAssist: enabled: true incrementalLearning: schedule: Every 15 days storage: class: className useIncrementalLearning: true ...
- To switch to S3 storage for the AI model, delete the following setting:
class: className
Replace the deleted entry with these settings for your storage type, S3 bucket, and the configuration of type
S3Credentials
that you created earlier:bucket: bucketName host: s3Endpoint s3Configuration: s3ConfigObjectName type: s3
- From the namespace where the Designer instance is deployed, run the oc edit
command to partially update the instance, where instanceName is the name
(metadata.name value) of the instance.
- Save the YAML definition and close the text editor to apply the changes.
S3Credentials
after you upgrade.- Red Hat
OpenShift web console:
Follow the procedure in Updating an instance from the Red Hat OpenShift web console. When you get to the YAML tab, overwrite the spec.designerMappingAssist.incrementalLearning.storage.class entry for persistent storage with spec.designerMappingAssist.incrementalLearning.storage.* settings for S3 storage, and then save.
- IBM Cloud Pak Platform UI:
Follow the procedure in Updating an instance from the IBM Cloud Pak Platform UI. Use the fields in the "UI form" view or switch to the YAML view to update the incremental learning storage definition. Overwrite the spec.designerMappingAssist.incrementalLearning.storage.class entry for persistent storage with spec.designerMappingAssist.incrementalLearning.storage.* settings for S3 storage, and then save.
You can switch from S3 to persistent storage for the AI model in a similar way if required by replacing existing S3 settings with the following spec.designerMappingAssist.incrementalLearning.storage.* settings:
class: className
type: persistent-claim
Migrating an 11.0.0.12-r1 or earlier App Connect Dashboard instance to Simple Storage Service (S3) storage
IBM App Connect Operator 1.5.0 introduced support for choosing a bucket in an S3 instance as the storage type for the content server that stores BAR files that you upload or import to an App Connect Dashboard. For S3 compatibility, your Dashboard version must be 12.0.1.0-r1 or later.
Switching a Dashboard's storage to use S3 storage cannot be done by updating the Dashboard's spec.storage.type setting because the value cannot be changed after the Dashboard is created. If you want your existing 11.0.0.12-r1 or earlier App Connect Dashboard instance to start using S3 storage, you will need to create an S3-compatible Dashboard and then migrate all your BAR files to the new Dashboard. After validating the migration, the new Dashboard will be ready for use and the old Dashboard can be deleted. The following steps outline this procedure. For more information about storage types, see Dashboard reference: Storage.
Before you begin, ensure that the following prerequisites are met:
- Ensure that you have cluster administrator authority or have been granted the appropriate role-based access control (RBAC).
To provide S3 support for your 11.0.0.12-r1 or earlier App Connect Dashboard instance, complete the following steps:
- Upgrade to the latest version of the IBM App Connect Operator as described in Upgrading the IBM App Connect Operator from an earlier to a later Continuous Delivery (CD) version.
- Upgrade your existing 11.0.0.12-r1 or earlier App Connect Dashboard
instance to the latest version. To allow the upgrade to proceed, you must update the Dashboard
version to a
12.0
-specific channel or fully qualified version, and update the license accordingly. For more information, see Upgrading your instances. - Back up the existing BAR files in your upgraded App Connect Dashboard
instance. Open the "BAR files" page (
) and use the backup function to download the collection of BAR files as a single .tar.gz archive to your browser's configured location. For more information, see Managing BAR files.
- Create an S3-compatible App Connect Dashboard instance in the same namespace as your upgraded App Connect Dashboard instance. For information about creating an S3-compatible Dashboard, see App Connect Dashboard reference.
- From your new App Connect Dashboard instance, open the "BAR
files" page (
) and then restore the .tar.gz BAR file archive that you downloaded from your upgraded App Connect Dashboard instance.
Restriction: The content server imposes a limit of 100 MB on the size of a BAR file that you can upload or import. This limit also applies to the size of an archive backup (.tar.gz) that can be restored.The BAR files will be restored with a
Not deployed
status. For more information, see Managing BAR files.Because the configuration objects and deployed integration servers from your upgraded App Connect Dashboard instance are in the same namespace as the new App Connect Dashboard instance, when you open the new Dashboard, you should be able to see the configuration objects and deployed integration servers in the UI. These deployed integration servers will still be linked to the upgraded App Connect Dashboard instance because the spec.barURL value for these integrations servers are still referencing the upgraded Dashboard's content server. To associate these BAR files with the new App Connect Dashboard instance, you must now update the content server location of these BAR files within each integration server custom resource (CR).
- For each integration server, use your preferred method to update the
spec.barURL value to replace the upgraded Dashboard name with the new Dashboard
name. For example, you can use the oc edit command from the Red Hat
OpenShift CLI, the kubectl edit command from a Kubernetes environment, or the Red Hat
OpenShift web
console.
The spec.barURL value of a deployed integration server (which is also the location of the BAR file in the content server) is typically generated in the following format:
https://dashboardName-dash:3443/path?token
Where:- dashboardName is the metadata.name value that defines the Dashboard name.
- path is a generated static path.
- token is a generated static token. (This token is also stored in the content server.)
For example, if the upgraded Dashboard name is
old-dashboard
, the spec.barURL value in the integration server CR could be similar to this:https://old-dashboard-dash:3443/v1/directories/CustomerDatabaseV1?0a892497-ea3b-4961-aefb-bc0c36479678
If the new Dashboard name (metadata.name value) is
new-dashboard
, the updated spec.barURL value should look like this:https://new-dashboard-dash:3443/v1/directories/CustomerDatabaseV1?0a892497-ea3b-4961-aefb-bc0c36479678
Tip: If you would like to upgrade any of your existing 11.0.0.12-r1 or earlier integration servers to the latest version, you can, while editing the integration server CR, also update the version to a12.0
-specific channel or fully qualified version, and update the license accordingly. For more information, see Upgrading your instances. - After all the spec.barURL values have been updated for your integration
servers, verify that the deployed BAR files are now associated with the new App Connect Dashboard instance.
From the new App Connect Dashboard instance, click the BAR files icon
in the navigation pane. When the "BAR files" page opens, the list of BAR files that have been deployed as integration servers should now have a
Deployed
status. - Delete the (old) upgraded App Connect Dashboard instance.
Setting custom environment variables for integration servers that are upgraded to 12.0.1.0-r1 or later
In 11.0.0.12-r1 or earlier Continuous Delivery integration server deployments, or 11.0.0.18-r1-eus or earlier Extended Update Support deployments, you can set custom environment variables from the Red Hat OpenShift web console (by navigating to ) or from the CLI (by using the oc env command). After you upgrade an integration server to a spec.version value that resolves to 12.0.1.0-r1 or later, you must use the spec.env parameter to reset any custom environment variables that were set on the 11.0.0.F-rX or 11.0.0.F-rX-eus deployment. You must also use the spec.env parameter to set any new custom environment variables on the upgraded integration server. IBM App Connect Operator 1.5.x or later is configured to trigger a reconciliation loop every 15 minutes for all custom resources, so any custom environment variables that you manually set from the Red Hat OpenShift web console or CLI will be overwritten during the reconciliation. Only environment variables that you set by using spec.env are persisted during a reconciliation.
If you upgrade the IBM App Connect Operator, but retain an existing integration server deployment at 11.0.0.F-rX or 11.0.0.F-rX-eus, any custom environment variables that are currently set on the deployment are retained.
For more information, see Integrations servers: Custom resource values and Effect of the reconciliation loop on customized settings for managed resources.
Matching BAR file versions to integration server versions
If you load an IBM App Connect Enterprise 11 development artifact into IBM App Connect Enterprise Toolkit 12 and save it, that artifact is converted to an App Connect Enterprise 12 development artifact. As such, any BAR files that are edited or created in version 12 will not be compatible with 11.0.0.12-r1 or earlier integration servers, and are supported for deployment only to 12.0.1.0-r1 or later integration servers. You must therefore ensure that you separately maintain version 11 BAR files for use with 11.0-specific integration servers, and version 12 BAR files for use with 12.0-specific integration servers.
Updating version-specific App Connect Enterprise paths in configuration objects
Releases of IBM App Connect Operator 1.4.0 or earlier are based on an image of App Connect Enterprise 11, whereas releases of IBM App Connect Operator 1.5.x or later are based on an image of App Connect Enterprise 12. As a result, the App Connect Enterprise installation path has changed from /opt/ibm/ace-11 to /opt/ibm/ace-12.
If you have upgraded the Operator to the latest version and you are using your older App Connect Enterprise 11 files, such as odbc.ini or server.conf.yaml to create configuration objects, you must manually update any version 11-specific paths to version 12-specific paths in these files before creating the configuration objects.
For example, if your odbc.ini file includes an entry such as
DRIVER=/opt/ibm/ace-11/server/ODBC/dsdriver/odbc_cli/clidriver/lib/libdb2o.so
, edit
the file to replace the /opt/ibm/ace-11 portion of the path with
/opt/ibm/ace-12.
If any existing configuration objects reference the /opt/ibm/ace-11 paths, you must also update those configuration objects to use /opt/ibm/ace-12 paths to avoid "file not found" or other errors in the integration server logs when those servers are upgraded. For information about updating configuration objects, see Configuration types for integration servers and integration runtimes.