Integration assembly deployment

An integration assembly is an instance type that you can use to deploy multiple instances of other IBM Cloud Pak® for Integration instances and components 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 and high availability.

Before you begin

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). For more information, 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.
You have installed all operators for the components that you are deploying with the assembly. Operators that are used by assemblies (followed by the component name used in the assembly) are:
- IBM App Connect (IntegrationRuntime)
- IBM Event Streams (EventStreams)
- IBM MQ (QueueManager)
- A certificate manager, such as cert-manager Operator for Red Hat OpenShift (QueueManager)
If you want to allow Integration assembly templates to be shared across your organization, Automation assets is already installed. For more information on installing Automation assets, see Automation assets deployment by using the Platform UI.

Creating an integration assembly in the Platform UI

Log in to Platform UI.
Click Create an instance.
Click Assembly, then click Next.
Use one of the following deployment options:
1. To deploy by using the default configuration for an assembly, click the tile for the deployment option that you need, then click Next. You can modify the default configuration as needed.
2. To deploy by using an existing template from Automation assets, click the Select a template tile. If you do not have Automation assets installed, a panel with an intallation link opens.
  1. After clicking the link, select a template and preview its contents.
  2. Click Create from asset.

Configuring in the Canvas

The Canvas perspective is selected by default. It opens a graphical interface on which you can drag-and-drop objects.

Click the UI form tab. Edit the fields that are mentioned in the first steps of the Configuring in the UI form section, for example Name and Storage class.
Click the Canvas tab. Drag and drop objects from the Palette, then connect and configure those objects as needed. For more information about the Canvas view, see Using the canvas to create instances and integrations.

The Cloud Pak for Integration operator supplies default configurations for each managed instance. You can customize your configuration with any part of the full specification supported by that custom resource. For more information, see Using an integration assembly.

Configuring in the UI form view

Set the following fields to configure the assembly. The UI form perspective opens a form that lets you view or modify the resource configuration.

In the Name field, enter a name for your instance of assembly.
Click to expand Namespace and select the namespace where your assembly will be deployed.
Set License Accept to true if you accept the Cloud Pak for Integration license agreement. For details, see Licensing.
For License LI, keep the default version unless you change spec.version. For details about licenses for specific versions, see the "Table of license versions" section in Licensing.
Specify the Storage class. Click Select Storage Class to select a Matching storage classes found in the dropdown that supports ReadWriteOnce (RWO) volumes. For more information, see Storage considerations.
Set any other configuration values as appropriate. The assembly supplies default configurations for each managed instance or integration. You can customize your configuration with any part of the full specification supported by that managed instance or integration. For more information, see Using an integration assembly.

Configuring in the YAML view

Click the YAML tab and update the following values:

metadata.namespace- select your project (namespace) name.
spec.license.accept- select true if you accept the Cloud Pak for Integration license agreement. For details, see Licensing.
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.
spec.storage.readWriteOnce.class - specify a storage class that supports ReadWriteOnce (RWO) volumes. For more information, see Storage considerations.
Any other configuration values, as appropriate. The assembly supplies default configurations for each managed instance or integration. You can customize your configuration with any part of the full specification supported by that managed instance or integration. For more information, see Using an integration assembly.

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

Click Create to initiate deployment. You are redirected to the home page. The assembly begins deployment and is initially in the Pending state. Click Pending to check the progress of the deployment. When the deployment completes, the status changes to Ready.

When deployed, an assembly is available as an expandable row in the instances table. The top row contains information about the assembly resource, and the nested rows contain information about each component in the assembly, such as the name and the namespace where they were deployed, and their current status.

Creating an integration assembly by using the CLI

Log into your cluster, using your OpenShift user credentials:
```
oc login
```
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
```
Create a IntegrationAssembly YAML file. For example, you could create a file called 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
```
  This command returns a list of available storage classes. For details about storage support and configuration, see Storage considerations.
- Set any other configuration values as appropriate. The assembly supplies default configurations for each managed instance. You can customize your configuration with any part of the full specification supported by that managed instance.
  Important: Once an instance is deployed through an assembly, the instance has to be managed through this assembly. Therefore, editing the custom resource of the specific instance is not permitted.
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 Using an integration assembly.
Apply the yaml file to the cluster
```
oc apply assembly.yaml
```
Get the status of the 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 be edited or deleted only in the assembly custom resource, as shown in the following examples.

High availability

To provision an assembly instance in high availability (HA) mode, set the value of spec.availability.type to HA. This setting ensures that all components managed by this assembly instance are deployed in HA mode.

Note the following:

If the spec.availability.type field in undefined, it defaults to SingleInstance.
This field is immutable, so the value can't be changed later.

Example configuration file:

spec:
  availability:
    type: HA

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 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 Using 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, when accepted for the assembly.
The Event Streams license use is set to the same setting configured for the assembly.
Persistent storage is enabled for Kafka with 10Gi, using the readWriteOnce storage class from the assembly.
Persistent storage is enabled for ZooKeeper with 2Gi, using the readWriteOnce storage class from the assembly.
The Kafka resources are set to 8Gi and 4 cpus for both the requests and limits.

Integration runtime managed integration

By default, for each managed integration of kind IntegrationRuntime, the following default configuration is used:

The integration runtime license is accepted, when accepted for the assembly.
The integration runtime has 1 or 3 pod replicas, depending on the availability type of the assembly.
The logFormat is set to basic.
The integration runtime version is set to the latest runtime version that is part of the Cloud Pak for Integration release associated with this assembly. The Cloud Pak for Integration release number is referenced in the assembly spec.version.

API managed integration

There is no default configuration for managed integrations of kind API. Add the full definition of the API that you want this assembly to manage as per the API object in Using declarative APIs.

Product managed integration

There is no default configuration for managed integrations of kind Product. Add the full definition of the Product that you want this assembly to manage as per the API object in Using declarative API Products.