Deploying an integration assembly

An integration assembly is a capability that allows you to deploy multiple instances of other IBM Cloud Pak® for Integration capabilities (such as messaging and Event Streams) from the same YAML file. This feature simplifies ease of instance creation and management, in part by supplying default configurations for complex elements, such as certificates.

Prerequisites

  • You are on a supported version of Red Hat Openshift. See Operating environment for details.

  • For online clusters, if you have not already created a secret called ibm-entitlement-key in the namespace where the instance will be created, see Applying your entitlement key.

  • An OpenShift cluster administrator has created one or more storage classes that support ReadWriteOnce (RWO). Supported storage providers include ibmc-block-gold, OpenShift Data Foundation (formerly OpenShift Container Storage), Spectrum, and Portworx. For additional details about storage support and configuration, see Storage considerations.

  • You have already installed the IBM Cloud Pak for Integration operator. If you have not already done so, see Installing the operators.

Creating an integration assembly in the OpenShift web console

  1. Log into the OpenShift web console with your OpenShift cluster admin credentials.

  2. If you installed the operators in All namespaces on the cluster mode, you must use a project other than openshift-operators in which to deploy the assembly.

    • If needed, create a new project for this purpose. Under Home > Projects, click Create Project, enter the name for your new project, and click Create.

  3. In the navigation panel, click Operators > Installed Operators.

  4. Change Project to your project (namespace) name. Click the drop-down arrow and select your project name from the list.

  5. In the list on the Installed Operators panel, find and click IBM Cloud Pak for Integration.

  6. Click the Integration Assembly tab.

  7. Click Create IntegrationAssembly. The Create IntegrationAssembly panel opens.

  8. Create the Platform UI with either the "Form view" or the "YAML view".

    Configuring in the Form view

    The Form view opens a form that lets you review and modify the resource configuration.

    1. In the Name field, enter a name for the new instance or use the default.

    2. Next to License, click the arrow to expand the license acceptance section.

    3. Set License Accept to true if you accept the Cloud Pak for Integration license. agreement. For details, see Licensing.

    4. For License LI, leave the default version unless you change spec.version. For details about specific version licenses, see the "Table of license versions" section in Licensing

    5. Specify the Storage class. Click to expand the Storage pane, click to expand the readWriteOnce pane, and click Select Storage Class to select a file storage class that supports ReadWriteOnce (RWO) volumes. Supported storage providers include ibmc-block-gold, OpenShift Data Foundation (formerly OpenShift Container Storage), Spectrum, and Portworx. For additional details about storage support and configuration, see Storage considerations.

    6. Add or remove managed instances that you want to include in this integration assembly.

    7. Set any other configuration values as appropriate. The integration assembly supplies default configurations for each managed instance. You can customize your configuration using the full specification supported by that managed instance. For more information, see Advanced configuration for an integration assembly.

    8. Click Create. You are redirected to the Integration Assembly tab, and your instance of the integration assembly is added to the list of instances in the current project (namespace).

    Configuring in the YAML view

    Update the values in the file:

    1. For metadata.namespace, select your project (namespace) name.

    2. For spec.license.accept, select true if you accept the Cloud Pak for Integration license agreement. For details, see Licensing.

    3. For spec.license, keep the default value unless you change the value for spec.version. For details about specific version licenses, consult the "Table of license versions" section in Licensing.

    4. For spec.storage.readWriteOnce.class, specify a storage class that supports ReadWriteOnce (RWO) volumes. Supported storage providers include ibmc-block-gold, OpenShift Data Foundation (formerly OpenShift Container Storage), Spectrum, and Portworx. For additional details about storage support and configuration, see Storage considerations.

    5. Add or remove managed instances that you want to include in this integration assembly.

    6. Set any other configuration values as appropriate. The integration assembly supplies default configurations for each managed instance. You can customize your configuration using the full specification supported by that managed instance. For more information, see Advanced configuration for an integration assembly.

    7. Click Create. You are redirected to the Integration Assembly tab, and your instance of the assembly is added to the list of instances in the current project (namespace).

    Important: Managed instances created with an integration assembly can only be edited or deleted (uninstalled) in the integration assembly custom resource.

Creating an integration assembly by using the CLI

  1. Log into your cluster, using your OpenShift user credentials:

    oc login
  2. If you installed the operators in All namespaces on the cluster mode, you will need to use a project other than openshift-operators in which to deploy the instance.

    • If needed, create a new project for this purpose by running:

      oc new-project <project_name>

      For example:

      oc new-project integration
  3. Create a IntegrationAssembly YAML file. For example, you could create a file called integration-assembly.yaml with the following example configuration. Update the values as indicated:

    • For metadata.namespace, enter your project (namespace) name.

    • Change the value of spec.license.accept to true if you accept the Cloud Pak for Integration license agreement. For details, see Licensing.

    • For spec.storage.readWriteOnce.class, specify a storage class that supports ReadWriteOnce (RWO) volumes. To get a list of available storage classes, run:

      oc get storageclasses

      A list of available storage classes appears. For details about storage support and configuration, see Storage considerations.

    • Set any other configuration values as appropriate. The integration assembly supplies default configurations for each managed instance. You can customize your configuration using the full specification supported by that managed instance.

    Example configuration file:

    apiVersion: integration.ibm.com/v1beta1
    kind: IntegrationAssembly
    metadata:
      name: example
      namespace: integration
    spec:
      version: 2022.4.1
      license:
        accept: true
        license: L-RJON-CJR2RX
        use: CloudPakForIntegrationNonProduction
      storage:
        readWriteOnce:
          class: <storage-class>
      managedInstances:
        list:
        - kind: QueueManager
          metadata:
            name: qm1
        - kind: EventStreams
          metadata:
            name: es1

    If you need advanced configuration options, see Advanced configuration for an integration assembly.

  4. Apply the yaml file to the cluster

    oc apply integration-assembly.yaml
  5. Get the status of the integration assembly by running the following command in the project (namespace) where it was deployed:

    oc get integrationassembly
Important: Managed instances created with an integration assembly can only be edited or deleted (uninstalled) in the integration assembly custom resource.

Queue Manager managed instance

By default, for each managed instance of kind: QueueManager, a ConfigMap named qm-<.metadata.name>-default is created. The queue manager instance contains a default mqsc/ini and an issuer and certificate that is created with a self-signed certificate (signed by the Certificate Authority for the integration assembly). The instance is configured to use the ConfigMap and certificate.

This results in the following default configuration for the queue manager instance:

  • The QueueManager license is accepted, when accepted for the integration assembly.

  • The QueueManager license use is set to Production or NonProduction, depending on the assembly license.use value.

  • Persistent storage is enabled for the QueueManager with 2Gi, using the readWriteOnce storage class from the assembly.

  • A channel named MTLS.SVRCONN is created. The channel has TLS enabled, but access to the channel is blocked by default. For examples of how to enable access (advanced configuration), see Advanced configuration for an integration assembly.

  • The web interface is enabled.

Event Streams managed instance

By default, for each managed instance of kind: EventStreams, the following default configuration is used:

  • The Event Streams license is accepted, if accepted for the integration assembly.

  • The Event Streams license use is set to the same setting configured for the integration assembly.

  • Persistent storage is enabled for Kafka with 10Gi, using the readWriteOnce storage class from the integration assembly.

  • Persistent storage is enabled for ZooKeeper with 2Gi, using the readWriteOnce storage class from the integration assembly.

  • The Kafka resources are set to 8Gi and 4 CPUs for both the requests and limits.