Upgrading your instances

After upgrading to the latest Continuous Delivery (CD) version of the IBM® App Connect Operator, follow these instructions if you need to manually upgrade existing instances of the App Connect Dashboard, App Connect Designer Authoring, Switch Server, Integration Server, and Integration Runtime custom resources. You can generally upgrade by using the Red Hat® OpenShift® web console or CLI, or from the IBM Cloud Pak Platform UI in your IBM Cloud Pak for Integration deployment.

Before you begin

Note:

Close any existing App Connect Dashboard or App Connect Designer instance that is currently open in your browser before you attempt this upgrade.

If an existing instance is currently open in a browser during an upgrade to the latest (fully qualified) operand version, you will observe an error when you try to refresh the Dashboard or Designer page in the browser. As a workaround, reload the Dashboard or Designer instance by using the URL that is presented in the custom resource (CR).

About this task

After the IBM App Connect Operator is upgraded, you must manually upgrade your existing instances if you want to apply custom resources from the latest Operator version. To allow the upgrade to proceed, you must update the version and license settings as follows:

  1. Ensure that the spec.version value is set to subscribe to the 12.0 or 12.0.12 custom resource channel, or is set to a fully qualified version of 12.0.12.2-rX.
  2. Update the spec.license.licence value to an appropriate licence for the Operator version.
Important: If you are using an App Connect Dashboard instance to access or deploy your integration servers or integration runtimes, and want to upgrade your integration servers or integration runtimes to the latest version, you must also ensure that you upgrade the Dashboard to the latest version. Attempting to access upgraded integration servers or integration runtimes from Dashboard instances at an older version might lead to errors of the following type due to incompatibility issues:

Unable to load integrationservers from the cluster: ...

Unable to load integrationruntimes from the cluster: ...

Note:
  • If you are upgrading to IBM App Connect Operator 7.1.0 or later, the Red Hat OpenShift version that you upgrade to determines which channels or versions are supported for your App Connect Dashboard, App Connect Designer, switch server, integration server, and integration runtime instances. For more information, see Implications for the installed Red Hat OpenShift version.
  • If you are using the AppConnectEnterpriseNonProduction license entitlement with any of your existing instances that you want to upgrade, you will need to switch to one of the supported 12.0.12.2-rX license entitlements.

    The IBM App Connect Enterprise Developer Edition license entitlement is not valid for use with channels or versions that resolve to 12.0.12.2-rX, so if spec.license.use is currently set to AppConnectEnterpriseNonProduction, you will need to overwrite it with a valid value for 12.0.12.2-rX.

    The AppConnectEnterpriseNonProduction license is valid only for instances at a 12.0.4.0-r2 or earlier version that is supported in the IBM App Connect Operator 6.2.0 or earlier release.

You can upgrade any of your existing App Connect Dashboard, App Connect Designer, integration server, integration runtime, and switch server instances by using the Red Hat OpenShift web console or CLI. You can also upgrade integration servers and integration runtimes directly from the App Connect Dashboard. From the IBM Cloud Pak Platform UI, you can directly upgrade only App Connect Dashboard and App Connect Designer instances.

Identity and access management (IAM) implications for upgrading App Connect Designer and App Connect Dashboard to to 12.0.10.0-r2 or later:

When you try to upgrade your 12.0.10.0-r1 or earlier Designer and Dashboard instances to 12.0.10.0-r2 or later, depending on the license and IAM settings in the existing CRs, you might need to manually update the CRs to allow the upgrade to proceed. For more information, see IAM implications for upgrading App Connect Designer and App Connect Dashboard instances to 12.0.10.0-r2 or later.


Upgrading your instances from the Red Hat OpenShift CLI

Procedure

To upgrade your instances, complete the following steps:

  1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
  2. If necessary, switch to the namespace (or project) that contains the instances: 
    oc project namespace
  3. Use your preferred method to update the spec.version and spec.license.licence values for each instance that you want to upgrade. The oc patch command is used in these steps to apply a patch with some bash shell features, but you can also use oc edit, or oc apply with the appropriate YAML.
    1. Use your preferred text editor to create a YAML file that contains the updated values. To help you choose the correct values, see spec.version values and Licensing reference for IBM App Connect Operator.

      For example, if you wanted to upgrade from channel 12.0.7 or a fully qualified version (such as 12.0.7.0-r5) to the latest version, you can update spec.version to use the 12.0 channel. And to switch from an earlier 12.0.7.0-rX license (such as L-MSST-58UM6D), which is incompatible with the latest release, you can update spec.license.licence to L-QECF-MBXVLU.

      spec:
  version: '12.0'
  license:
    license: L-QECF-MBXVLU
    2. Save this file with a .yaml extension; for example, newversion.yaml.
    3. Run the following command to update the values for an instance, where:
      • kind represents the value of the kind parameter for the instance, which can be Dashboard, DesignerAuthoring, SwitchServer, IntegrationServer, or IntegrationRuntime. (These values are not case sensitive.)
      • instanceName is the name of the instance, which is shown as the metadata.name value.

      (Use the name of the .yaml file that you created.)

      oc patch kind instanceName --type='merge' --patch "$(cat filename.yaml)"

      For example:

      oc patch dashboard db-prod --type='merge' --patch "$(cat newversion.yaml)"
      Tip:
      • Other possible oc patch commands for updating the spec.version or spec.license.licence value are as follows. (These commands might show an Invalid JSON Patch message on certain operating systems.)
        oc patch kind instanceName -p '{"spec":{"version":"12.0"}}' --type=merge
        oc patch kind instanceName -p '{"spec":{"license":{"license":"licenseValue"}}}' --type=merge
        oc patch kind instanceName -p '{"spec":{"version":"12.0", "license":{"license":"licenseValue"}}}' --type=merge

      • The oc edit command will automatically open the default text editor for your operating system (for example, Notepad on Windows) or another configured editor. Update and save the YAML definition, and then close the text editor to apply the command.
        oc edit kind instanceName -n namespace

Upgrading your instances from the Red Hat OpenShift web console

Procedure

To upgrade your instances, complete the following steps:

  1. Applicable to IBM Cloud Pak for Integration only:
    1. If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
    2. From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
  2. Applicable to an IBM App Connect Operator deployment only: From a browser window, log in to the OpenShift web console for your cluster.
  3. Ensure that you are in the Administrator perspective Administrator perspective of the web console.
  4. From the navigation, click Operators > Installed Operators to display all the installed Operators in the current namespace.
  5. If necessary, select a specific namespace (project) where your IBM App Connect Operator is installed.
  6. Locate and click IBM App Connect in the table to open the Operator details view.
  7. Click the All instances tab.
  8. Complete the following steps to update the spec.version and spec.license.licence values for each instance that you want to upgrade.
    1. Click the name of the instance.
    2. Go to the YAML tab.
    3. Update the spec.version value to a channel or fully qualified version for the latest Operator, and update the spec.license.licence value to an appropriate licence for the Operator version. To help you choose the correct values, see spec.version values and Licensing reference for IBM App Connect Operator.
    4. Click Save.

Upgrading the Dashboard or Designer from the IBM Cloud Pak Platform UI

Procedure

To upgrade your App Connect Dashboard and App Connect Designer instances, complete the following steps:

  1. From a browser window, log in to the IBM Cloud Pak Platform UI.
    Tip: You can use the generated URL for a deployed IBM Cloud Pak for Integration Platform UI instance to access the Platform UI.
  2. From the Platform UI home page, open the navigation menu Navigation menu, and then click Administration > Integration instances.
    Any existing instances of App Connect Dashboard (Integration dashboard) and App Connect Designer (Integration design) are displayed on the Integration instances page. In the instances table, the entries in the Version column are either annotated with the text New version available or with an information icon (i) if new versions are available. The Status should also be shown as Ready, or as Warning if the current version is deprecated (or its storage is ephemeral).
    "Integration instances" page with Dashboard and Designer instances annotated with an (i) icon
  3. Complete either of the following steps:
    • Upgrade by using the Change version option:
      1. Click the options icon Options icon for an instance that you want to upgrade, and then click Change version from the menu. The "Change version" panel for the Designer or Dashboard instance opens.
      2. From the Available versions drop-down list, select a channel or fully qualified custom resource (or operand) version that is supported for the latest Operator. Also review and accept the licence that is presented in the License drop-down list. To help you choose the correct values, see spec.version values and Licensing reference for IBM App Connect Operator.
        Tip: The display names in the License drop-down list within the Change version panel map directly to the spec.license.license values. In the Licensing reference for IBM App Connect Operator topic, the display names are shown in the Description and (Display name) column in the table.
      3. Click Change version to save your changes and start the upgrade.
    • Upgrade by using the Edit option. (You might choose this option if you wanted to also modify other settings; for example, if you wanted to enable Mapping Assist in your App Connect Designer instance.)
      1. Click the options icon Options icon for an instance that you want to upgrade, and then click Edit from the menu. The Edit page for the Designer or Dashboard instance opens.
      2. From the UI form or YAML view, update the Channel or version field or spec.version value to a channel or fully qualified custom resource (or operand) version for the latest Operator. Also update the License LI field or spec.license.licence value to an appropriate licence for the channel or version. To help you choose the correct values, see spec.version values and Licensing reference for IBM App Connect Operator.
      3. Optional. Update any other settings as required.
      4. Click Update to save your changes and start the upgrade.
    You are redirected to the Integration instances page. In the instances table, the entry in the Version column shows the updated version when the upgrade completes.

Upgrading integration servers or integration runtimes directly from the App Connect Dashboard

From your App Connect Dashboard instance, you can change the versions of your integration servers or integration runtimes from the options menu Options menu on the tile if required. This capability provides a way for you to upgrade your integration servers or integration runtimes after the IBM App Connect Operator has been upgraded.

For more information, see Changing the version of a deployed integration server.

Useful commands for checking or verifying your versions and license values

Use these commands to check your versions and license values if required before upgrading, or to verify that your intended values have been applied after the upgrade.

Example

In these commands, the value of kind can be any of: Dashboard, DesignerAuthoring, SwitchServer, IntegrationServer, or IntegrationRuntime. (These values are not case sensitive.) The instanceName variable denotes the name of the instance that is specified as the metadata.name value.

If necessary, include the -n namespace setting.

  • This command lists existing instances of a specific kind and shows which App Connect versions are running.

    The output displays the running App Connect versions in the RESOLVEDVERSION column.

    oc get kind

    Examples:

    oc get IntegrationServer
NAME                        RESOLVEDVERSION   REPLICAS   AVAILABLEREPLICAS   CUSTOMIMAGES   STATUS   AGE
is-01-quickstart            12.0.5.0-r4       1          1                   false          Ready    8d
des-ma-johndoe-designer     12.0.5.0-r4       1          1                   false          Ready    5d4h
des-leemajor-designer       12.0.5.0-r4       1          1                   false          Ready    2d1h
designer-josie-designer     12.0.5.0-r4       1          1                   false          Ready    7d3h
baton-test-upgrade-server   12.0.5.0-r1-lts   1          1                   false          Ready    20d
    oc get dashboard
NAME               RESOLVEDVERSION   REPLICAS   CUSTOMIMAGES   STATUS   URL                                                                                                AGE
db-01-quickstart   12.0.6.0-r1       1          false          Ready    https://cpd-cp4i.apps.acecc-cd.acme.com/integration/run/integrations/ace-fiona/db-01-quickstart/   5d7h
db-02-quickstart   12.0.6.0-r1       1          false          Ready    https://cpd-cp4i.apps.acecc-cd.acme.com/integration/run/integrations/ace-fiona/db-02-quickstart/   4d23h


  • This command lists the spec and status settings of an existing instance and shows what versions can be chosen, and which one is active:
    oc get kind instanceName -o yaml

    In the output, status.versions.available identifies the available channels and fully qualified versions as well as licensing details, and status.reconciled identifies the App Connect version that is running.

    Example:

    oc get integrationserver is-01-quickstart -o yaml -n ace-dhruv2
apiVersion: appconnect.ibm.com/v1beta1
kind: IntegrationServer
metadata:
  creationTimestamp: "2022-10-26T09:40:51Z"
  generation: 1
  managedFields:
  - apiVersion: appconnect.ibm.com/v1beta1
    fieldsType: FieldsV1
...
    time: "2022-10-26T09:40:51Z"
  name: is-01-quickstart
  namespace: ace-dhruv2
  resourceVersion: "15831068"
  uid: b3cb817b-1af9-4a62-98ab-d98fc32831e5
spec:
  adminServerSecure: true
  barURL: https://db-01-quickstart-dash:3443/v1/directories/Schedular-1?1989666c-5de3-42f4-b790-ec7be16a61eb
  configurations: []
  createDashboardUsers: true
  designerFlowsOperationMode: local
  designerFlowsType: event-driven-or-api-flows
  enableMetrics: true
  license:
    accept: true
    license: L-APEH-CFZE47
    use: AppConnectEnterpriseProduction
  pod:
    containers:
      runtime:
        resources:
          limits:
            cpu: 300m
            memory: 368Mi
          requests:
            cpu: 300m
            memory: 368Mi
  replicas: 1
  router:
    timeout: 120s
  service:
    endpointType: http
  version: "12.0"
status:
  availableReplicas: 1
  conditions:
  - lastTransitionTime: "2022-10-31T17:29:23Z"
    message: integrationserver is ready
    reason: Deployed
    status: "True"
    type: Ready
  customImages: false
  endpoints:
  - name: http endpoint
    type: api
    uri: http://is-01-quickstart-http-ace-dhruv2.apps.acecc-cd-410.acme.com
  - name: https endpoint
    type: api
    uri: https://is-01-quickstart-https-ace-dhruv2.apps.acecc-cd-410.acme.com
  labelSelector: release=is-01-quickstart
  phase: Ready
  replicas: 1
  supportsTraceCustomResource: true
  traceEnabled: {}
  versions:
    available:
      channels:
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.6.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CFZE47)
          matchesCurrentType: true
          name: L-APEH-CFZE47
        name: "12.0"
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.6.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CFZE47)
          matchesCurrentType: true
          name: L-APEH-CFZE47
        name: 12.0.6
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.6.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CFZE47)
          matchesCurrentType: true
          name: L-APEH-CFZE47
        name: 12.0-lts
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.6.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CFZE47)
          matchesCurrentType: true
          name: L-APEH-CFZE47
        name: 12.0.6-lts
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.5.0 - Sept 2022
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CCHL5W)
          matchesCurrentType: true
          name: L-KSBM-CJ2KWU
        name: 12.0.5
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.5.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CCHL5W)
          matchesCurrentType: true
          name: L-APEH-CCHL5W
        name: 12.0.5-lts
      - licenses:
        - displayName: IBM App Connect Enterprise for Developers 12.0.4.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-C9NCDM)
          name: L-APEH-C9NCDM
        - displayName: IBM App Connect Enterprise 12.0.4.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-C9NCK6)
          matchesCurrentType: true
          name: L-APEH-C9NCK6
        name: 12.0.4
      - licenses:
        - displayName: IBM App Connect Enterprise for Developers 11.0.0.18
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CEKEQ6)
          name: L-APEH-CEKEQ6
        - displayName: IBM App Connect Enterprise 11.0.0.18
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CEKET7)
          matchesCurrentType: true
          name: L-APEH-CEKET7
        name: 11.0.0-eus
      - licenses:
        - displayName: IBM App Connect Enterprise for Developers 11.0.0.18
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CEKEQ6)
          name: L-APEH-CEKEQ6
        - displayName: IBM App Connect Enterprise 11.0.0.18
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CEKET7)
          matchesCurrentType: true
          name: L-APEH-CEKET7
        name: 11.0.0.18-eus
      versions:
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.6.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CFZE47)
          matchesCurrentType: true
          name: L-APEH-CFZE47
        name: 12.0.6.0-r1
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.6.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CFZE47)
          matchesCurrentType: true
          name: L-APEH-CFZE47
        name: 12.0.6.0-r1-lts
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.5.0 - Sept 2022
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CCHL5W)
          matchesCurrentType: true
          name: L-KSBM-CJ2KWU
        name: 12.0.5.0-r4
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.5.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CCHL5W)
          matchesCurrentType: true
          name: L-APEH-CCHL5W
        name: 12.0.5.0-r3
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.5.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CCHL5W)
          matchesCurrentType: true
          name: L-APEH-CCHL5W
        name: 12.0.5.0-r2
      - licenses:
        - displayName: IBM App Connect Enterprise 12.0.5.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CCHL5W)
          matchesCurrentType: true
          name: L-APEH-CCHL5W
        name: 12.0.5.0-r1-lts
      - licenses:
        - displayName: IBM App Connect Enterprise for Developers 12.0.4.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-C9NCDM)
          name: L-APEH-C9NCDM
        - displayName: IBM App Connect Enterprise 12.0.4.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-C9NCK6)
          matchesCurrentType: true
          name: L-APEH-C9NCK6
        name: 12.0.4.0-r2
      - licenses:
        - displayName: IBM App Connect Enterprise for Developers 12.0.4.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-C9NCDM)
          name: L-APEH-C9NCDM
        - displayName: IBM App Connect Enterprise 12.0.4.0
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-C9NCK6)
          matchesCurrentType: true
          name: L-APEH-C9NCK6
        name: 12.0.4.0-r1
      - licenses:
        - displayName: IBM App Connect Enterprise for Developers 11.0.0.18
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CEKEQ6)
          name: L-APEH-CEKEQ6
        - displayName: IBM App Connect Enterprise 11.0.0.18
          link: https://www-03.ibm.com/software/sla/sladb.nsf/searchlis/?searchview&searchorder=4&searchmax=0&query=(L-APEH-CEKET7)
          matchesCurrentType: true
          name: L-APEH-CEKET7
        name: 11.0.0.18-r1-eus
    reconciled: 12.0.6.0-r1